用途
agent-tool 用于为 AI 智能体添加一个新的工具（函数），让模型可以在对话过程中调用它，例如查询信息、访问外部 API 或执行某个动作。它属于 vstorm-co/full-stack-ai-agent-template 模板中的一项操作指南，适用于扩展助手能力的场景。
主要能力
- 在 backend/app/agents/tools/ 目录下定义工具函数，工具会被暴露给模型，供其在对话中途调用。
- 支持按不同 AI 框架注册工具：pydantic_ai、pydantic_deep、langchain、langgraph、deepagents。
- 可选地通过系统提示（app/agents/prompts.py）引导模型在特定情况下使用该工具。
- 可选地在前端聊天界面为工具调用结果添加自定义渲染卡片。
使用方式
- 在 backend/app/agents/tools/<tool_name>.py 中编写工具函数：
- 异步、带完整类型注解，并配有清晰的 docstring——模型看到的就是 docstring 和函数签名，因此需要精确。
- 保持纯逻辑：接收带类型的参数，返回可 JSON 序列化的结果。硬错误直接抛出异常；软失败返回结构化的 {"error": ...}，供模型推理。
- 密钥和 IO 操作应放在 settings 和服务层之后，不要内联凭据。
- 在 backend/app/agents/tools/init.py 中导出该工具（添加 import 并追加到 all，与现有的功能开关块保持一致）。
- 在对应框架的 assistant 中注册该工具：
- pydantic_ai：app/agents/assistant.py，使用 @agent.tool（需要 RunContext[Deps]）或 @agent.tool_plain（无上下文）装饰，例如： @agent.tool async def my_tool(ctx: RunContext[Deps], query: str) -> dict: """One-line description the model reads to decide when to call this.""" ...
- pydantic_deep：app/agents/pydantic_deep_assistant.py，将函数加入智能体的工具列表。
- langchain：app/agents/langchain_assistant.py，用 @tool 包装并加入传给智能体的 tools=[...]。
- langgraph：app/agents/langgraph_assistant.py，用 @tool 包装并加入绑定到图的工具列表。
- deepagents：app/agents/deepagents_assistant.py，将函数加入智能体的工具列表。
- 提示引导（可选但推荐）：如果该工具只应在特定情况下使用，在 app/agents/prompts.py 的系统提示中加一句话，让模型知道何时调用它。
- 前端渲染（可选）：工具调用会在聊天 UI 中渲染为卡片。如需定制卡片，在 frontend/src/components/chat/tool-results/ 下添加渲染器；否则使用通用卡片。
- 测试：添加 backend/tests/test_<tool_name>.py（可参考现有的 test_web_search.py / test_chart_tool.py）。工具是普通异步函数，可直接测试，无需智能体。
适用场景
需要让 AI 助手具备查询、调用外部 API 或执行动作等新能力时，可按此流程扩展工具。
限制与规则
- docstring 是与模型之间的契约，需保持准确、面向动作。
- 返回小而结构化的负载，不要把大量数据倾泻进上下文。
- 长时间运行或有副作用的工作应放在服务层（可能还需后台任务），不要内联在工具中。
- 更完整的操作说明见 docs/howto/add-agent-tool.md。
暂未提供
关于收费、价格、平台支持范围等信息，资料中暂未提供。