o i@sddlmZddlZddlZddlZddlZddlmZddl m Z m Z m Z m Z mZddlmZmZmZmZddlmZddlmZmZmZmZddlmZmZdd lmZdd l m!Z!m"Z"m#Z#dd l$m%Z%m&Z&d d l'm(Z(m)Z)m*Z*m+Z+m,Z,m-Z.m/Z/m0Z1d dl(m2Z2m3Z3m4Z4m5Z5m6Z6m7Z7d dl)m8Z8d dl9m:Z:d dl;mZ>m?Z?m@Z@d dlAmBZBmCZCd dlDmEZEmFZFd dlGmHZHmIZId dlJmKZKmLZLmMZMmNZNmOZOmPZPmQZQmRZRmSZSmTZTmUZUmVZVd dlWmXZXd dlYmZZZm[Z[d dl\m]Z]d dl^m_Z_d dl`maZaddlbmcZcmdZdmeZemfZfddlgmhZherd dlimjZjd Zke"d!Zle"d"ZmendZoejpd#d$Gd%d&d&eceKeBfZqejpd#d$Gd'd(d(e_eKZrdS))) annotationsN)Lock) AsyncIterator AwaitableCallableIteratorSequence)AbstractAsyncContextManagerAsyncExitStackasynccontextmanagercontextmanager) ContextVar) TYPE_CHECKINGAnyClassVaroverload) NoOpTraceruse_span)GenerateJsonSchema)SelfTypeVar deprecated)DEFAULT_INSTRUMENTATION_VERSIONInstrumentationNames) _agent_graph_output_system_prompt_utils exceptionsmessagesmodelsusage) CallToolsNode EndStrategyHistoryProcessorModelRequestNodeUserPromptNodecapture_run_messages) OutputToolset) ToolManager)AbstractBuiltinTool)InstrumentationSettingsInstrumentedModelinstrument_model) OutputDataT OutputSpec)AgentRunAgentRunResult) ModelSettingsmerge_model_settings) AgentDepsTDeferredToolResultsDocstringFormatGenerateToolJsonSchema RunContextToolToolFuncContextToolFuncEither ToolFuncPlain ToolParamsToolPrepareFuncToolsPrepareFunc)AbstractToolset)DynamicToolset ToolsetFunc)CombinedToolset)FunctionToolset)PreparedToolset) AbstractAgentEventStreamHandler InstructionsRunOutputDataT) WrapperAgent MCPServer) Agentr1r2r(r$r#r&r'r,rLrHrITSF)initc@seZdZUdZded<ded<ded< ded < d ed <d ed < dZded<ejddZded<ejddZ ded<ejddZ ded<ejddZ ded<ejddZ ded<ejddZ ded<ejddZded<ejddZd ed!<ejddZd"ed#<ejddZd$ed%<ejddZd&ed'<ejddZd&ed(<ejddZd)ed*<ejddZd)ed+<ejddZd,ed-<ejddZd.ed/<ejddZd)ed0<ejddZd1ed2<e 3ded3d4ed3d3d5d3d4d4d3d3d3dd6d3d3d3d7ddRdSZeedT 3ded3d4ed3d3d5d3d4d4d3d3d4dd6d3d3d3dUddXdSZ 3ded3d4ed3d3d5d3d4d4d3d3d3dd6d3d3d3d7dd[dSZeddd^d_Z e!dd`daZ"e"j#ddcdaZ"e!ddddeZ$e$j#ddfdeZ$e!ddhdiZ%e!ddjdkZ&e!ddldmZ'ddodpZ(e 3dd3d3d3d3d3d3d3d3d3d\d3d3dq dddZ)e 3dd3d3d3d3d3d3d3d3d\d3d3d dddZ)e* 3dd3d3d3d3d3d3d3d3d3d\d3d3dq dddZ)d ddZ+e,e-j.e-j.e-j.e-j.e-j.e-j.dd!ddZ/ed"ddZ0ed#ddZ0ed$ddZ0ed%ddZ0ed&ddZ0 3dd'ddZ0ed"ddZ1ed#ddZ1ed$ddZ1ed%ddZ1eddd(ddZ1 3dddd)ddZ1ed*ddZ2ed+ddZ2ed,ddZ2ed-ddZ2d.ddZ2ed/ddZ3ed3d3d3d3dde4d3ddd3dÜ d0ddZ3 3dd3d3d3d3dde4d3ddd3dÜ d1ddZ3ed2dd؄Z5ed3d3d3d3dde4d3ddd3dÜ d3dd؄Z5 3dd3d3d3d3dde4d3ddd3dÜ d4dd؄Z5ed5dd߄Z6ed\dd6dd߄Z6 3dd\dd7dd߄Z6d8ddZ7d9ddZ8d:ddZ9 3dd;ddZ:e-j.d3fdddZ=ed?ddZ=d@ddZ=dAddZ>dBddZ?ddCd d Z@e*ed  3ddDd dZAd3S(ErOatClass for defining "agents" - a way to have a specific type of "conversation" with an LLM. Agents are generic in the dependency type they take [`AgentDepsT`][pydantic_ai.tools.AgentDepsT] and the output type they return, [`OutputDataT`][pydantic_ai.output.OutputDataT]. By default, if neither generic parameter is customised, agents have type `Agent[None, str]`. Minimal usage example: ```python from pydantic_ai import Agent agent = Agent('openai:gpt-4o') result = agent.run_sync('What is the capital of France?') print(result.output) #> The capital of France is Paris. ``` 1models.Model | models.KnownModelName | str | None_model str | None_namer$ end_strategyModelSettings | Nonemodel_settingsOutputSpec[OutputDataT] _output_type%InstrumentationSettings | bool | None instrumentFz(ClassVar[InstrumentationSettings | bool]_instrument_default)reprtype[AgentDepsT] _deps_type!_output.OutputSchema[OutputDataT]_output_schemaz6list[_output.OutputValidator[AgentDepsT, OutputDataT]]_output_validators7list[str | _system_prompt.SystemPromptFunc[AgentDepsT]] _instructionsztuple[str, ...]_system_promptsz3list[_system_prompt.SystemPromptRunner[AgentDepsT]]_system_prompt_functionsz8dict[str, _system_prompt.SystemPromptRunner[AgentDepsT]] _system_prompt_dynamic_functionszFunctionToolset[AgentDepsT]_function_toolsetz OutputToolset[AgentDepsT] | None_output_toolsetz!list[AbstractToolset[AgentDepsT]]_user_toolsets#ToolsPrepareFunc[AgentDepsT] | None_prepare_tools_prepare_output_toolsint_max_result_retries_max_tool_retries%EventStreamHandler[AgentDepsT] | None_event_stream_handlerr _enter_lock_entered_countzAsyncExitStack | None _exit_stackNrGearly) output_type instructions system_prompt deps_typenamerYretriesoutput_retriestools builtin_tools prepare_toolsprepare_output_toolstoolsetsdefer_model_checkrWr]history_processorsevent_stream_handlermodelrzr{Instructions[AgentDepsT]r|str | Sequence[str]r}r~rr int | Noner]`. name: The name of the agent, used for logging. If `None`, we try to infer the agent name from the call frame when the agent is first run. model_settings: Optional model request settings to use for this agent's runs, by default. retries: The default number of retries to allow for tool calls and output validation, before raising an error. For model request retries, see the [HTTP Request Retries](../retries.md) documentation. output_retries: The maximum number of retries to allow for output validation, defaults to `retries`. tools: Tools to register with the agent, you can also register tools via the decorators [`@agent.tool`][pydantic_ai.Agent.tool] and [`@agent.tool_plain`][pydantic_ai.Agent.tool_plain]. builtin_tools: The builtin tools that the agent will use. This depends on the model, as some models may not support certain tools. If the model doesn't support the builtin tools, an error will be raised. prepare_tools: Custom function to prepare the tool definition of all tools for each step, except output tools. This is useful if you want to customize the definition of multiple tools or you want to register a subset of tools for a given step. See [`ToolsPrepareFunc`][pydantic_ai.tools.ToolsPrepareFunc] prepare_output_tools: Custom function to prepare the tool definition of all output tools for each step. This is useful if you want to customize the definition of multiple output tools or you want to register a subset of output tools for a given step. See [`ToolsPrepareFunc`][pydantic_ai.tools.ToolsPrepareFunc] toolsets: Toolsets to register with the agent, including MCP servers and functions which take a run context and return a toolset. See [`ToolsetFunc`][pydantic_ai.toolsets.ToolsetFunc] for more information. defer_model_check: by default, if you provide a [named][pydantic_ai.models.KnownModelName] model, it's evaluated to create a [`Model`][pydantic_ai.models.Model] instance immediately, which checks for the necessary environment variables. Set this to `false` to defer the evaluation until the first run. Useful if you want to [override the model][pydantic_ai.Agent.override] for testing. end_strategy: Strategy for handling tool calls that are requested alongside a final result. See [`EndStrategy`][pydantic_ai.agent.EndStrategy] for more information. instrument: Set to True to automatically instrument with OpenTelemetry, which will use Logfire if it's configured. Set to an instance of [`InstrumentationSettings`][pydantic_ai.agent.InstrumentationSettings] to customize. If this isn't set, then the last value set by [`Agent.instrument_all()`][pydantic_ai.Agent.instrument_all] will be used, which defaults to False. See the [Debugging and Monitoring guide](https://ai.pydantic.dev/logfire/) for more info. history_processors: Optional list of callables to process the message history before sending it to the model. Each processor takes a list of messages and returns a modified list of messages. Processors can be sync or async and are applied in sequence. event_stream_handler: Optional handler for events from the model's streaming response and the agent's execution of tools. Nrz<`mcp_servers` and `toolsets` cannot be set at the same time.z3`mcp_servers` is deprecated, use `toolsets` instead max_retries output_schemacSs$g|]}t|tstt|dqS)) toolset_func) isinstancerArBr5.0toolsetrxrxr Is  z"Agent.__init__..cSsg|] }t|tr|qSrx)rrArrxrxrrNs_override_name)default_override_deps_override_model_override_toolsets_override_tools_override_instructionsr)7rTr! infer_modelrVrWrYr[r]rapop TypeErrorwarningswarnDeprecationWarningrvalidate_empty_kwargsr OutputSchemar/buildrcrd_normalize_instructionsrfrstrtuplergrhrirqrr_builtin_toolsrnrorrkr_AgentFunctionToolsetrj_dynamic_toolsetsrlrrtr rrrrrrrrurvrw)rrrzr{r|r}r~rYrrrrrrrrrWr]rrrrrxrxrrsf L           TInstrumentationSettings | boolcCs |t_dS)zMSet the instrumentation options for all agents where `instrument` is not set.N)rOr^)r]rxrxrinstrument_alle zAgent.instrument_allcC|jS)z,The default model configured for this agent.rTrrxrxrrjz Agent.modelvaluecC ||_dS)zSet the default model configured for this agent. We allow `str` here since the actual list of allowed models changes frequently. Nrrrrxrxrros cCs|j}|r |jS|jS)zThe name of the agent, used for logging. If `None`, we try to infer the agent name from the call frame when the agent is first run. )rgetrrV)rname_rxrxrr~ws z Agent.namecCr)z,Set the name of the agent, used for logging.N)rVrrxrxrr~rtypecCr)z+The type of dependencies used by the agent.)rarrxrxrr}rzAgent.deps_typecCr)zjThe type of data output by agent runs, used to validate the data returned by the model, defaults to `str`.)r[rrxrxrrzrzAgent.output_typecCr)zcOptional handler for events from the model's streaming response and the agent's execution of tools.)rtrrxrxrrrzAgent.event_stream_handlerrcCs@t|jd|jd|jd|jd|jd|jd|jdS)Nz(model=z, name=z, end_strategy=z, model_settings=z, output_type=z , instrument=))r__name__rr~rWrYrzr]rrxrxr__repr__s@zAgent.__repr__) rzmessage_historydeferred_tool_resultsrr{depsrY usage_limitsr" infer_namerr user_prompt,str | Sequence[_messages.UserContent] | Noner'Sequence[_messages.ModelMessage] | NonerDeferredToolResults | Nonerr5r_usage.UsageLimits | Noner"_usage.RunUsage | Noner,Sequence[AbstractToolset[AgentDepsT]] | None$Sequence[AbstractBuiltinTool] | None>AbstractAsyncContextManager[AgentRun[AgentDepsT, OutputDataT]]c Crrrxrrrzrrrr{rrYrr"rrrrxrxriterz Agent.iter) rrrr{rrYrr"rrrOutputSpec[RunOutputDataT]AAbstractAsyncContextManager[AgentRun[AgentDepsT, RunOutputDataT]]c CrrrxrrxrxrrrOutputSpec[Any] | None(AsyncIterator[AgentRun[AgentDepsT, Any]]c #s| r|jdur|t||}~||}||}|p#|j}|j}|j }||j ks1|r=|j }|r=|j |_ ||_|j|| d}tt|}t|j|j|}| pXt} tj|rat|ng| ddd}t|j|j}t||}| pyt} |j|d\d%fd d }t|tr|j }|j j!}nd}t"}tj#tt$fd&id |d |d|rt%|ndd|d|d| d|j d|j&d|d|d|j'dg|j(| pgd|d|d|d|}tj)t|||j*|j+|j,d}|jpd}t-.|r|j/nt0}|j1|2||r|j3nd|||dd d!}z|j4||||5r.t6|ndd"d#4IdHZ} |4IdH=t7| }!|!V|!j8}"durq|5rq|rq|j9rq|:d$t|"j;t<rg|"j;nt=>t?|"j;WdIdHn 1IdHswYWdIdHn 1IdHswYWz*|r|5r|@|A|| |jB|jCW|DdSW|DdSW|DdS|Dwz'|r|5r|@|A|| |jB|jCW|DwW|DwW|Dw|Dw)'aA contextmanager which can be used to iterate over the agent graph's nodes as they are executed. This method builds an internal agent graph (using system prompts, tools and output schemas) and then returns an `AgentRun` object. The `AgentRun` can be used to async-iterate over the nodes of the graph as they are executed. This is the API to use if you want to consume the outputs coming from each LLM model response, or the stream of events coming from the execution of tools. The `AgentRun` also provides methods to access the full message history, new messages, and usage statistics, and the final result of the run once it has completed. For more details, see the documentation of `AgentRun`. Example: ```python from pydantic_ai import Agent agent = Agent('openai:gpt-4o') async def main(): nodes = [] async with agent.iter('What is the capital of France?') as agent_run: async for node in agent_run: nodes.append(node) print(nodes) ''' [ UserPromptNode( user_prompt='What is the capital of France?', instructions_functions=[], system_prompts=(), system_prompt_functions=[], system_prompt_dynamic_functions={}, ), ModelRequestNode( request=ModelRequest( parts=[ UserPromptPart( content='What is the capital of France?', timestamp=datetime.datetime(...), ) ], run_id='...', ) ), CallToolsNode( model_response=ModelResponse( parts=[TextPart(content='The capital of France is Paris.')], usage=RequestUsage(input_tokens=56, output_tokens=7), model_name='gpt-4o', timestamp=datetime.datetime(...), run_id='...', ) ), End(data=FinalResult(output='The capital of France is Paris.')), ] ''' print(agent_run.result.output) #> The capital of France is Paris. ``` Args: user_prompt: User input to start/continue the conversation. output_type: Custom output type to use for this run, `output_type` may only be used if the agent has no output validators since output validators would expect an argument that matches the agent's output type. message_history: History of the conversation so far. deferred_tool_results: Optional results for deferred tool calls in the message history. model: Optional model to use for this run, required if `model` was not set when creating the agent. instructions: Optional additional instructions to use for this run. deps: Optional dependencies to use for this run. model_settings: Optional settings to use for this model's request. usage_limits: Optional limits on model request count or token usage. usage: Optional usage to start with, useful for resuming a conversation or agents used in tools. infer_name: Whether to try to infer the agent name from the call frame if it's not set. toolsets: Optional additional toolsets for this run. builtin_tools: Optional additional builtin tools for this run. Returns: The result of the run. N)output_toolsetadditional_toolsetsr)rr"rrun_step)additional_instructions run_contextRunContext[AgentDepsT]rrUcsDgfddDIdH}dd|D}|sdSd|S)Ncsg|] }|IdHqSr)run)rfuncrrxrrMsz8Agent.iter..get_instructions..cSsg|]}|r|qSrxrx)rprxrxrrPsz )joinstrip)rpartsinstructions_functionsinstructions_literalrrget_instructionsJsz$Agent.iter..get_instructions user_depspromptnew_message_indexrrYrmax_result_retriesrWroutput_validatorsrr tool_managertracerrinstrumentation_settings)rrr{rsystem_promptssystem_prompt_functionssystem_prompt_dynamic_functionsagentzno-modelz run) model_name agent_namezgen_ai.agent.namez logfire.msg) attributesF)inputsstaterspanr final_result)rrrrUrx)Er~ _infer_nameinspect currentframe _get_model _get_deps_prepare_output_schemarzrdrkrcrrqrr _get_toolsetr*r5rbuild_agent_graphra_usageRunUsageGraphAgentStatelistr4settingsrY UsageLimits_get_instructionsrr-rrrGraphAgentDepsr/lenrWrrr'rgrhrir for_versionversionr start_spanget_agent_run_span_namerr is_recordingrr1resultinclude_content set_attributeoutputrjsondumps serialize_anyset_attributes_run_span_end_attributesrrend)#rrrzrrrr{rrYrr"rrr model_usedr output_type_rrrrgraphrmerged_settingsrrr graph_depsuser_prompt_noderinstrumentation_namesrun_span graph_run agent_runrrxrrrsa                   ,*      rr,_usage.RunUsagelist[_messages.ModelMessage]rc s|jdkrdtdd||Di}n1t|dt|t|i|}|dkr3||d<t fdd ||dDrFd |d <i| |d td idd| Dddd iidiS)NrGall_messages_eventscSsg|]}t|qSrx)r- event_to_dict)rerxrxrrsz2Agent._run_span_end_attributes..zpydantic_ai.all_messagesrzpydantic_ai.new_message_indexc3s0|]}t|tjo|jduo|jkVqdSr)r _messages ModelRequestr{)rmlast_instructionsrxr s  z1Agent._run_span_end_attributes..Tz!pydantic_ai.variable_instructionszlogfire.json_schemaobjectcSs(i|]\}}|t|trddiniqS)rarray)rr)rkvrxrxr s(z2Agent._run_span_end_attributes..rr)r properties) rrrmessages_to_otel_eventsr-rmessages_to_otel_messagesrsystem_instructions_attributesanyopentelemetry_attributesitems)rrr"rrattrsrxr6rr"s>    zAgent._run_span_end_attributes)r~rrrrr{str | _utils.UnsetAgentDepsT | _utils.Unset9models.Model | models.KnownModelName | str | _utils.Unset4Sequence[AbstractToolset[AgentDepsT]] | _utils.UnsetKSequence[Tool[AgentDepsT] | ToolFuncEither[AgentDepsT, ...]] | _utils.Unset'Instructions[AgentDepsT] | _utils.UnsetIterator[None]c cst|r|jt|}nd}t|r!|jt|}nd}t|r5|jtt|} nd} t|rF|j t|} nd} t|rW|j t|} nd} t|rm| |} |j t| } nd} zDdVW|dur~|j ||dur|j || dur|j | | dur|j | | dur|j | | dur|j | dSdS|dur|j ||dur|j || dur|j | | dur|j | | dur|j | | dur|j | ww)a]Context manager to temporarily override agent name, dependencies, model, toolsets, tools, or instructions. This is particularly useful when testing. You can find an example of this [here](../testing.md#overriding-model-via-pytest-fixtures). Args: name: The name to use instead of the name passed to the agent constructor and agent run. deps: The dependencies to use instead of the dependencies passed to the agent run. model: The model to use instead of the model passed to the agent run. toolsets: The toolsets to use instead of the toolsets passed to the agent constructor and agent run. tools: The tools to use instead of the tools registered with the agent. instructions: The instructions to use instead of the instructions registered with the agent. N)ris_setrsetSomerrr!rrrrrreset)rr~rrrrr{ name_token deps_token model_tokentoolsets_token tools_tokennormalized_instructionsinstructions_tokenrxrxroverrides`                 zAgent.overrider'Callable[[RunContext[AgentDepsT]], str]cCrrrxrrrxrxrr{$zAgent.instructions2Callable[[RunContext[AgentDepsT]], Awaitable[str]]cCrrrxrZrxrxrr{)r[Callable[[], str]cCrrrxrZrxrxrr{.Callable[[], Awaitable[str]]cCrrrxrZrxrxrr{1r^dCallable[[_system_prompt.SystemPromptFunc[AgentDepsT]], _system_prompt.SystemPromptFunc[AgentDepsT]]cCrrrxrrxrxrr{4r[2_system_prompt.SystemPromptFunc[AgentDepsT] | NoneCallable[[_system_prompt.SystemPromptFunc[AgentDepsT]], _system_prompt.SystemPromptFunc[AgentDepsT]] | _system_prompt.SystemPromptFunc[AgentDepsT]cs*|dur dfdd }|Sj||S)aDecorator to register an instructions function. Optionally takes [`RunContext`][pydantic_ai.tools.RunContext] as its only argument. Can decorate a sync or async functions. The decorator can be used bare (`agent.instructions`). Overloads for every possible signature of `instructions` are included so the decorator doesn't obscure the type of the function. Example: ```python from pydantic_ai import Agent, RunContext agent = Agent('test', deps_type=str) @agent.instructions def simple_instructions() -> str: return 'foobar' @agent.instructions async def async_instructions(ctx: RunContext[str]) -> str: return f'{ctx.deps} is the best' ``` Nfunc_+_system_prompt.SystemPromptFunc[AgentDepsT]rcsj||Srrfappendrcrrxr decorator\s z%Agent.instructions..decoratorrcrdrrdre)rrrhrxrrr{9s ! cCrrrxrZrxrxrr|gr[zAgent.system_promptcCrrrxrZrxrxrr|lr[cCrrrxrZrxrxrr|qr^cCrrrxrZrxrxrr|tr^dynamicrkcCrrrx)rrkrxrxrr|wr[csF|durd fdd }|SrJdjtjt|d|S) aDecorator to register a system prompt function. Optionally takes [`RunContext`][pydantic_ai.tools.RunContext] as its only argument. Can decorate a sync or async functions. The decorator can be used either bare (`agent.system_prompt`) or as a function call (`agent.system_prompt(...)`), see the examples below. Overloads for every possible signature of `system_prompt` are included so the decorator doesn't obscure the type of the function, see `tests/typed_agent.py` for tests. Args: func: The function to decorate dynamic: If True, the system prompt will be reevaluated even when `messages_history` is provided, see [`SystemPromptPart.dynamic_ref`][pydantic_ai.messages.SystemPromptPart.dynamic_ref] Example: ```python from pydantic_ai import Agent, RunContext agent = Agent('test', deps_type=str) @agent.system_prompt def simple_system_prompt() -> str: return 'foobar' @agent.system_prompt(dynamic=True) async def async_system_prompt(ctx: RunContext[str]) -> str: return f'{ctx.deps} is the best' ``` Nrcrdrcs2tjt|d}j|r|j|j<|S)Nrj)rSystemPromptRunnerr5rhrfri __qualname__)rcrunnerrkrrxrrhs   z&Agent.system_prompt..decoratorz"dynamic can't be True in this caserjri)rhrfrrlr5)rrrkrhrxrorr||s )  str: if 'wrong' in data: raise ModelRetry('wrong response') return data @agent.output_validator async def output_validator_deps(ctx: RunContext[str], data: str) -> str: if ctx.deps in data: raise ModelRetry('wrong response') return data result = agent.run_sync('foobar', deps='spam') print(result.output) #> success (no tool calls) ``` )rdrfrOutputValidatorr5rrZrxrxrrqs"'ToolFuncContext[AgentDepsT, ToolParams]cCrrrxrZrxrxrtoolr^z Agent.toolauto) r~ descriptionrpreparedocstring_formatrequire_parameter_descriptionsschema_generatorstrict sequentialrequires_approvalmetadatarzr{"ToolPrepareFunc[AgentDepsT] | Noner|r7r}r~type[GenerateJsonSchema]r bool | Nonerrrdict[str, Any] | None\Callable[[ToolFuncContext[AgentDepsT, ToolParams]], ToolFuncContext[AgentDepsT, ToolParams]]c Crrrx rr~rzrr{r|r}r~rrrrrxrxrrx.ToolFuncContext[AgentDepsT, ToolParams] | Nonec  8d f dd } |dur| S| |S)a( Decorator to register a tool function which takes [`RunContext`][pydantic_ai.tools.RunContext] as its first argument. Can decorate a sync or async functions. The docstring is inspected to extract both the tool description and description of each parameter, [learn more](../tools.md#function-tools-and-schema). We can't add overloads for every possible signature of tool, since the return type is a recursive union so the signature of functions decorated with `@agent.tool` is obscured. Example: ```python from pydantic_ai import Agent, RunContext agent = Agent('test', deps_type=int) @agent.tool def foobar(ctx: RunContext[int], x: int) -> int: return ctx.deps + x @agent.tool(retries=2) async def spam(ctx: RunContext[str], y: float) -> float: return ctx.deps + y result = agent.run_sync('foobar', deps=1) print(result.output) #> {"foobar":1,"spam":1.0} ``` Args: func: The tool function to register. name: The name of the tool, defaults to the function name. description: The description of the tool, defaults to the function docstring. retries: The number of retries to allow for this tool, defaults to the agent's default retries, which defaults to 1. prepare: custom method to prepare the tool definition for each step, return `None` to omit this tool from a given step. This is useful if you want to customise a tool at call time, or omit it completely from a step. See [`ToolPrepareFunc`][pydantic_ai.tools.ToolPrepareFunc]. docstring_format: The format of the docstring, see [`DocstringFormat`][pydantic_ai.tools.DocstringFormat]. Defaults to `'auto'`, such that the format is inferred from the structure of the docstring. require_parameter_descriptions: If True, raise an error if a parameter description is missing. Defaults to False. schema_generator: The JSON schema generator class to use for this tool. Defaults to `GenerateToolJsonSchema`. strict: Whether to enforce JSON schema compliance (only affects OpenAI). See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info. sequential: Whether the function requires a sequential/serial execution environment. Defaults to False. requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False. See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info. metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization. rcrwrc* jj|d d |S)NT takes_ctxr~rzrr{r|r}r~rrrrrj add_functionrg rzr|rr~r{r}rrr~rrrrxrtool_decoratorGs z"Agent.tool..tool_decoratorN)rcrwrrwrxrrr~rzrr{r|r}r~rrrrrrxrrrxs$CToolFuncPlain[ToolParams]cCrrrxrZrxrxr tool_plain^r^zAgent.tool_plain@Callable[[ToolFuncPlain[ToolParams]], ToolFuncPlain[ToolParams]]c Crrrxrrxrxrrar ToolFuncPlain[ToolParams] | Nonec  r)a Decorator to register a tool function which DOES NOT take `RunContext` as an argument. Can decorate a sync or async functions. The docstring is inspected to extract both the tool description and description of each parameter, [learn more](../tools.md#function-tools-and-schema). We can't add overloads for every possible signature of tool, since the return type is a recursive union so the signature of functions decorated with `@agent.tool` is obscured. Example: ```python from pydantic_ai import Agent, RunContext agent = Agent('test') @agent.tool def foobar(ctx: RunContext[int]) -> int: return 123 @agent.tool(retries=2) async def spam(ctx: RunContext[str]) -> float: return 3.14 result = agent.run_sync('foobar', deps=1) print(result.output) #> {"foobar":123,"spam":3.14} ``` Args: func: The tool function to register. name: The name of the tool, defaults to the function name. description: The description of the tool, defaults to the function docstring. retries: The number of retries to allow for this tool, defaults to the agent's default retries, which defaults to 1. prepare: custom method to prepare the tool definition for each step, return `None` to omit this tool from a given step. This is useful if you want to customise a tool at call time, or omit it completely from a step. See [`ToolPrepareFunc`][pydantic_ai.tools.ToolPrepareFunc]. docstring_format: The format of the docstring, see [`DocstringFormat`][pydantic_ai.tools.DocstringFormat]. Defaults to `'auto'`, such that the format is inferred from the structure of the docstring. require_parameter_descriptions: If True, raise an error if a parameter description is missing. Defaults to False. schema_generator: The JSON schema generator class to use for this tool. Defaults to `GenerateToolJsonSchema`. strict: Whether to enforce JSON schema compliance (only affects OpenAI). See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info. sequential: Whether the function requires a sequential/serial execution environment. Defaults to False. requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False. See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info. metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization. rcrrcr)NFrrrgrrxrrs z(Agent.tool_plain..tool_decoratorN)rcrrrrxrrxrrrss$CToolsetFunc[AgentDepsT]cCrrrxrZrxrxrrr^z Agent.toolset per_run_stepr AbstractToolset[str]: return FunctionToolset() ``` Args: func: The toolset function to register. per_run_step: Whether to re-evaluate the toolset for each run step. Defaults to True. rcrrcsjt|d|S)Nr)rrfrBrgrrrxrtoolset_decoratorsz(Agent.toolset..toolset_decoratorN)rcrrrrx)rrrrrxrrrs models.ModelcCs|j}r|dur|jdurtd|j}n|dur#t|}n|jdur2t|j}|_ntd|j}|durA|j }t ||S)zCreate a model configured for this agent. Args: model: model to use for this run, required if `model` was not set when creating the agent. Returns: The model used Nz`model` must either be set on the agent or included when calling it. (Even when `override(model=...)` is customizing the model that will actually be called)zD`model` must either be set on the agent or included when calling it.) rrrr UserErrorrr!rr]r^r.)rr some_modelmodel_r]rxrxrrs     zAgent._get_modelrAgent[T, OutputDataT]rPcCs|j}r |jS|S)zGet deps for a run. If we've overridden deps via `_override_deps`, use that, otherwise use the deps passed to the call. We could do runtime type checking of deps against `self._deps_type`, but that's a slippery slope. )rrr)rr some_depsrxrxrrszAgent._get_depscCs,|durgSt|tst|r|gSt|Sr)rrcallabler)rr{rxrxrr%s zAgent._normalize_instructionsrFtuple[str | None, list[_system_prompt.SystemPromptRunner[AgentDepsT]]]cCs|j}|r |j}n|j}|dur|||g}g}|D]}t|tr/| |q"| t j t |q"d |pBd}||fS)N )rrrrfcopyextendrrrrfrrlr5rr)rroverride_instructionsr{ literal_parts functions instructionliteralrxrxrr/s    zAgent._get_instructionsr1AbstractToolset[AgentDepsT] | None | _utils.UnsetrAbstractToolset[AgentDepsT]cCs|j}|r|jdurg||}t|}ddd}||}|jr)t||j}t|r0|n|j }|durF|j r@t||j }t||g}|S)zGet the complete toolset. Args: output_toolset: The output toolset to use instead of the one built at agent construction time. additional_toolsets: Additional toolsets to add, unless toolsets have been overridden. NrrrcSst|tr t|S|Sr)rrB dataclassesreplacerrxrxrcopy_dynamic_toolsetsZs  z1Agent._get_toolset..copy_dynamic_toolsets)rrrr) rrrrDvisit_and_replacernrFrrMrkro)rrrrrrrxrxrr Gs       zAgent._get_toolset%Sequence[AbstractToolset[AgentDepsT]]cCslg}|j}rt|j|j|jd}n|j}|||j}r'|j}ng|j |j }| ||S)zAll toolsets registered on the agent, including a function toolset holding tools that were registered on the agent directly. Output tools are not included. r) rrrrrrrcrjrfrrlrr)rr some_toolsfunction_toolsetsome_user_toolsets user_toolsetsrxrxrrms   zAgent.toolsetscCrrrxrrzrxrxrr r^zAgent._prepare_output_schema$_output.OutputSchema[RunOutputDataT]cCrrrxrrxrxrr r[_output.OutputSchema[Any]cCs2|dur|jr tdtj|}|S|j}|S)NzJCannot set a custom run `output_type` when the agent has output validators)rdrrrrrrc)rrzschemarxrxrr s  rc s|j4IdHF|jdkr._set_sampling_model)rrrr) r!rrrrmcprNr apply)rrr2rrxrrset_mcp_sampling_models  zAgent.set_mcp_sampling_modelz`run_mcp_servers` is deprecated, use `async with agent:` instead. If you need to set a sampling model on all MCP servers, use `agent.set_mcp_sampling_model()`.AsyncIterator[None]c Cstz||Wntjy|durYnw|4IdHdVWdIdHdS1IdHs3wYdS)aRun [`MCPServerStdio`s][pydantic_ai.mcp.MCPServerStdio] so they can be used by the agent. Deprecated: use [`async with agent`][pydantic_ai.agent.Agent.__aenter__] instead. If you need to set a sampling model on all MCP servers, use [`agent.set_mcp_sampling_model()`][pydantic_ai.agent.Agent.set_mcp_sampling_model]. Returns: a context manager to start and shutdown the servers. N)rrr)rrrxrxrrun_mcp_serverss.zAgent.run_mcp_serversr)(rrSrzrZr{rr|rr}r`r~rUrYrXrrprrrrrrrrmrrmrrrrrWr$r]r\rrrrsrr)(rrSrzrZr{rr|rr}r`r~rUrYrXrrprrrrrrrrmrrmrrrrrWr$r]r\rrrrsrr)(rrSrzrZr{rr|rr}r`r~rUrYrXrrprrrrrrrrmrrmrrrrrWr$r]r\rrrrsrr)T)r]rrr)rrS)rrSrr)rrU)rrUrr)rr)rrZ)rrsrr)rrrzrrrrrrrSr{rrr5rYrXrrr"rrrrrrrrr)rrrzrrrrrrrSr{rrr5rYrXrrr"rrrrrrrrr)rrrzrrrrrrrSr{rrr5rYrXrrr"rrrrrrrrr)rr,r"r.rr/rrp)r~rFrrGrrHrrIrrJr{rKrrL)rrYrrY)rr\rr\)rr]rr])rr_rr_)rr`)rrarrb)rkrrr`)rrarkrrrb)rrprrp)rrrrrr)rrsrrs)rrtrrt)rrurru)rrwrrw)r~rUrzrUrrr{rr|r7r}rr~rrrrrrrrrrr)rrr~rUrzrUrrr{rr|r7r}rr~rrrrrrrrrrr)rrrr)r~rUrzrUrrr{rr|r7r}rr~rrrrrrrrrrr)rrr~rUrzrUrrr{rr|r7r}rr~rrrrrrrrrrr)rrrr)rrrr)rrrrrr)rrSrr)rrrrPrrP)r{rrre)rrrr)rrrrrr)rr)rzrrrb)rzrrr)rzrrr)rr)rrrr)rrSrr)rrSrr)Br __module__rm__doc____annotations__r^rfieldrarcrdrfrgrhrirjrkrlrnrorqrrrtrurvrwrrNoneTyperr staticmethodrpropertyrsetterr~r}rzrrrr r"r rUNSETrXr{r|rqrxr8rrrrrrr rr rrrrrxrxrxrrO]sX    k5F.: %ZX  #  & rOcs^eZdZUded<gfddddfd d ZedddZedddZdfdd ZZ S)rrrrGNridrrrrprrUcs||_tj|||ddS)Nr)rsuperr)rrrrr __class__rxrrsz_AgentFunctionToolset.__init__rrcCdS)Nzrxrrxrxrrz_AgentFunctionToolset.idcCr)Nz the agentrxrrxrxrlabelrz_AgentFunctionToolset.labelrxTool[AgentDepsT]rcs(|jr |jjs tdt|dS)NzjTo use tools that require approval, add `DeferredToolRequests` to the list of output types for this agent.)rrallows_deferred_toolsrrradd_tool)rrxrrxrrs z_AgentFunctionToolset.add_tool)rrrrprrUrrr)rxrrr) rrrmrrrrrr __classcell__rxrxrrrs   r)s __future__r _annotationsrrrrasynciorcollections.abcrrrrr contextlibr r r r contextvarsr typingrrrropentelemetry.tracerrpydantic.json_schemartyping_extensionsrrrpydantic_ai._instrumentationrrrrrrrr r3r!r"r r#r$r%r&r'r(r) _tool_managerr*rr+models.instrumentedr,r-r.rr/r0rr1r2rr3r4rr5r6r7r8r9r:r;r<r=r>r?r@rrAtoolsets._dynamicrBrCtoolsets.combinedrDtoolsets.functionrEtoolsets.preparedrFabstractrHrIrJrKwrapperrLrrN__all__rPrQrr dataclassrOrrxrxrxrsh    (   8