Langchain-Chatchat Agent多工具调用实战指南

你是否在使用Langchain-Chatchat时，遇到过Agent工具调用流程复杂、配置繁琐的问题？本文将带你通过实战案例，快速掌握Agent接口的多工具调用方法，轻松实现从工具注册到任务执行的全流程落地。读完本文后，你将能够独立配置多工具调用链、解决常见的格式适配问题，并通过可视化界面监控工具执行状态。

一、Agent接口核心能力解析

Langchain-Chatchat的Agent模块是实现复杂任务自动化的核心组件，它能够根据用户需求自动选择并调用合适的工具。官方文档docs/contributing/agent.md详细介绍了Agent的架构设计，其核心优势在于：

• 多模型兼容：支持GLM-3/4、Qwen-2等开源模型的工具调用能力
• 丰富工具生态：内置16种常用工具，涵盖搜索、计算、文件处理等场景
• 灵活扩展机制：提供标准化工具注册接口，支持自定义工具开发

Agent Factory中维护着两类核心模型系列，包括GLM系列（GLM-3、GLM-4）和Qwen系列（Qwen-2、Qwen1.5），这些模型经过优化，能够高效理解工具调用指令并生成符合规范的执行计划。

二、多工具调用工作流程

Agent的工具调用流程遵循"任务解析→工具选择→执行反馈→结果生成"的闭环逻辑，具体步骤如下：

graph TD
    A[用户查询] --> B[Agent解析任务]
    B --> C{需要工具调用?}
    C -->|是| D[选择合适工具]
    D --> E[执行工具调用]
    E --> F[获取结果]
    F --> B
    C -->|否| G[生成最终回答]

在实际执行过程中，CustomAsyncIteratorCallbackHandler类负责全程监控工具状态变化，通过队列机制实时传递执行信息。状态管理采用markdown_docs/server/agent/callbacks.md中定义的Status枚举，包括start、running、complete等6种状态，确保每个工具调用环节都可追踪、可回溯。

三、实战配置步骤

3.1 工具注册实现

以数学计算器工具为例，通过@regist_tool装饰器即可快速完成注册。工具实现代码存放于libs/chatchat-server/chatchat/server/agent/tools_registry，核心代码如下：

@regist_tool(title="数学计算器")
def calculate(text: str = Field(description="a math expression")) -> float:
    """
    Useful to answer questions about simple calculations.
    translate user question to a math expression that can be evaluated by numexpr.
    """
    import numexpr
    try:
        ret = str(numexpr.evaluate(text))
    except Exception as e:
        ret = f"wrong: {e}"
    return BaseToolOutput(ret)

对于LangChain原生工具，可通过适配层快速集成，如系统命令工具：

from langchain_community.tools import ShellTool

@regist_tool(title="系统命令")
def shell(query: str = Field(description="The command to execute")):
    """Use Shell to execute system shell commands"""
    tool = ShellTool()
    return BaseToolOutput(tool.run(tool_input=query))

3.2 提示词优化策略

为提高模型调用工具的准确率，需在用户提示中明确工具调用意图。例如调用互联网搜索工具时，推荐使用以下提示模板：

请使用search_internet工具帮我查询：2025年人工智能领域最新研究进展

系统会自动识别"search_internet"关键词，并触发对应工具。对于复杂任务，可通过docs/contributing/agent.md中定义的prompt_settings.yaml文件自定义提示词模板，适配不同模型的格式要求。

3.3 前端配置界面

完成工具注册后，可通过前端界面进行可视化配置。相关界面组件位于frontend/src/features/AgentSetting/，支持工具启用/禁用、参数调整等功能。配置完成后，系统会自动生成工具调用链，用户可在聊天界面直接触发多工具协同任务。

四、常见问题与解决方案

4.1 工具返回格式错误

问题表现：工具调用后返回结果无法被Agent正确解析
解决方案：确保所有自定义工具均使用BaseToolOutput封装返回结果，格式示例：

return BaseToolOutput("计算结果：42")

4.2 模型不触发工具调用

问题表现：用户明确要求工具调用，但模型直接生成回答
解决方案：

1. 在提示词中显式指定工具名称（如"使用search_internet工具"）
2. 检查模型是否支持工具调用（目前仅GLM/Qwen系列模型支持）
3. 调整prompt_settings.yaml中的系统提示词，强化工具使用指令

4.3 异步回调异常

问题表现：工具执行状态无法实时更新
解决方案：检查CustomAsyncIteratorCallbackHandler实现，确保队列初始化正确：

self.queue = asyncio.Queue()
self.done = asyncio.Event()
self.cur_tool = {}

详细异常处理可参考markdown_docs/server/agent/callbacks.md中的错误处理章节。

五、总结与扩展

通过本文介绍的方法，你已掌握Agent多工具调用的核心技术，包括工具注册、流程配置和状态监控。项目提供了完善的文档和示例代码，建议进一步阅读：

• 官方工具开发指南：docs/contributing/agent.md
• 回调处理机制：markdown_docs/server/agent/callbacks.md
• 前端交互实现：frontend/src/features/AgentSetting/

对于高级用户，可尝试开发复合工具链，通过工具间的结果传递实现复杂业务逻辑。例如"互联网搜索→数据分析→图表生成"的全流程自动化，只需在工具描述中明确输入输出格式，Agent即可自动完成工具调度。

最后，建议通过README.md关注项目最新动态，及时获取工具生态的更新信息。