AgentKit智能体输出不符合预期如何调优

AgentKit输出异常时，需要从提示结构、工具定义、执行链路这三个方面同步排查问题：强化system_prompt的强制格式与禁止行为指令；校准工具schema与OpenAPI描述的一致性；注入post_validator来校验输出的忠实度；启用LangSmith来追踪定位失真节点。

AgentKit智能体输出不符合预期，说明模型在规划、工具调用或上下文理解环节已出现偏差，必须从提示结构、工具定义、执行链路三处同步切入定位，不能只改提示词就重试。

检查系统提示是否具备强约束力

打开agentkit配置里的system_prompt文件，看看里面有没有明确的「禁止行为」和「强制格式」的指令。比如说，如果输出应该是JSON格式，但实际返回的却是自然语言解释，那么提示里就得写清楚：

删掉所有“请”“希望”“尽量”类弱动词，全部替换为“必须”“禁止”“仅允许”。AgentKit 不解析礼貌用语，它只响应确定性指令。

验证方式：用 curl 直接向本地 agentkit serve 接口发送最小测试请求，观察 raw output 是否仍含冗余文本。

重校准工具 Schema 与描述一致性

方法一：比对工具注册定义与实际调用日志

进入 tools/ 目录，打开对应工具的 Python 文件（如 search_db.py），检查其 schema 字段是否与运行时捕获的失败调用日志完全一致——尤其是参数名大小写、嵌套层级、必填项 "required": ["query"] 是否声明。

方法二：用 OpenAPI 格式重写描述

将原自由文本描述（如“查数据库，传关键词”）替换为标准 OpenAPI v3.0 描述，字段级标注类型、示例、枚举值。AgentKit 的工具解析器依赖结构化元数据而非语义理解，

修改后运行 agentkit tools validate 命令，确保无 warning 输出。

注入执行后校验层拦截幻觉输出

第一步：在 agentkit/pipeline/ 下新建 post_validator.py

第二步：编写校验逻辑，例如对“生成报告”类工具，强制检查输出中是否包含至少一个来自工具返回的原始字段值（如 "total_revenue"），否则抛出 ValidationError

第三步：在配置文件 config.yaml 的 pipeline 节点末尾追加该模块路径：- post_validator: true

这一步不可跳过。AgentKit 默认不校验输出忠实度，仅保证语法合法；没有此层，工具返回空结果时模型会直接编造数据，且无法被 trace 日志识别。

启用 LangSmith 追踪并定位失真节点

① 在 .env 中设置 LANGCHAIN_TRACING_V2=true 与 LANGCHAIN_ENDPOINT=https://api.smith.langchain.com

② 启动 agentkit 时添加 --tracing 参数，确保每个 Thought → Act → Observe 步骤都被打上 span 标签

③ 访问 LangSmith UI，筛选失败 trace，重点查看 tool_input 与 tool_output 是否存在字段截断、类型错配（如 string 被当 int 解析）

④ 若发现某工具调用前的 Thought 明确写了“调用 search_web”，但 trace 中实际调用的是 fetch_news，说明工具描述相似度过高，需重写两者的 description 字段，拉开语义区分度。