生产禁区

OpenAI Agents SDK 工程笔记：ModelRetrySettings 与 RetryPolicy 模型侧重试、退避叠加与生产禁区一次促销活动中，下单 Agent 在上游网关 429 时“看起来自己好了”：用户侧最终成功，财务侧却出现少量重复扣款。排查发现两层重试叠在一起。网关客户端按指数退避重打，Agent 运行时又在 ModelSettings.retry 里开了 runner 托管重试；中间那次模型调用其实已经触发过写工具，只是响应在返回途中被判为可重试失败。没有人配置“成功就重试”，是重试边界把一次不确定的失败当成了可安全重放的运输错误。

OpenAI Agents SDK 工程笔记：ToolContext 工具侧上下文注入、跨请求串租户与生产禁区一个多租户的计费助手里，扣费工具需要知道当前是哪个租户。最早的写法很省事：请求进来时把租户 id 写进模块级的字典，工具函数里直接读。压测那天，两个租户的请求几乎同时到达，A 租户的一次扣费记到了 B 租户头上。日志里看，工具确实被 A 的会话调用，读到的租户却是 B。

OpenAI Agents SDK 工程笔记：RunResult.last_agent 多交接后责任归属、终稿误挂与生产禁区多 Agent 交接跑完以后，日志里常出现一个尴尬问题。入口叫分诊，终稿却是计费专家写的，告警和计费却挂在分诊头上。RunResult 上有一个专门字段处理这件事。本机 openai-agents 0.23.1 里，属性名就是 last_agent，类型是 Agent。它指向本轮跑完时最后一个仍被框架握着的 Agent。标题里说的责任归属，指的就是用这个字段钉终稿作者，而不是用入口名或展示名猜。

OpenAI Agents SDK 工程笔记：AgentOutputSchema 结构化输出声明、strict 校验失败与生产禁区很多团队在 Agent 上写了 output_type=某个 Pydantic 模型，就默认终稿一定是结构化对象。声明期那一层 AgentOutputSchema 才管这件事。它生成 JSON Schema，再在模型返回后做 validate_json。跑完再用别的方法强转，是另一条路径，本文不展开。

OpenAI Agents SDK 工程笔记：TraceProcessor 导出、敏感字段脱敏与生产禁区Agents SDK 的追踪默认是开着的。每次 Runner.run 都会生成一条 trace，下面挂着 Agent、生成、工具调用、交接等 span。排障时这很方便，可它也意味着用户输入、工具参数、工具返回值都会被打包，交给处理器导出。导出到哪里、带走了什么，很多团队上线前没有认真看过。

OpenAI Agents SDK 工程笔记：自定义 Session 接口（get_items / add_items / clear）与多租户隔离的生产禁区官方给了 SQLiteSession，也给了托管的会话实现。很多团队还是会自己写一个 Session，原因很实际，历史要进公司已有的 Postgres 或 Redis，要按租户分库，要接审计。自己写的那一刻，SDK 不再替你兜底。Runner 只管调用四个方法，键怎么拼、写入是否原子、读出来多少条、清空清到哪一层，全是实现者的责任。

OpenAI Agents SDK 工程笔记：SQLiteSession 多轮会话持久化与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com多轮 Agent 最容易踩的坑，不是「忘了上一句」，而是以为落盘了其实只落了半截、以为隔离了其实共用了 session_id、以为删掉了其实 messages 还在。OpenAI Agents SDK 的 SQLiteSession 把对话 item 写进 SQLite：默认 :memory: 进程结束即丢；传入文件路径才跨重启。Runner.run(..., session=...) 跑前 get_items 取

OpenAI Agents SDK 工程笔记：tool_use_behavior 与 is_enabled 动态工具开关生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com一个 Agent 调完工具之后，接下来发生什么？默认情况下，工具结果会交回模型，模型再决定是继续调用还是给出终答。这个默认值看起来理所当然，直到线上出现两类事故：通知发了两遍，因为模型在第二轮「确认一下」又调了一次；管理员的清缓存工具突然不见了，因为开关函数读错了上下文里的键。

OpenAI Agents SDK 工程笔记：LocalShellTool 与 ApplyPatchTool 执行面边界与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.comLocalShellTool / ShellTool 与 ApplyPatchTool 让模型能在你的机器上执行命令、改文件。SDK 不会替你做工作区隔离：executor / editor 收到什么就执行什么。本文在 openai-agents 0.23.1 下用脚本化假模型发出真实的 local_shell_call / apply_patch_call，对比「朴素实现」与「加闸实现」，留下 13 行 CSV（

OpenAI Agents SDK 工程笔记：ModelProvider 多模型接入、Responses/Chat Completions 切换与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.comAgent 上写了 model="gpt-4.1"，真正发出去的请求却打到了别的前缀；本地全绿，一接第三方兼容端点就 404；为了省事把第三方 AsyncOpenAI 设成默认客户端，结果 tracing 把同一把 key 往 OpenAI 的导出接口送。官方 Models 页把这些控制项拆得很清楚，但工程上最容易漏的是谁在解析 model 字符串、Responses 与 Chat Completions 两套形状

OpenAI Agents SDK 工程笔记：MCP 工具接入与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com把 MCP server 接进 Agent，最贵的失败往往不是「连不上」，而是连上了、工具全暴露了、谁都能调：一个文件系统 server 同时带着 read_file 和 delete_file，开发时图省事不做过滤，上线后模型在一次误解里就把删除工具调了出去。官方 MCP 页开头就写了信任前提：只连可信 server、用最小权限凭据、token 放在 authorization 字段或 header 而不是 U

OpenAI Agents SDK 工程笔记：sessions 记忆边界再核对与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com把 Agents SDK 的 sessions 当成「自动记得上一句」很容易过界：它管的是客户端会话历史的取回与写回，不是业务授权、不是 OpenAI 服务端续写、更不是「进程重启后一定还在」。官方 Sessions 写得很直：同一次 run 里，session 不能与 conversation_id / previous_response_id / auto_previous_response_id 叠用；跑前取

OpenAI Agents SDK 工程笔记：streaming 流式输出与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com把 Agents SDK 的 streaming 当成「多打几个 print」会踩坑：Runner.run_streamed() 返回的是 RunResultStreaming，真正完成要以 stream_events() 迭代器结束为准；最后几个可见 token 到齐之后，会话持久化、审批记账、历史压缩仍可能在收尾。官方 Streaming 与 Results 写得很直：事件分 raw / run item /

OpenAI Agents SDK 工程笔记：handoffs 多 Agent 交接与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com多 Agent 系统最容易翻车的不是「少写了一个专家提示」，而是把 handoff（交接）当成普通 tool 调用：以为只是「请同事帮一下」，实际却把对话所有权交给了另一个 Agent。官方 Handoffs 与 Orchestrating multiple agents 写得很直：handoffs 对模型呈现为工具（如 transfer_to_refund_agent）；一旦触发，专家 Agent 接管本轮后续

OpenAI Agents SDK 工程笔记：tool 调用循环、max_turns 与生产禁区千笔-AIWritePaper · https://www.aiwritepaper.com多轮 Agent 最容易翻车的不是「忘了挂 tools」，而是把模型决定调用、SDK 执行工具、再送回模型当成无限循环，却从不验收 max_turns。官方 Running agents（中文：运行智能体）把循环钉死为：调模型 → 最终输出则停 / 任务转移则换 Agent / 有 tool calls 则执行并回灌 → 超过 max_turns 抛 MaxTurnsExceeded。本文按工程笔记写法，钉死循环、

我是有底线的