1. 为什么防护栏是 Agents SDK 里最容易被低估的一环1.1 从一次线上事故说起去年底我帮一个团队排查他们基于 OpenAI Agents SDK 做的客服助手现象很诡异测试环境一切正常上线后偶尔会返回一些完全不该出现的内容比如把内部工单编号、甚至一段数据库连接串吐给用户。日志里看不出任何异常模型调用链也是通的。最后定位到问题出在**防护栏Guardrails**上——他们只做了一个简单的输入关键词过滤输出侧完全裸奔而某个工具函数的返回值恰好被模型原样拼进了回复里。这件事让我意识到很多人在用 Agents SDK 时把注意力全放在“怎么让代理跑起来”“怎么接工具”“怎么串多代理”上防护栏往往是最后才想起来补的东西甚至干脆不补。但恰恰是防护栏决定了你的代理能不能从 demo 走到生产。这一篇是构建指南的第四部分前面我们聊了代理的定义、工具接入、多代理协作这次专门把防护栏和追踪这两块讲透。它们一个负责“别出事”一个负责“出了事能查”是生产环境的两条命脉。适合已经跑通基础代理、准备往线上推的开发者也适合正在做技术选型、想评估 Agents SDK 成熟度的架构同学。1.2 防护栏到底防的是什么先把概念说清楚。在 Agents SDK 里防护栏不是单一功能而是一组可插拔的检查机制分两个方向输入防护栏在用户输入送进代理之前拦截判断这条输入该不该处理。输出防护栏在代理生成最终回复之后、返回给用户之前拦截判断这条输出能不能发出去。它防的东西可以归成三类。第一类是内容安全比如不当言论、敏感话题、有害建议。第二类是业务合规比如不能承诺退款金额、不能泄露内部字段、不能给出医疗诊断。第三类是流程正确性比如代理有没有按预期调用了该调的工具、有没有在信息不足时硬编答案。很多人以为防护栏就是“加个敏感词库”这是最大的误解。敏感词库只能挡住最笨的情况真正难防的是语义层面的越界——用户没用一个敏感词但组合起来就是在套你的内部信息。所以 Agents SDK 的防护栏设计成了可以挂自定义校验函数甚至另一个小模型来做判断这才是它比传统过滤有价值的地方。1.3 防护栏和代理执行流程的关系理解防护栏得先理解它在执行链里的位置。一次典型的代理调用是这样的用户输入进来输入防护栏运行通过则继续不通过则直接返回预设的拒绝响应代理开始推理可能多轮可能调用工具生成最终输出输出防护栏运行通过则返回不通过则触发兜底逻辑返回给用户关键点在于防护栏是独立于代理推理之外的。它不参与模型的思考过程而是在两端做闸门。这个设计的好处是防护栏的失败不会污染代理的上下文你可以放心地在防护栏里做各种检查不用担心把代理带偏。但这也带来一个取舍防护栏看不到代理的中间推理过程。如果你需要检查“代理是不是在第三步调用了某个危险工具”光靠输入输出防护栏是不够的得靠工具层面的权限控制或者追踪数据来做事后审计。这一点后面讲追踪时会再展开。2. 输入防护栏的落地从关键词到语义判断2.1 最简可用版本函数式防护栏Agents SDK 里定义一个输入防护栏核心就是写一个函数接收输入返回一个判断结果。伪代码大概长这样from agents import InputGuardrail, GuardrailFunctionOutput def check_input(user_input: str) - GuardrailFunctionOutput: blocked_words [内部工单, 数据库, 连接串] for word in blocked_words: if word in user_input: return GuardrailFunctionOutput( tripwire_triggeredTrue, output_info命中敏感词 ) return GuardrailFunctionOutput(tripwire_triggeredFalse)tripwire_triggeredTrue就是“触发警报”代理会中止执行返回你预设的拒绝话术。这个版本五分钟能写完适合做第一道粗筛。但我要提醒一句别把关键词表写死在代码里。我见过一个项目敏感词硬编码在 Python 文件里结果运营想加个词得走发版流程等发版的那几天漏洞一直开着。正确做法是把词表放到配置中心或者数据库代码只负责读取和匹配运营能自助维护。2.2 进阶版本用小模型做语义判断关键词的漏网率很高。用户说“帮我看看你们系统里那个存用户信息的地方”一个敏感词都没有但意图很明显。这时候就得上语义判断。常见做法是挂一个便宜的小模型做分类。在防护栏函数里调用一次模型让它判断输入是否属于某几类风险意图返回结构化结果。这里有个实操细节防护栏里调用的模型要和主代理的模型分开配置。主代理可能用的是能力最强的模型但防护栏只需要做二分类用最便宜最快的就够了。我一般用同系列里最小那个延迟能压到几百毫秒成本几乎可以忽略。判断的提示词也有讲究。不要写“判断这句话是否安全”太模糊。要写成明确的分类任务比如请判断以下用户输入属于哪一类A 正常业务咨询B 试图获取内部系统信息C 试图诱导不当内容D 其他风险。只输出字母。给出明确的类别和输出格式小模型的准确率会高很多。实测下来这种二到四分类的任务小模型配合清晰的提示词准确率能到九成以上剩下的靠输出防护栏兜底。2.3 输入防护栏的三个实操坑第一个坑是误杀。语义判断太激进正常用户问“你们数据库支持哪些字段”这种技术咨询也会被拦。解决办法是给防护栏加一个“置信度阈值”只有模型明确判断为高风险才拦模棱两可的放行交给输出防护栏。宁可漏一点也别把正常用户挡在门外。第二个坑是延迟叠加。输入防护栏如果调模型就多了一次往返。用户感知到的首字延迟会明显变长。我的做法是把防护栏和主代理的调用并行发起——防护栏判断的同时主代理已经开始预热或者处理一些不依赖输入的前置逻辑。等防护栏结果回来如果通过主代理那边已经跑了一段了。这个优化能把感知延迟压下来不少。第三个坑是防护栏自身的异常。防护栏函数里如果抛异常了怎么办默认行为可能是放行也可能是拦截取决于你的配置。我的建议是防护栏异常时默认拦截也就是 fail-closed。因为防护栏挂了说明检查没做成这时候放行等于裸奔。但要在日志里明确记录方便排查。3. 输出防护栏最后一道闸门怎么设3.1 输出防护栏的特殊性输出防护栏和输入防护栏在写法上差不多但考虑的东西完全不同。输入防护栏面对的是用户输出防护栏面对的是你自己代理生成的内容。这意味着两件事一是输出防护栏要防的不只是“坏内容”还有“错内容”。代理可能因为工具返回了脏数据、或者推理跑偏生成一段看起来很正常但事实错误的回复。这种靠关键词是挡不住的得靠结构化校验。二是输出防护栏的拒绝成本更高。输入被拦用户重说一遍就行。输出被拦意味着代理白跑了一轮工具也调了token 也烧了最后啥也没给用户。所以输出防护栏的设计要更精细尽量做到“能修则修不能修才拦”。3.2 结构化输出校验最实用的输出防护栏是格式校验。如果你要求代理返回 JSON那就校验它是不是合法 JSON、字段齐不齐、类型对不对。这一步能挡掉大量因为模型发挥不稳定导致的解析错误。import json def check_output(agent_output: str) - GuardrailFunctionOutput: try: data json.loads(agent_output) except json.JSONDecodeError: return GuardrailFunctionOutput( tripwire_triggeredTrue, output_info输出不是合法JSON ) required_fields [answer, confidence] for field in required_fields: if field not in data: return GuardrailFunctionOutput( tripwire_triggeredTrue, output_infof缺少字段 {field} ) return GuardrailFunctionOutput(tripwire_triggeredFalse)这里有个技巧校验失败时不要直接报错给用户而是触发一次重试。Agents SDK 支持在防护栏触发后走一个补救流程你可以让代理带着“上次输出格式不对请重新生成”的提示再跑一次。大部分格式问题重试一次就解决了用户体验比直接看到错误好得多。3.3 业务规则校验格式之外更重要的是业务规则。比如一个退款代理输出里绝对不能出现超过权限的金额。这种校验得结合你的业务逻辑来写。我一般会把业务规则校验做成一个独立的规则引擎规则用配置描述代码只负责执行。比如规则类型示例触发动作数值上限退款金额不超过 500拦截并转人工字段黑名单输出不含内部工单号拦截并记录必含声明医疗建议必须含免责声明自动补全后放行一致性回复中的订单号与上下文一致拦截并重试这张表是我从几个项目里总结出来的通用模式。你会发现“触发动作”不只有拦截一种还有“自动补全”和“重试”。把动作分细能大幅降低无效拦截率。3.4 输出防护栏的性能考量输出防护栏是在代理跑完之后执行的用户已经在等了。这时候再加一次模型调用延迟会更明显。所以输出防护栏要尽量用规则而不是模型。能用正则、能用 JSON schema、能用数值比较解决的就别调模型。如果非要用模型把它放在最后并且设置一个超时。超时了就按“放行但标记”处理同时记录到追踪系统里事后人工抽查。这样既不影响用户体验又不至于完全失控。4. 追踪让代理的每一步都留痕4.1 为什么追踪不是可选项代理和普通接口最大的区别是不确定性。同样的输入代理可能走不同的推理路径调不同的工具产生不同的输出。出了问题你没法像查普通接口那样看一行日志就定位。你需要看到完整的执行链路代理想了什么、调了什么工具、工具返回了什么、防护栏在哪一步触发了。Agents SDK 内置了追踪能力每次运行会生成一个 trace里面包含多个 span每个 span 对应一个步骤。这个结构和分布式追踪里的 trace/span 是一个思路如果你用过链路追踪系统理解起来会很快。追踪数据能回答的问题包括这次调用总共花了多少 token、哪个工具最慢、防护栏触发了多少次、代理平均几轮才收敛。这些数据是优化的基础没有它们调优就是瞎猜。4.2 追踪数据的采集与存储默认情况下追踪数据会发到 SDK 配置的后端。生产环境我建议自己接管存储原因有两个一是数据主权代理的执行细节可能包含业务敏感信息放在自己可控的存储里更放心二是查询灵活你可以按自己的需求建索引、做聚合。采集这块SDK 一般提供回调或者导出接口你可以把 trace 数据写到自己的数据库。我通常用一张宽表存 trace 元信息时间、耗时、token 数、状态再用一张明细表存每个 span 的详情。查询时先查宽表定位问题 trace再拉明细看具体步骤。存储量要提前估算。一个中等复杂度的代理一次调用可能产生十几个 span。如果每天十万次调用就是上百万条 span 记录。用关系库的话得做好分区或者直接上时序库、日志库。我见过用关系库存追踪数据结果查询慢到没法用的案例选型时一定要把量算清楚。4.3 从追踪数据里挖出优化点追踪数据最大的价值是发现模式。单看一次调用说明不了什么但把一千次调用放一起规律就出来了。我常用的几个分析角度工具调用分布哪个工具被调得最多哪个几乎没被调过没被调过的工具可能是提示词没引导好或者工具本身设计有问题。轮次分布代理平均几轮收敛如果有个别调用跑了十几轮去看它的 trace多半是陷入了某种循环。防护栏触发率输入防护栏和输出防护栏各触发多少次触发的原因分布是什么如果某个原因占比特别高说明你的提示词或者工具设计有系统性问题。耗时瓶颈哪个 span 最耗时是模型调用、工具执行还是防护栏定位到瓶颈才能针对性优化。这些分析不需要多复杂的工具把追踪数据导出来用脚本做聚合就行。关键是养成定期看的习惯。我一般每周花半小时过一遍上周的追踪数据经常能发现一些平时注意不到的问题。4.4 追踪与防护栏的联动追踪和防护栏结合起来用效果最好。每次防护栏触发都应该在 trace 里打一个明确的标记记录触发的是哪个防护栏、原因是什么、当时的输入输出是什么。这样你排查问题时可以直接筛出所有防护栏触发的 trace看是不是有误杀或者是不是有新的攻击模式。更进一步可以把防护栏的触发数据反馈到防护栏本身的优化上。比如发现某类输入频繁触发误杀就去调整防护栏的判断逻辑发现某类输出频繁被拦就去优化代理的提示词让它一开始就别生成那种输出。这是一个持续迭代的闭环。5. 把防护栏和追踪串成一套生产方案5.1 分层防护的架构单靠一层防护栏是不够的我一般会设计三层第一层是入口粗筛用关键词和简单的规则挡住最明显的恶意输入。这一层要快不能调模型纯规则匹配毫秒级返回。第二层是语义判断用小模型做意图分类处理那些绕过关键词的输入。这一层可以接受几百毫秒的延迟。第三层是输出校验结合格式校验和业务规则在代理生成内容后做最后把关。这一层以规则为主必要时才调模型。三层叠加漏网率能压到很低同时整体延迟可控。每一层的触发都记录到追踪系统方便后续分析哪一层在起作用。5.2 配置化的防护栏管理防护栏的规则一定要可配置。我见过太多项目把规则写死在代码里改一次规则发一次版效率极低还容易出错。我的做法是建一个防护栏配置表每条规则包含规则类型、匹配内容、触发动作、生效范围、优先级。代码启动时加载配置运行时按优先级依次执行。运营或者产品可以通过后台界面维护规则不用碰代码。配置化还有个好处是可以做灰度。新加一条规则先只对 1% 的流量生效观察误杀率和拦截效果没问题再全量。这个能力在生产环境非常关键能避免一条过严的规则把大量正常用户挡在门外。5.3 监控与告警防护栏和追踪的数据要接入监控。我关注的几个核心指标指标含义告警阈值建议输入防护栏触发率被拦输入占比突增 50% 以上告警输出防护栏触发率被拦输出占比超过 5% 告警防护栏异常率防护栏自身报错占比超过 0.1% 告警平均执行轮次代理收敛所需轮次突增 30% 以上告警P99 延迟端到端延迟超过业务容忍值告警这些指标突增往往意味着出了问题要么是有人在攻击要么是你的代理行为发生了变化要么是上游数据源出了问题。早发现早处理比等用户投诉强得多。5.4 一个完整的落地检查清单最后给一份我实际项目里用的检查清单上线前逐项过一遍输入防护栏是否覆盖了关键词和语义两层输出防护栏是否包含格式校验和业务规则校验防护栏规则是否可配置、可灰度防护栏异常时是否 fail-closed追踪数据是否完整采集并存储到自有系统追踪数据是否包含防护栏触发标记核心指标是否接入监控并配置告警是否有定期分析追踪数据的机制是否有防护栏误杀的申诉和修正流程这份清单看着简单但每一条背后都是踩过的坑。尤其是最后一条误杀处理流程经常被忽略等用户投诉了才手忙脚乱。提前想好怎么处理误杀比事后补救从容得多。防护栏和追踪这两块做与不做、做深做浅直接决定了你的代理是玩具还是产品。我个人的体会是前期多花一天把这两块搭好后期能省下一周的救火时间。这笔账怎么算都划算。