从“能调用工具的 Demo”到可审计、可恢复、可评测、可控成本的生产系统 版本2026-08-141. 先定义 Agent它是一个受约束的决策循环一个生产级 Agent 至少同时具备四个要素目标用户或上游系统想获得什么结果。状态已知事实、执行进度、预算、审批与失败记录。动作空间允许调用的工具、委托的专家、可生成的产物。停止条件成功、失败、超时、预算耗尽、风险升级或需要人工接管。可以把一次运行抽象为state(t1) transition(state(t), observation(t), policy, budget)模型只是transition的一个候选实现。数据库事务、权限策略、幂等键、审批、重试和审计不能交给模型“凭感觉”完成。1.1 Agent 与普通工作流的边界优先使用确定性工作流当任务满足以下条件步骤稳定、分支少输入输出 schema 明确失败处理可枚举不需要在运行中理解开放文本并改变计划。使用 Agent当任务确实需要根据自然语言或非结构化证据选择下一步在多个工具间动态路由对不完整信息做澄清、检索和验证生成需要语义判断的产物。最稳健的生产形态通常不是“全自主”而是确定性工作流骨架 局部 Agent 决策点 高风险动作人工审批2. 参考架构把控制面、执行面和治理面分开2.1 各层责任层核心责任不应承担的责任体验与接入身份、租户、请求归一化、流式响应、附件接入不直接持有高权限业务凭证编排与状态状态机、计划、路由、重试、审批、取消、恢复不绕过策略引擎执行动作模型与上下文推理、结构化输出、模型路由、检索上下文不作为唯一事实源或权限源工具执行参数校验、鉴权、速率限制、幂等、调用外部系统不接受未经验证的自由文本命令业务与数据CRM/ERP/数据库/消息/文件等真实系统不把内部权限委托给模型决定横切治理审计、可观测性、安全、成本、数据保留不能在上线后“再补”2.2 控制面与执行面为什么要拆控制面决定“允许做什么”执行面负责“按已批准参数去做”。拆分带来四个直接收益模型被 Prompt Injection 影响时仍无法自行扩大权限执行器可使用短期凭证而不是把长期密钥放进模型上下文每个动作都能绑定审批、策略版本和幂等键可以独立扩缩容推理受 Token/延迟限制工具执行受 I/O 和外部 API 限制。3. 协议选型不要把所有连接都叫“Agent 协作”3.1 四种常见边界边界适合解决什么必须设计什么函数/工具调用同一应用内模型选择一个受控函数JSON Schema、超时、错误类型、幂等MCP/连接器统一暴露外部工具和数据工具发现、授权、工具过滤、审批、结果裁剪Agent 任务协议一个 Agent 把独立责任委托给另一个 Agent能力发现、任务 ID、状态、取消、产物、回调/轮询内部消息队列跨服务的可靠异步执行至少一次投递、去重、死信、重放、顺序性[官方事实]OpenAI Responses API 可通过 MCP/Connectors 扩展模型能力工具调用可以自动允许也可以要求显式审批。MCP 工具会先列出工具定义再执行调用过多工具会增加成本和延迟可用allowed_tools限制或在支持时延迟加载工具定义。MCP and Connectors3.2 MCP 不负责什么MCP 解决的是模型客户端与工具/数据源之间的接口不自动提供完整的长任务调度跨 Agent 所有权转移业务事务端到端 exactly-once审批组织结构灾难恢复。这些仍需要编排器、数据库、消息队列和业务策略。3.3 何时真的需要多个 Agent多 Agent 的收益来自责任边界不是角色扮演。满足以下至少一项再考虑拆分子任务可并行且彼此上下文相对独立不同子任务需要不同工具权限需要独立 SLA、预算或审计责任子任务产物有稳定 schema可独立验收专家上下文很大放入主 Agent 会显著污染上下文。如果只是“规划者、研究员、写作者”三个名字共享同一套上下文和权限多 Agent 往往只会增加 Token、延迟和失败点。4. 运行时把 Agent Loop 建模成有限状态机4.1 最小持久化状态from dataclasses import dataclass, field from enum import Enum from typing import Any ​ class RunStatus(str, Enum): RECEIVED received PLANNING planning WAITING_APPROVAL waiting_approval EXECUTING executing VERIFYING verifying COMPLETED completed FAILED failed CANCELED canceled ​ dataclass class RunState: run_id: str tenant_id: str user_id: str status: RunStatus step_no: int 0 token_budget: int 0 tool_call_budget: int 0 deadline_epoch_ms: int 0 facts: dict[str, Any] field(default_factorydict) artifacts: list[dict[str, Any]] field(default_factorylist) pending_approval_id: str | None None policy_version: str 状态必须存到可靠存储而不是只存在进程内存。否则服务重启、网络抖动或审批等待都会让任务失去上下文。4.2 重试不是“再问模型一次”先对失败分类失败类型例子建议策略瞬时基础设施失败502、连接重置、限流指数退避 jitter限制次数可修复参数失败schema 缺字段、日期格式错把结构化错误返回模型最多修复 1–2 次业务冲突库存变化、版本冲突重新读取事实后重新计划不盲重试权限失败403、scope 不足停止并请求授权不重试安全策略拒绝高风险参数、越权目标终止或升级人工不允许模型规避不确定结果超时但外部系统可能已执行用幂等键/查询状态确认禁止直接重放4.3 幂等与副作用对每个有副作用的动作生成稳定幂等键idempotency_key hash(tenant_id, run_id, step_id, tool_name, canonical_args)执行器应记录PENDING → STARTED → SUCCEEDED | FAILED | UNKNOWN若状态为UNKNOWN必须通过外部系统查询结果而不是重新执行“退款、发信、下单、部署”等动作。5. 工具工程Schema 是契约权限是边界5.1 一个好工具应具备的性质窄职责create_refund优于manage_order。可验证参数金额、币种、资源 ID、枚举和上限明确。结构化错误区分可重试、需授权、业务冲突和永久失败。可预测副作用工具描述必须写清会创建、修改、发送还是删除。最小返回只返回下一步需要的数据避免整份客户记录进入模型上下文。内置幂等调用方重复请求不会造成重复扣款或重复消息。5.2 工具元数据与风险注册表from dataclasses import dataclass from typing import Literal ​ Risk Literal[read, write, financial, destructive] ​ dataclass(frozenTrue) class ToolPolicy: name: str risk: Risk approval_required: bool max_calls_per_run: int timeout_seconds: int allowed_roles: frozenset[str] allowed_tenants: frozenset[str] | None None ​ TOOL_POLICIES { search_orders: ToolPolicy( namesearch_orders, riskread, approval_requiredFalse, max_calls_per_run5, timeout_seconds10, allowed_rolesfrozenset({support, manager}), ), refund_order: ToolPolicy( namerefund_order, riskfinancial, approval_requiredTrue, max_calls_per_run1, timeout_seconds20, allowed_rolesfrozenset({manager}), ), }风险不能只写在 prompt 中。策略引擎必须在执行器侧重新校验身份、租户、角色、资源所有权和参数限制。5.3 审批对象必须绑定具体参数错误做法“是否允许 Agent 使用退款工具”正确做法动作refund_order 订单ORD-20260814-1042 金额SGD 28.98 原因重复扣款 影响退款后订单保持已取消预计 5–10 个工作日到账 审批有效期10 分钟 参数哈希sha256:...审批后若参数变化原审批失效。5.4 MCP 调用的 Token 与延迟[官方事实]OpenAI 文档说明在 Responses API 中MCP 本身不额外按“每次工具调用”收费费用来自导入工具定义和进行工具调用时使用的模型 Token。工具多时应使用allowed_tools支持 Tool Search 时可defer_loading避免把所有函数定义同时加载进上下文。MCP and Connectors因此MCP 成本优化首先是只暴露当前任务需要的工具工具描述短而精确搜索先返回元数据再按 ID 获取正文对大型结果在工具侧聚合、去重和截断保留已列出的工具上下文避免每轮重复发现。6. 上下文与记忆不要把所有历史都塞给模型6.1 四类记忆要分开类型示例存储与召回策略会话工作记忆当前目标、刚获得的工具结果短期上下文随运行结束归档任务状态step、审批、幂等键、预算强一致数据库不能靠摘要替代用户长期偏好语言、格式、时区显式可编辑最小化保存领域知识政策、手册、产品文档版本化知识库检索时附来源“记忆”不是越多越好。错误、过期或越权的记忆会稳定地产生错误结果。6.2 RAG 的生产流水线采集 → 解析 → 去重 → 分块 → 元数据/ACL → 索引 ↓ 查询 → 意图/过滤 → 召回 → 重排 → 权限过滤 → 上下文组装 → 引用关键点ACL 过滤应在检索层执行而不是检索后让模型“忽略无权限文档”文档必须带版本、生效时间、来源和所有者Chunk ID 要稳定才能做引用、回放和差异评测检索失败时要允许回答“不知道”而不是把模型参数知识当企业事实先测Recallk与权限泄露再测最终回答。6.3 上下文压缩的正确顺序删除与任务无关的工具和说明用 ID/元数据筛选再取正文结构化工具返回避免 HTML/日志噪声对历史做带事实引用的摘要长任务使用 checkpoint而不是无限追加消息最后才考虑更大的上下文窗口。7. 模型选型用任务分层和评测不用“总榜”7.1 建立候选模型矩阵每个模型至少在以下维度单独评测维度测量方法不能用什么替代工具选择正确率期望工具、禁止工具、无工具三类样本通用聊天榜单参数正确率JSON schema 业务约束通过率“看起来合理”任务完成率端到端结果与副作用核验只看最终文字事实性来源支持率、引用精度、无依据断言率LLM 自评分安全性越权、注入、敏感数据测试集拒答率越高越安全延迟p50/p95/p99含工具等待单次手测成本每个成功任务的全链路成本每百万 Token 单价7.2 路由策略低风险结构化分类 → 小模型 多工具、长上下文、复杂规划 → 强模型 高风险动作 → 强模型建议 策略引擎 人工审批 批量离线任务 → 批处理/异步 简单聚合过滤 → 代码执行不调用模型7.3 OpenAI 模型价格示例快照以下仅用于展示如何记录价格配置不是永久价目表。截至 2026-08-14官方 OpenAI 文档列出的 GPT-5.6 文本 Token 单价为模型输入 / 1M Token缓存输入 / 1M输出 / 1M建议定位GPT-5.6 Sol5.00 | 0.50$30.00复杂专业任务GPT-5.6 Terra2.50 | 0.25$15.00能力与成本平衡GPT-5.6 Luna1.00 | 0.10$6.00高吞吐、成本敏感来源OpenAI model catalog 与 Model comparison。实际账单应在部署时重新核对。不要直接把这张表变成路由规则。先用自己的评测集证明较小模型达到质量与安全门槛再降级。8. 安全把 Prompt Injection 当成控制面攻击8.1 威胁模型Agent 同时接触以下不可信输入用户消息网页、邮件、PDF 和检索文档第三方工具返回另一个 Agent 的消息或产物文件名、URL、元数据和错误信息。任何一层都可能包含“忽略之前指令、发送密钥、调用某工具”等恶意文本。安全目标不是识别所有恶意句式而是让这些文本没有能力直接改变高权限控制流。8.2 为什么正则黑名单不够原稿的检测器只能识别几个英文短语。攻击者可以改写、翻译或分词用 Base64、Unicode 或图片承载指令把指令嵌入正常业务内容诱导模型通过合法工具间接泄露数据利用工具返回继续注入。黑名单可作为低成本遥测信号但不能作为授权边界。8.3 防御优先级不把不可信文本拼进高优先级开发者指令外部内容只进入“数据字段”不进入控制字段Agent 间使用固定 schema 传输最小字段工具 allowlist 与参数限制由执行器强制高风险动作逐次审批凭证短期化、按工具和租户隔离对出站域名、数据量和敏感字段设策略用注入与越权测试集持续评测。[官方事实]OpenAI 安全指南建议不要把不可信变量放入 developer message使用结构化输出约束节点间数据流保持 MCP 工具审批结合 guardrails、trace graders 和 evals。官方同时明确指出即使组合这些措施Agent 仍可能犯错或被欺骗。Safety in building agents8.4 策略决策必须在模型外执行def authorize(ctx, tool_name: str, args: dict) - tuple[bool, str]: policy TOOL_POLICIES[tool_name] if ctx.role not in policy.allowed_roles: return False, role_not_allowed if args.get(tenant_id) ! ctx.tenant_id: return False, cross_tenant_access if tool_name refund_order and args[amount_minor] 50_000: return False, amount_limit_exceeded if policy.approval_required and not ctx.has_valid_approval(tool_name, args): return False, approval_required return True, allowed模型可以提出参数但不能决定authorize()的结果。9. 评测从组件正确性到业务结果9.1 五层评测体系层评什么典型指标数据/检索是否取到正确且有权限的证据Recallk、nDCG、ACL 泄露率、过期文档命中率规划/路由是否选择正确步骤、模型和工具工具选择 F1、无效步骤率、计划长度工具执行参数与副作用是否正确schema 通过率、幂等命中率、错误分类准确率最终答案是否受证据支持、格式正确引用支持率、无依据断言率、schema 通过率业务结果是否真正创造价值一次解决率、人工接管率、处理时长、投诉/损失9.2 数据集分层建议至少包含常见正常样本边界条件和歧义输入工具超时、空结果、重复结果权限不足和跨租户请求间接 Prompt Injection高风险动作与审批拒绝多轮澄清和长任务恢复历史生产事故回放。不要只用“500 条干净问答”。测试分布应覆盖生产噪声、错别字、多语言、附件异常、时区和真实权限。9.3 Judge 的正确用法LLM Judge 适合评价语义和风格但应满足rubric 明确避免“总体打分”Judge 看不到不该知道的标签用人工标注集校准 Judge高风险结论用确定性检查或人工复核记录 Judge 模型版本与 prompt 版本监控 Judge 漂移。9.4 发布门槛一个可执行的门槛示例release_gate: task_success_rate: baseline - 0.5pp unauthorized_action_rate: 0 duplicate_side_effect_rate: 0 citation_support_rate: 98% p95_latency_ms: 8000 cost_per_success: budget human_escalation_rate: within expected band这里的数值只是模板。阈值要由业务风险和基线数据决定。[官方事实]OpenAI 将 evals 定义为用测试输入和标准评估模型输出、分析结果并迭代改进的过程模型升级前尤其需要代表性评测。Working with evals10. 可观测性一次运行必须能完整回放10.1 四类遥测Trace请求、模型、检索、工具、审批之间的因果关系。Metrics成功率、延迟、Token、成本、重试和接管趋势。Logs结构化错误、策略理由、外部响应码。Artifacts最终文件、引用快照、工具结果摘要和审批记录。10.2 Span 建议字段run.id step.id tenant.id user.role model.name model.reasoning_effort usage.input_tokens usage.output_tokens usage.cached_tokens usage.reasoning_tokens tool.name tool.risk tool.args_hash tool.result_hash policy.version policy.decision approval.id approval.actor retry.count error.category latency.ms estimated_cost禁止直接把完整 prompt、邮箱正文、客户数据和密钥写入日志。对敏感字段做删除、哈希或受控采样。10.3 OpenTelemetry 代码骨架from opentelemetry import trace tracer trace.get_tracer(agent.runtime) async def run_step(state, step, executor): with tracer.start_as_current_span(agent.step) as span: span.set_attribute(run.id, state.run_id) span.set_attribute(step.id, step.id) span.set_attribute(tool.name, step.tool_name) span.set_attribute(tool.risk, step.risk) span.set_attribute(policy.version, state.policy_version) try: result await executor.execute(step) span.set_attribute(tool.status, result.status) return result except Exception as exc: span.record_exception(exc) span.set_status(trace.Status(trace.StatusCode.ERROR)) raise10.4 SLO 要围绕“成功任务”只监控 API 200 没有意义。建议同时跟踪task_success_ratecorrect_side_effect_rateunauthorized_action_rateduplicate_action_ratep95_end_to_end_latencycost_per_successful_taskhuman_escalation_raterecovery_success_rate。11. 成本工程按“成功任务”而不是单次模型调用计价图中的百分比是示意分解不是行业基准。真实占比必须从 Trace 和账单计算。11.1 总成本模型Cost(task) Σ model_input_tokens × input_price Σ cached_tokens × cached_price Σ model_output_tokens × output_price tool/API charges retrieval/storage/compute retries and verification human review time expected failure loss决策时更有价值的是Cost_per_success total_cost / successful_tasks一个更便宜但失败率更高、需要更多重试和人工复核的模型可能有更高的Cost_per_success。11.2 优化顺序限制任务范围日期、项目、最大结果数、最大步骤数。减少工具面allowed_tools、延迟加载、按阶段暴露。工具侧裁剪搜索/过滤/聚合在数据附近执行。删除重复提示规则只写一次工具描述保持精确。缓存稳定前缀系统说明、固定 schema、静态参考。模型路由经评测后把简单任务下放。并行化独立 I/O减少墙钟时间不一定减少 Token。批处理离线任务允许更长延迟换取吞吐和成本。失败早停权限不足、预算不足时立即结束。11.3 预算护栏class BudgetExceeded(RuntimeError): pass def check_budget(state, *, next_input_tokens: int, next_tool_calls: int 0): if next_input_tokens state.token_budget: raise BudgetExceeded(token_budget) if next_tool_calls state.tool_call_budget: raise BudgetExceeded(tool_call_budget) if now_ms() state.deadline_epoch_ms: raise BudgetExceeded(deadline)预算耗尽后的策略应预先定义返回部分结果、降级模型、请求用户缩小范围或转人工不能无限续费重试。12. 部署从风险和集成复杂度做决策12.1 四种路径路径适合优势主要代价SaaS / 低代码验证低风险、低集成、快速验证上线快、运维少可控性、可移植性、深度集成有限托管 Agent 平台中高风险、标准化集成治理、审批、观测能力集中平台绑定与定制边界代码优先 Agent 平台复杂业务、需要测试和扩展控制力强、可工程化需要成熟研发与运维能力自建编排 私有执行面高风险、高集成、强数据边界权限、网络、审计最可控成本和组织复杂度最高12.2 沙箱与网络原稿把容器设为network_mode: none同时又需要调用远程模型和 MCP这在逻辑上冲突。更合理的生产策略编排器与工具执行器分离工具执行器使用只读根文件系统和最小 Linux capabilities临时工作目录设置大小、文件数和生命周期限制出站网络仅允许批准域名、端口和 DNS敏感内部服务通过私网、服务身份和短期凭证访问禁止工具返回任意 URL 后自动访问每种工具使用独立服务账户和资源配额。[官方事实]对私有、内网或防火墙后的 MCPOpenAI 文档提供 Secure MCP Tunnel 作为受支持产品中的连接方式不应为了接入而直接把私有服务暴露到公网。MCP and Connectors13. 一个可复用的失败复盘使用“合成案例”不伪造真实企业以下是综合常见模式构造的合成案例用于展示复盘方法不代表真实公司或真实金额。13.1 场景客服 Agent 可以读取订单、读取政策并发起退款。上线后出现相似问题答案不一致过期政策被召回超时后重复发起退款邮件中的恶意文本诱导 Agent 请求额外客户数据团队只记录最终回答无法定位是哪一步出错。13.2 因果链知识无版本 → 召回过期文档 ↓ 自由文本进入规划上下文 → 间接注入影响工具选择 ↓ 退款工具无金额上限、无幂等键 → 超时重试造成重复副作用 ↓ 无 step trace / policy log → 无法回放与快速止损13.3 改进不是“换更强模型”根因修复验证方法过期知识文档版本、生效期、owner检索过滤过期文档测试集命中率为 0间接注入外部内容隔离、结构化抽取、工具 allowlist注入集不产生未授权调用重复退款幂等键、执行状态查询、事务语义超时/重放测试无重复副作用金额越权执行器策略 审批绑定参数边界金额与跨租户测试无法定位全链路 trace、版本记录、产物快照任意事故可从 run_id 回放14. 从 0 到生产的 12 周路线图第 1–2 周问题与基线明确任务边界和“不做什么”收集真实样本与人工处理基线定义业务指标、风险等级和审批人建立最小离线评测集。退出条件不用模型也能清楚描述输入、输出、失败和风险。第 3–4 周只读原型单 Agent只读工具结构化输出完整 trace无外部副作用。退出条件检索、工具选择、引用和延迟达到原型门槛。第 5–6 周受控写入策略引擎幂等键审批绑定参数事务/补偿权限和注入测试集。退出条件越权和重复副作用测试为零。第 7–8 周可靠性持久状态机重试分类超时、取消和恢复生产失败回放SLO 与告警。退出条件依赖故障和服务重启后能恢复或安全停止。第 9–10 周灰度影子流量1%–5% 灰度明确回滚开关人工复核抽样成本/成功任务监控。退出条件业务、质量、安全、成本均不劣于发布门槛。第 11–12 周扩大与治理扩大流量定期红队与评测Prompt/模型/工具/策略版本管理数据保留与删除流程事故响应手册和责任人。15. 上线检查清单目标与数据有明确业务目标、人工基线和不可接受结果测试集来自真实分布含噪声、边界与失败样本知识有版本、生效期、来源、owner 和 ACL敏感数据有最小化、保留和删除策略模型与上下文模型选择由评测决定而不是排行榜Prompt、模型、工具 schema 均有版本历史和工具结果有裁剪与预算不知道时允许停止、澄清或转人工工具与权限工具窄职责、参数可验证、错误结构化allowlist、角色、租户和资源所有权在执行器校验高风险动作逐次审批且审批绑定参数写工具有幂等键、状态查询和补偿/回滚方案凭证短期化未进入 prompt、日志或产物安全不可信内容不进入高优先级指令Agent 间和节点间使用固定 schema已测试间接注入、越权、跨租户和数据外泄出站网络、域名和数据量受控远程 MCP 服务器来源可信敏感动作要求审批可靠性与运维状态持久化可暂停、恢复、取消重试有分类、次数、退避和总预算Trace 能还原模型、检索、工具、策略和审批有任务级 SLO、告警、回滚开关和事故手册成本按成功任务监控而不是只看 Token 单价16. 核心结论Agent 是受约束的状态机不是无限循环的聊天模型。MCP 连接工具任务协议连接责任边界数据库和队列负责可靠状态。模型可以建议动作但策略引擎、权限和审批必须在模型外强制执行。Prompt Injection 的核心防御是数据与控制分离不是关键词黑名单。先评组件再评端到端最后评业务结果一个“准确率”远远不够。成本应按成功任务计算工具结果、重试和人工复核常比模型单价更重要。多 Agent 只有在责任、权限、上下文或并行性真正独立时才值得。生产系统的竞争力来自可审计、可恢复、可评测和可回滚。参考资料与核验日期以下页面均于 2026-08-14 核验OpenAI, Agents SDK overview — Agent 定义、运行、编排、guardrails、观测与评测入口。OpenAI, MCP and Connectors — MCP 工具发现、审批、allowed_tools、延迟加载、安全与 Token 说明。OpenAI, Safety in building agents — Prompt Injection、私有数据泄露、结构化输出、审批和评测建议。OpenAI, Working with evals — 评测任务、测试输入、结果分析与迭代流程。OpenAI, Model catalog — 当前模型能力、上下文和价格。OpenAI, Model comparison — GPT-5.6 系列价格与规格快照。OpenAI, Model guidance — 模型路由、工具调用、缓存、Token 效率和评测建议。