agentkit输出异常需从提示结构、工具定义、执行链路三处同步排查：强化system_prompt的强制格式与禁止行为指令；校准工具schema与openapi描述一致性；注入post_validator校验输出忠实度；启用langsmith追踪定位失真节点。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
AgentKit智能体输出不符合预期，说明模型在规划、工具调用或上下文理解环节已出现偏差，必须从提示结构、工具定义、执行链路三处同步切入定位，不能只改提示词就重试。
检查系统提示是否具备强约束力
打开 agentkit 配置中的 system_prompt 文件，确认是否包含明确的「禁止行为」与「强制格式」指令。例如，若输出应为 JSON，但实际返回了自然语言解释，则提示中必须写明：【必须仅输出合法JSON，禁止任何解释性文字、注释或Markdown标记】。
删掉所有“请”“希望”“尽量”类弱动词，全部替换为“必须”“禁止”“仅允许”。AgentKit 不解析礼貌用语，它只响应确定性指令。
验证方式：用 curl 直接向本地 agentkit serve 接口发送最小测试请求，观察 raw output 是否仍含冗余文本。
重校准工具 Schema 与描述一致性
方法一：比对工具注册定义与实际调用日志
进入 tools/ 目录，打开对应工具的 Python 文件（如 search_db.py），检查其 schema 字段是否与运行时捕获的失败调用日志完全一致——尤其是参数名大小写、嵌套层级、必填项 "required": ["query"] 是否声明。
方法二：用 OpenAPI 格式重写描述
将原自由文本描述（如“查数据库，传关键词”）替换为标准 OpenAPI v3.0 描述，字段级标注类型、示例、枚举值。AgentKit 的工具解析器依赖结构化元数据而非语义理解，【缺失 type 或 example 字段会导致参数推断失败率上升47%】。
修改后运行 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 字段，拉开语义区分度。
