前言封闭告一段落开始系统复盘一个生产 Agent 到底怎么跑起来。踩坑、经验和落地最主要的是用户认可。尽量用几篇文章讲清这篇文章是系列第1篇用一次只读查询把从界面到 Trace 的整条链路先跑通。用户说“查一下生产环境order-service最近的错误日志。”最终只看到一段回答背后至少经过身份、会话、意图、模型、工具、流式事件、持久化和观测。任何一跳出错都可能表现成“Agent 答错了”。这篇先把整条链路跑通后面几篇再分头细说。案例 OpsPilot企业运维助手虚构只读工具search_resource、query_logs知识工具search_knowledge_base写工具restart_instance必须 HITLHuman-in-the-Loop人在回路确认技术栈Node.js TypeScript Vue 3一张总图POST SSEVue 对话 UI会话服务鉴权与 RequestContextAgent Runtime意图与上下文组装模型网关LLM ProviderTool Runtime业务 API / MCPRAG 检索向量库 / 全文索引Run 事件与消息持久化Trace / Metrics / Eval图上每一块管一件事别混模型负责读懂意思并给出结构化提案。Runtime 负责推进步骤、卡预算、处理中断。Tool Runtime 负责 schema参数长什么样、鉴权、幂等同一操作做一次和做多次和真正执行。会话服务负责身份、Run 生命周期和跟前端的协议。Trace/Eval 负责事后说清「到底哪一跳错了」。请求怎么进 Runtime会话 API 入口前端不应直连模型。它调用自己的会话 APIPOST /api/conversations/conv_123/runs Authorization: Beareruser-tokenContent-Type: application/json Idempotency-Key: 2d7e45b8{message:查一下生产环境 order-service 最近的错误日志}RequestContext 从哪来服务入口中间件从可信登录态拼出上下文。尤其是tenantId和userId别从模型参数或用户原文里读exporttypeRequestContext{// 入口鉴权后的请求上下文requestId:string// 本请求 ID日志与排障用traceId:string// 全链路追踪 ID跨会话/工具/模型共用tenantId:string// 租户检索过滤与数据隔离以此为准userId:string// 当前用户工具鉴权读这里不读模型参数roles:string[]// 角色用于 ACL / RAG 可见范围scopes:string[]// 允许调用的工具或资源范围deadlineAt:number// 整次 Run 截止时间戳超时取消}会话服务创建runId写入用户消息然后把 Run 交给 Runtime。HTTP 连接只是订阅进度不是任务状态本身。只读时序从提案到回灌场景用户问「查一下生产环境order-service最近的错误日志」。这是只读链路不需要 HITL通常会先定位资源再查日志最后给出带证据的回答。按谁干什么读图参与方职责VueUI发起 POST订阅 SSE渲染步骤与增量文本SessionAPI验身份、建 Run、转发事件不直连模型AgentRuntime推进 ReAct调模型、派工具、收结果、决定是否结束ModelGateway统一调用 LLM返回tool_calls或最终文本ToolRuntime校验参数、按RequestContext鉴权、执行业务 APIObservability记录 span、版本、Token供事后归因ObservabilityToolRuntimeModelGatewayAgentRuntimeSessionAPIVueUIUserObservabilityToolRuntimeModelGatewayAgentRuntimeSessionAPIVueUIUser查询 order-service 错误日志POST runstart(run, context)SSE run_startedmessages tool schemassearch_resource(args)tool_startedSSE tool_startedinvoke(search_resource, args, context)exact resourceToolMessage(result)query_logs(args)invoke(query_logs, args, context)structured log summaryToolMessage(result)final answerspans metrics versionsfinal messageSSE text_delta done切记每个tool_call_id必须有对应结果。工具失败也要返回结构化错误否则下一轮模型既无法自我修正也可能违反模型 API 的消息约束。关键几跳入口前端POST run会话服务带着可信RequestContext启动 Runtime同时先推run_started让 UI 立刻有反馈。第一轮模型Runtime 把消息和工具 schema 交给模型。模型提出search_resource——此时还没查库只是「提案」。工具执行Runtime 发tool_started给前端再交给 Tool Runtime 真正调用。身份用上下文里的tenantId/userId不信模型参数里的身份字段。结果回灌工具结果变成ToolMessage再进模型。每个tool_call_id都必须有一条结果失败也要结构化回灌否则下一轮对不齐消息协议。第二轮工具模型根据资源信息再提query_logs同样走 Tool Runtime拿到结构化日志摘要。收尾模型给出最终自然语言答案Runtime 落 Trace会话服务推text_deltadone。HTTP 断开不代表 Run 不存在状态以会话服务为准。一句话模型只提案、Tool Runtime 才执行前端只订事件、别自己猜「是不是在调工具」写操作别走这条「连续自动跑」的路要进下一节的 HITL。事件、写操作 HITL 与落库前端、落库和观测最好围着同一组业务事件转。事件类型可以先定成下面这一组exporttypeRunEvent// Run 业务事件联合|{type:run_started// 事件Run 已开始runId:string// 本次 Run IDsequence:number// 事件序号去重/续传用}|{type:text_delta// 事件增量文本runId:string// 所属 Runsequence:number// 事件序号delta:string// 增量文本不是全量覆盖}|{type:tool_started// 事件工具开始执行runId:string// 所属 Runsequence:number// 事件序号callId:string// 与 tool_finished 配对tool:string// 工具名给步骤条展示}|{type:tool_finished// 事件工具结束runId:string// 所属 Runsequence:number// 事件序号callId:string// 对应 tool_startedstatus:success|error// 执行结果状态summary:string// 给前端的短摘要不是原始大结果}|{type:interrupt// 事件HITL 等待确认runId:string// 所属 Runsequence:number// 事件序号interruptId:string// 恢复时带回防止过期确认payload:unknown// 确认卡内容风险说明、参数摘要等}|{type:done// 事件Run 正常结束runId:string// 所属 Runsequence:number// 事件序号messageId:string// 落库后的助手消息 ID}|{type:error// 事件Run 失败runId:string// 所属 Runsequence:number// 事件序号code:string// 可分类错误码勿回灌堆栈}sequence用来去重和以后补发第一版就算还没做事件重放字段也先留着。别让前端靠解析自然语言去猜「现在是不是在调工具」。写操作为什么必须换一条路如果用户说“重启这个异常实例”。模型只能提出动作不能自己给自己开权限restart_instance proposedapproved reauthorizedrejected or expiredRunningWaitingHumanCancelledCompletedFailed恢复时至少重做四件事校验interruptId仍 pending按当前 RequestContext 重新鉴权重新读取资源防止确认期间状态变化用幂等键避免双击和网络重试造成重复执行。具体实现见后面几篇多轮、SSE、HITL 和工具 Runtime 会分开写。Run 最少要存什么SSE 可能断Run 还在跑。所以库里至少要有一张「状态小票」RunRecord随时能查这笔请求卡在哪、用了哪版 Prompt/模型。它不是聊天全文也不是工具吐出来的大结果。typeRunRecord{// Run 落库最小字段id:string// Run 主键conversationId:string// 所属会话tenantId:string// 租户隔离字段查询必带status:// Run 生命周期状态|queued// 已入队等待 Worker|running// 模型/工具执行中|waiting_human// HITL 等待确认|succeeded// 正常结束|failed// 失败结束|cancelled// 用户或系统取消lastSequence:number// 已发出的最大事件序号断线续传/去重promptVersion:string// 本轮 Prompt 版本排障/回滚用toolsetVersion:string// 工具集版本model:string// 实际调用的模型名createdAt:string// 创建时间updatedAt:string// 最后状态变更时间}日志摘要可能很长另存成 artifact对象存储或附件表Run 里只留引用。Prompt、工具集、模型、知识库版本要能挂到 Trace 上否则线上回退时说不清「当时到底用了哪一版」。验收、排障与交付顺序层可验证的完成标准Vue UI流式增量可渲染工具步骤可折叠停止与 HITL 可操作会话服务用户消息和 Run 落库断开可查结果取消语义明确Runtime最大步数重复调用检测可中断状态可恢复Tool Runtimeschema、scope、超时、错误分类、幂等与审计RAG租户过滤引用可回原文文档更新可失效模型网关超时与 429 分类模型版本、Token 和成本可观测安全外部内容不改变权限高风险操作有独立控制点质量一条traceId可还原轨迹修改前后可跑同一 Eval发布健康检查、灰度、回滚和告警入口可用一个故障怎么定位用户反馈“我明明查生产为什么返回测试环境”按 Trace 找第一个错误点// Trace 片段意图对了但工具参数环境错了——第一错误点在填参不在库查询{traceId:tr_01,// 整次请求追踪 idintent:{// 意图分析结果type:query_logs,// 意图正确environment:production// 用户要生产},toolCalls:[// 实际发出的工具调用{name:query_logs,// 工具选对了args:{// 工具参数service:order-service,// 服务正确environment:test// 实际调成了测试 → 修 Prompt/结构化约束}}]}意图对了、工具参数错了就修选工具/填参的 Prompt 或结构化约束别先去改数据库查询。交付顺序与业务验收交付顺序没有行业标准。下面只是风险从低到高的建议不是固定周数会话落库 文本 SSE。一个只读工具 ToolMessage 错误回灌。RAG 权限过滤 引用。写工具 HITL 幂等审计。Eval 发布检查 Trace 大盘。模型降级、预算、灰度和回滚。业务侧也不能省。一次完整上线至少能说清需求澄清 → 成功指标 → 只读原型 → 写操作与 HITL → 上线 → 采用率 / 用户反馈 → 回滚与复盘成功指标先写业务结果例如「值班能在工作台查完日志并点开引用」再写模型指标。没有采用率和回滚记录只能证明系统能跑不能证明有人在用。小结这篇先钉住三件事模型提案Tool Runtime 执行。前端订事件不猜状态。写操作必须 HITL 重鉴权。文中的 OpsPilot、ID 和 Trace 都是可复现的示例。下一篇继续《Agent 意图识别从语义理解到稳定路由》。希望这篇文章对你有所帮助、有所借鉴。
前言封闭告一段落开始系统复盘一个生产 Agent 到底怎么跑起来。踩坑、经验和落地最主要的是用户认可。尽量用几篇文章讲清这篇文章是系列第1篇用一次只读查询把从界面到 Trace 的整条链路先跑通。用户说“查一下生产环境order-service最近的错误日志。”最终只看到一段回答背后至少经过身份、会话、意图、模型、工具、流式事件、持久化和观测。任何一跳出错都可能表现成“Agent 答错了”。这篇先把整条链路跑通后面几篇再分头细说。案例 OpsPilot企业运维助手虚构只读工具search_resource、query_logs知识工具search_knowledge_base写工具restart_instance必须 HITLHuman-in-the-Loop人在回路确认技术栈Node.js TypeScript Vue 3一张总图POST SSEVue 对话 UI会话服务鉴权与 RequestContextAgent Runtime意图与上下文组装模型网关LLM ProviderTool Runtime业务 API / MCPRAG 检索向量库 / 全文索引Run 事件与消息持久化Trace / Metrics / Eval图上每一块管一件事别混模型负责读懂意思并给出结构化提案。Runtime 负责推进步骤、卡预算、处理中断。Tool Runtime 负责 schema参数长什么样、鉴权、幂等同一操作做一次和做多次和真正执行。会话服务负责身份、Run 生命周期和跟前端的协议。Trace/Eval 负责事后说清「到底哪一跳错了」。请求怎么进 Runtime会话 API 入口前端不应直连模型。它调用自己的会话 APIPOST /api/conversations/conv_123/runs Authorization: Beareruser-tokenContent-Type: application/json Idempotency-Key: 2d7e45b8{message:查一下生产环境 order-service 最近的错误日志}RequestContext 从哪来服务入口中间件从可信登录态拼出上下文。尤其是tenantId和userId别从模型参数或用户原文里读exporttypeRequestContext{// 入口鉴权后的请求上下文requestId:string// 本请求 ID日志与排障用traceId:string// 全链路追踪 ID跨会话/工具/模型共用tenantId:string// 租户检索过滤与数据隔离以此为准userId:string// 当前用户工具鉴权读这里不读模型参数roles:string[]// 角色用于 ACL / RAG 可见范围scopes:string[]// 允许调用的工具或资源范围deadlineAt:number// 整次 Run 截止时间戳超时取消}会话服务创建runId写入用户消息然后把 Run 交给 Runtime。HTTP 连接只是订阅进度不是任务状态本身。只读时序从提案到回灌场景用户问「查一下生产环境order-service最近的错误日志」。这是只读链路不需要 HITL通常会先定位资源再查日志最后给出带证据的回答。按谁干什么读图参与方职责VueUI发起 POST订阅 SSE渲染步骤与增量文本SessionAPI验身份、建 Run、转发事件不直连模型AgentRuntime推进 ReAct调模型、派工具、收结果、决定是否结束ModelGateway统一调用 LLM返回tool_calls或最终文本ToolRuntime校验参数、按RequestContext鉴权、执行业务 APIObservability记录 span、版本、Token供事后归因ObservabilityToolRuntimeModelGatewayAgentRuntimeSessionAPIVueUIUserObservabilityToolRuntimeModelGatewayAgentRuntimeSessionAPIVueUIUser查询 order-service 错误日志POST runstart(run, context)SSE run_startedmessages tool schemassearch_resource(args)tool_startedSSE tool_startedinvoke(search_resource, args, context)exact resourceToolMessage(result)query_logs(args)invoke(query_logs, args, context)structured log summaryToolMessage(result)final answerspans metrics versionsfinal messageSSE text_delta done切记每个tool_call_id必须有对应结果。工具失败也要返回结构化错误否则下一轮模型既无法自我修正也可能违反模型 API 的消息约束。关键几跳入口前端POST run会话服务带着可信RequestContext启动 Runtime同时先推run_started让 UI 立刻有反馈。第一轮模型Runtime 把消息和工具 schema 交给模型。模型提出search_resource——此时还没查库只是「提案」。工具执行Runtime 发tool_started给前端再交给 Tool Runtime 真正调用。身份用上下文里的tenantId/userId不信模型参数里的身份字段。结果回灌工具结果变成ToolMessage再进模型。每个tool_call_id都必须有一条结果失败也要结构化回灌否则下一轮对不齐消息协议。第二轮工具模型根据资源信息再提query_logs同样走 Tool Runtime拿到结构化日志摘要。收尾模型给出最终自然语言答案Runtime 落 Trace会话服务推text_deltadone。HTTP 断开不代表 Run 不存在状态以会话服务为准。一句话模型只提案、Tool Runtime 才执行前端只订事件、别自己猜「是不是在调工具」写操作别走这条「连续自动跑」的路要进下一节的 HITL。事件、写操作 HITL 与落库前端、落库和观测最好围着同一组业务事件转。事件类型可以先定成下面这一组exporttypeRunEvent// Run 业务事件联合|{type:run_started// 事件Run 已开始runId:string// 本次 Run IDsequence:number// 事件序号去重/续传用}|{type:text_delta// 事件增量文本runId:string// 所属 Runsequence:number// 事件序号delta:string// 增量文本不是全量覆盖}|{type:tool_started// 事件工具开始执行runId:string// 所属 Runsequence:number// 事件序号callId:string// 与 tool_finished 配对tool:string// 工具名给步骤条展示}|{type:tool_finished// 事件工具结束runId:string// 所属 Runsequence:number// 事件序号callId:string// 对应 tool_startedstatus:success|error// 执行结果状态summary:string// 给前端的短摘要不是原始大结果}|{type:interrupt// 事件HITL 等待确认runId:string// 所属 Runsequence:number// 事件序号interruptId:string// 恢复时带回防止过期确认payload:unknown// 确认卡内容风险说明、参数摘要等}|{type:done// 事件Run 正常结束runId:string// 所属 Runsequence:number// 事件序号messageId:string// 落库后的助手消息 ID}|{type:error// 事件Run 失败runId:string// 所属 Runsequence:number// 事件序号code:string// 可分类错误码勿回灌堆栈}sequence用来去重和以后补发第一版就算还没做事件重放字段也先留着。别让前端靠解析自然语言去猜「现在是不是在调工具」。写操作为什么必须换一条路如果用户说“重启这个异常实例”。模型只能提出动作不能自己给自己开权限restart_instance proposedapproved reauthorizedrejected or expiredRunningWaitingHumanCancelledCompletedFailed恢复时至少重做四件事校验interruptId仍 pending按当前 RequestContext 重新鉴权重新读取资源防止确认期间状态变化用幂等键避免双击和网络重试造成重复执行。具体实现见后面几篇多轮、SSE、HITL 和工具 Runtime 会分开写。Run 最少要存什么SSE 可能断Run 还在跑。所以库里至少要有一张「状态小票」RunRecord随时能查这笔请求卡在哪、用了哪版 Prompt/模型。它不是聊天全文也不是工具吐出来的大结果。typeRunRecord{// Run 落库最小字段id:string// Run 主键conversationId:string// 所属会话tenantId:string// 租户隔离字段查询必带status:// Run 生命周期状态|queued// 已入队等待 Worker|running// 模型/工具执行中|waiting_human// HITL 等待确认|succeeded// 正常结束|failed// 失败结束|cancelled// 用户或系统取消lastSequence:number// 已发出的最大事件序号断线续传/去重promptVersion:string// 本轮 Prompt 版本排障/回滚用toolsetVersion:string// 工具集版本model:string// 实际调用的模型名createdAt:string// 创建时间updatedAt:string// 最后状态变更时间}日志摘要可能很长另存成 artifact对象存储或附件表Run 里只留引用。Prompt、工具集、模型、知识库版本要能挂到 Trace 上否则线上回退时说不清「当时到底用了哪一版」。验收、排障与交付顺序层可验证的完成标准Vue UI流式增量可渲染工具步骤可折叠停止与 HITL 可操作会话服务用户消息和 Run 落库断开可查结果取消语义明确Runtime最大步数重复调用检测可中断状态可恢复Tool Runtimeschema、scope、超时、错误分类、幂等与审计RAG租户过滤引用可回原文文档更新可失效模型网关超时与 429 分类模型版本、Token 和成本可观测安全外部内容不改变权限高风险操作有独立控制点质量一条traceId可还原轨迹修改前后可跑同一 Eval发布健康检查、灰度、回滚和告警入口可用一个故障怎么定位用户反馈“我明明查生产为什么返回测试环境”按 Trace 找第一个错误点// Trace 片段意图对了但工具参数环境错了——第一错误点在填参不在库查询{traceId:tr_01,// 整次请求追踪 idintent:{// 意图分析结果type:query_logs,// 意图正确environment:production// 用户要生产},toolCalls:[// 实际发出的工具调用{name:query_logs,// 工具选对了args:{// 工具参数service:order-service,// 服务正确environment:test// 实际调成了测试 → 修 Prompt/结构化约束}}]}意图对了、工具参数错了就修选工具/填参的 Prompt 或结构化约束别先去改数据库查询。交付顺序与业务验收交付顺序没有行业标准。下面只是风险从低到高的建议不是固定周数会话落库 文本 SSE。一个只读工具 ToolMessage 错误回灌。RAG 权限过滤 引用。写工具 HITL 幂等审计。Eval 发布检查 Trace 大盘。模型降级、预算、灰度和回滚。业务侧也不能省。一次完整上线至少能说清需求澄清 → 成功指标 → 只读原型 → 写操作与 HITL → 上线 → 采用率 / 用户反馈 → 回滚与复盘成功指标先写业务结果例如「值班能在工作台查完日志并点开引用」再写模型指标。没有采用率和回滚记录只能证明系统能跑不能证明有人在用。小结这篇先钉住三件事模型提案Tool Runtime 执行。前端订事件不猜状态。写操作必须 HITL 重鉴权。文中的 OpsPilot、ID 和 Trace 都是可复现的示例。下一篇继续《Agent 意图识别从语义理解到稳定路由》。希望这篇文章对你有所帮助、有所借鉴。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
