API ideas: Agents vs. Functions

[pietz]

If I wanted to create a data extraction tool with PydanticAI, I'd do something like this:

class Article(BaseModel):
    headline: str
    subheadline: str
    content: str
    publish_date: datetime

agent = Agent(..., system_prompt="Extract the necessary information from the input text", result_type=Article)
response = agent.run(input_text)
data = response.data

I think this is fine for the most part, but I actually find it a bit cleaner how marvin does it. They separate their agent called Assistant from non-interactive functionalities. So in marvin you'd do this:

@marvin.fn
def extract_data(input_text: str) -> Article:
    """Extract the necessary information from the input text"""

data = extract_data(input_text)

marvin also has some single purpose functions that include data generation , classification and extraction to make it even easier:

data = marvin.extract(input_text, target=Article)

My point here is two fold:

• This functionality is not really an "Agent" as there is no interaction with the user. It's basically an intelligent function.
• There is little (no?) reason to wrap it into it's own module because it's essentially stateless.

Maybe it would make sense for PydanticAI to explore functionalities and APIs outside the Agent class?

[samuelcolvin]

Interesting.

@jlowin interested in what you think?

This also relates to #300 and #120 - providing a concise abstraction for registering other agents as tools to an agent, what people in the bay area call "agent handoff".

[pietz]

@samuelcolvin I also shared some thoughts on handoff in #219 which is another area where PydanticAI's API might benefit from extension. In general, I think that marvin provides examples of some beautiful API patterns that are also based on Pydantic models to the core. swarm from OpenAI have a great pattern for handoffs and multi agents by introducing a Client on top of the agent.

[jlowin]

Thanks for the thoughts @pietz and @samuelcolvin! You raise some interesting points about API patterns and handoffs. I actually see Marvin and PydanticAI playing complementary but distinct roles in the ecosystem.

Marvin is extremely opinionated - we've explored lots of DX patterns (some worked great, others... well, they're resting peacefully in our experimental graveyard 😅). A key part of Marvin's magic isn't just its syntax but also from injecting purpose-specific system prompts under the hood, in some cases optimized for specific LLM providers (in fact the most recent version of Marvin was OpenAI-only because we just couldn't get results more universally). This kind of opinionated prompt engineering sugar feels a bit too sweet for a foundational engine like PydanticAI, which I imagine wants to stay more prompt-agnostic and may not be able to guarantee quality of such workflows otherwise.

There's definitely overlap -- Marvin's very first feature was structured outputs, which obviously PAI is the king of today. And some of the raw DX might even be appropriate, though the trouble with high-level DX is its very resistant to change (in terms of backwards compatibility).

The exciting news is that we're actually working on rebuilding Marvin and ControlFlow on top of PydanticAI! This will let us focus on what Marvin/CF do best - providing high-level, opinionated interfaces for specific agentic workflows - while leveraging PydanticAI's robust core capabilities as an engine.

NB @samuelcolvin and I haven't discussed this directly, so just my opinions here.

[samuelcolvin]

I've proposed #541 which I hope documents multi-agent applications pretty well.

Full support for graphs is coming too, see #528 and #539.

I'd love your feedback, particularly on #541 at this time.