Add support for callable output tools

[dmontagu]

Makes it possible to pass a call to ToolOutput, in which case the arguments provided by the model will be used to call that function, and that function's output is what will be returned from the agent run.

There are some additional things to do before this is ready:

• Handle the case where the function has an argument of type RunContext; this value should be injected, not obtained from the model.
• Tests
• Docs

Any concerns about the approach here would be appreciated.

Note — I think we also need to support multiple values of ToolOutput, at which point we may be able to refactor our union handling to make use of that under the hood for better consistency.

---

For context, I used this script to test:

import logfire
from logfire import ConsoleOptions

from pydantic_ai import Agent, ToolOutput, ModelRetry

logfire.instrument_pydantic_ai()
logfire.configure(send_to_logfire=False, console=ConsoleOptions(verbose=True))


def my_int_tool(x: int) -> int:
    print(f'my_int_tool called with {x}')
    if x % 2 == 0:
        raise ModelRetry('Sorry, I meant an odd number')
    return x


my_agent = Agent(
    model='openai:gpt-4o',
    output_type=ToolOutput(call=my_int_tool),
    system_prompt='You are a helpful assistant.',
)


result = my_agent.run_sync('Please return any even number')
print(result.output)

and I see this output in the console:

18:12:10.734 my_agent run
18:12:10.735   chat gpt-4o
             │ model_request_parameters={
             │                              'function_tools': [],
             │                              'allow_text_output': False,
             │                              'output_tools': [{'name': 'final_result', 'description': 'The final response which ends this conversation', 'parameters_json_schema': {'additionalProperties': False, 'properties': {'x': {'title': 'X', 'type': 'integer'}}, 'required': ['x'], 'type': 'object'}, 'outer_typed_dict_key': None, 'strict': True}],
             │                          }
my_int_tool called with 2
18:12:12.829   chat gpt-4o
             │ model_request_parameters={
             │                              'function_tools': [],
             │                              'allow_text_output': False,
             │                              'output_tools': [{'name': 'final_result', 'description': 'The final response which ends this conversation', 'parameters_json_schema': {'additionalProperties': False, 'properties': {'x': {'title': 'X', 'type': 'integer'}}, 'required': ['x'], 'type': 'object'}, 'outer_typed_dict_key': None, 'strict': True}],
             │                          }
my_int_tool called with 3
3

[github-actions]

Docs Preview

commit:	3422669
Preview URL:	https://9c8de114-pydantic-ai-previews.pydantic.workers.dev