Pydantic-AI项目中Agent工具结果直接返回的技术实现

在Pydantic-AI项目中，开发者经常会遇到需要直接获取工具(tool)执行结果而不经过LLM二次处理的需求。本文将深入探讨这一技术问题的解决方案。

问题背景

在构建AI代理(Agent)时，常见的场景是：

1. 代理调用特定工具执行任务
2. 工具返回结构化数据(如Pydantic模型)
3. 期望直接将工具结果作为代理的最终输出

然而，默认情况下，Pydantic-AI的Agent会将工具结果再次输入LLM进行处理，这可能导致不必要的计算开销或结果变形。

核心解决方案

使用result_validator装饰器

Pydantic-AI提供了result_validator装饰器，可以覆盖代理的最终输出：

@new_agent.result_validator
async def direct_result_validator(
    ctx: RunContext[Deps], 
    result: list[ProductsResponse]
) -> list[ProductsResponse]:
    return [ProductsResponse(title="直接返回", handle="示例", image_url="url")]

这种方法的特点是：

• 完全绕过LLM对结果的二次处理
• 保持类型安全，强制返回结果必须符合声明的result_type
• 适用于简单场景，但灵活性较低

消息历史追踪技术

对于需要保留中间结果的复杂场景，可以通过访问消息历史来获取工具原始输出：

result = new_agent.run_sync("查询请求")
messages = result.all_messages()
tool_output = messages[-1].content  # 假设最后一条是工具输出

这种方法的优势在于：

• 可以获取完整的执行轨迹
• 适用于调试和审计场景
• 保留了LLM处理前后的完整信息

高级应用：Graph与End节点

对于需要更精细控制执行流的场景，Pydantic-AI的Graph功能提供了专业级的解决方案：

from pydantic_ai.graph import End

@new_agent.tool
async def critical_tool(ctx: RunContext) -> End:
    data = get_important_data()
    return End(final_result=data)

这种模式的特点：

• 明确声明终止点(End节点)
• 支持复杂业务流程控制
• 需要一定的学习曲线

最佳实践建议

1. 对于简单直接返回场景，优先使用result_validator
2. 需要保留中间结果时，采用消息历史追踪
3. 复杂业务流程考虑Graph架构
4. 始终确保返回类型与声明一致，避免运行时错误

性能优化提示

直接返回工具结果可以显著减少LLM调用次数，在以下场景特别有效：

• 工具输出已经是最终需要的格式
• 结果不需要LLM的进一步解释或转换
• 对响应延迟敏感的应用场景

通过合理运用这些技术，开发者可以在Pydantic-AI项目中实现更高效、更可控的代理行为。