Pydantic AI Agent工具装饰器无法注册工具的问题排查与解决

问题场景 #

我正在构建一个Pydantic AI Agent。当把工具列表作为参数传入Agent实例时，工具能正常注册并工作：

chat_agent = Agent(
    model=create_chat_model(),
    output_type=ChatResponse,
    deps_type=ChatAgentDeps,
    tools=[xyz, abc, tst],
)

但使用装饰器方式注册工具时，工具始终无法生效，尝试过tools、toolset、tool_plain等装饰器都没用：

@chat_agent.tool
def xyz(ctx: RunContext[Deps], 
    qry,
    ):
    pass

@chat_agent.tool
def abc(
    _: RunContext[Deps]
    ):
    pass

我希望用装饰器方式让代码更简洁易扩展，请问问题原因是什么，该如何修复？

可能原因 #

• 装饰器调用时机错误：如果在chat_agent实例初始化前就使用@chat_agent.tool装饰器，此时实例还未创建，装饰器无法绑定到有效对象，导致注册失败。
• 函数签名不匹配：装饰器对函数参数的类型、数量可能有严格要求，比如qry缺少类型注解，或者RunContext的泛型参数与Agent的deps_type不匹配，导致装饰器无法识别为有效工具。
• 装饰器元数据缺失：部分框架要求装饰器必须指定工具名称、描述等元数据，否则无法完成注册流程。

修复方案 #

1. 调整代码顺序，确保实例先初始化
   先创建Agent实例，再定义被装饰的工具函数，保证装饰器能绑定到已存在的实例：

   # 先初始化Agent实例
   chat_agent = Agent(
       model=create_chat_model(),
       output_type=ChatResponse,
       deps_type=ChatAgentDeps,
   )
   
   # 再用装饰器注册工具
   @chat_agent.tool
   def xyz(ctx: RunContext[ChatAgentDeps], qry: str) -> str:
       # 工具逻辑实现
       return f"处理查询内容：{qry}"
   
   @chat_agent.tool
   def abc(ctx: RunContext[ChatAgentDeps]) -> str:
       # 工具逻辑实现
       return "执行abc工具操作"
   

2. 补全函数签名的类型注解
   确保所有参数都有明确的类型注解，且RunContext的泛型参数与Agent的deps_type完全一致，让装饰器能正确识别工具的输入输出规范。

3. 显式指定工具元数据
   若框架要求，在装饰器中传入工具名称、描述等元数据，帮助AI识别和调用工具：

   @chat_agent.tool(name="查询处理工具", description="接收用户查询并返回处理结果")
   def xyz(ctx: RunContext[ChatAgentDeps], qry: str) -> str:
       pass
   

4. 改用先标记再添加的方式
   如果直接装饰无效，可先用框架的基础工具装饰器标记函数，再手动添加到Agent实例：

   from pydantic_ai_core import tool
   
   @tool
   def xyz(ctx: RunContext[ChatAgentDeps], qry: str) -> str:
       pass
   
   chat_agent = Agent(
       model=create_chat_model(),
       output_type=ChatResponse,
       deps_type=ChatAgentDeps,
   )
   chat_agent.add_tool(xyz)
   

内容的提问来源于stack exchange，提问作者Prabhleen Bindra