Add result_type to run methods

[SYNchroACK]

Fix: #564

[SYNchroACK]

Example

from pydantic import BaseModel
from pydantic_ai import Agent


class City(BaseModel):
    name: str

class Country(BaseModel):
    name: str

class Community(BaseModel):
    name: str

agent = Agent(
    model='openai:gpt-4o',
    system_prompt='You are a tour guide assistant.',
    result_type=list[City | Country | Community],
)

result = agent.run_sync(
    user_prompt='Provide me the best communities to hang out.',
    result_type=list[Community],
)

result = agent.run_sync(
    user_prompt='Provide me the best countries to visit.',
    result_type=list[Country],
)

result = agent.run_sync(
    user_prompt='I have no idea about what should I visit this winter, give me some ideas.. countries, cities, communities',
    # It will use the `result_type` defined in the agent
)

[samuelcolvin]

ha, this would break a lot of cases since agents can be run concurrently, they need to be static.

You'll need to pass the result_schema around everywhere you need to use it.

I suspect a better approach would be to move all the run logic from Agent into a new AgentRun (data)class, to avoid argument overload.

[sydney-runkle]

This seems like a good idea structurally to implement sooner rather than later

[samuelcolvin]

Actually, the correct way to do this is to add the result_schema to RunContext, see #570.

[phil65]

I think this needs a different TypeVar (+overloads)? Its not the same type as Agent´s generic TResult, its basically a type override.

[samuelcolvin]

See #564 (comment)

[phil65]

After having played around with it for while, I would strongly suggest to drop the generic return type for the Agent itself completely. I think having the typing for return type stricly "call-based" is the favourable approach, mixed approaches lead to weird ambiguities.

[sonarqubecloud]

Quality Gate failed

Failed conditions
4.7% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[SYNchroACK]

After having played around with it for while, I would strongly suggest to drop the generic return type for the Agent itself completely. I think having the typing for return type stricly "call-based" is the favourable approach, mixed approaches lead to weird ambiguities.

In case you have chance, take over this feature. ;)

[phil65]

No, sorry, I didnt mean to intervene, but Just tryin to provide some input since I ran into the same initial issues you had. I now solved it by getting rid of TResult for the "main" Agent and then introducing a second StructuredAgent.

class StructuredAgent[TDeps, TResult]:
    """Wrapper for Agent that enforces a specific result type.
    """

    def __init__(
        self,
        agent: Agent[TDeps],
        result_type: type[TResult],
        final_tool_name: str = "final_result",
        final_tool_description: str | None = None,
    ):

That allows to have a "flexible" Agent as well as a fixed "structured" agent.
SInce the interface of Agent is quite small, perhaps it could be enforced by a shared base class or a Protocol.