Agent API 工程实践：从会话管理到多模型接入

2026 年，Agent 从演示阶段进入生产环境。一个典型的信号是：开发者讨论的问题变了。一年前，问题集中在“怎么让模型调用工具”；现在，问题变成了“会话跨天之后怎么恢复”、“工具从 5 个涨到 50 个之后上下文还够不够用”、“多个子智能体同时改一个文件怎么协调”。这些问题的共同特征是——它们都不是模型能力问题，而是工程系统问题。

Agent API 的价值，恰恰在于它试图把一部分工程系统问题从应用层收走。但收走哪些、留下哪些、边界在哪里，决定了它能不能被真正用起来。

一、会话管理：Agent API 最核心的工程赌注

Chat Completions 是无状态调用。每次请求携带完整的 messages 数组，模型不持有任何跨请求状态。这个模型简单、可预测，但把状态管理的全部负担推给了调用方。

Agent API 做了一个方向相反的决策：把会话状态收归平台。

OpenAI Agents API 的 Session 对象是一个持久化的 Agent 实例，跨轮次维护状态。文档明确，会话配置、轮次（turns）和条目（items）由 OpenAI 管理，应用通过 POST /v1/agents/sessions 创建会话并分配任务。断连后，会话仍可通过 retrieve 方法获取待处理的工具调用，使用相同的 turn_id 和 call_id 提交结果。这意味着 Agent 的“记忆”不再完全由客户端持有。

这个设计解决了一个实际痛点。在自建 Agent 时，开发者需要处理上下文窗口的物理限制。超过约 200K token 后，注意力稀释效应可能导致可观测的性能退化。手动压缩上下文又容易丢失关键信息。Agents API 的自动上下文压缩把这项工作收到平台侧，应用不需要在每一轮手动拼接和裁剪历史。

但代价是明确的。会话状态托管在 OpenAI 侧，数据驻留目前仅限美国，且不支持 Zero Data Retention。即使选择自托管沙箱，也不会因此变成 ZDR 合规。对于有数据合规要求的团队，这是一个需要在架构选型阶段就纳入考量的约束。

二、协议分层：MCP 管纵向连接，A2A 管横向协作

Agent 系统的协议栈在 2026 年完成了关键收敛。两个协议的分工已经足够清晰，不再需要“二选一”。

MCP 解决的是 Agent 与工具、数据源之间的连接。 2026 年 7 月发布的第五版规范是 MCP 问世以来最大的架构调整。它从有状态的双向协议转为无状态请求/响应模型，移除了 initialize 握手和 Mcp-Session-Id 头，每个请求完全自包含。这个改动的工程意义在于：MCP 服务器现在可以部署在 Serverless 和 Edge 基础设施上，无需配置会话亲和性，像传统 HTTP 服务一样按轮询调度即可。

数据可以说明 MCP 的生态成熟度。截至 2026 年 7 月，MCP 的 SDK 月下载量超过 4 亿次，一年内增长了 4 倍，官方 registry 已有约 18,850 条条目。对于一个需要考虑长期维护成本的系统来说，这个规模意味着工具生态的供给不再依赖单一厂商。

A2A 解决的是 Agent 与 Agent 之间的协作。 v1.0 在 2026 年 3 月发布，核心对象是 Agent Card。它是一份结构化的能力声明，描述 Agent 能做什么、如何联系、支持哪些模态。从 v0.3 起，Agent Card 支持 JWS 签名，接收方可以验证卡片的完整性和来源，在跨组织协作中建立身份信任。

A2A 的架构选择值得注意。它明确对齐 Web 架构原则：无状态、分层、标准协议绑定。官方文档的表述是，组织可以用“已经用于 Web 系统的负载均衡、网关、安全和可观测性模式”来扩展 Agent 交互。这意味着 A2A 没有发明一套新的运维范式，而是把 Agent 通信嵌入现有的基础设施层。对于一个已经在运行 Kubernetes、API Gateway 和分布式追踪的团队，这个选择的迁移成本显著更低。

A2A 与 MCP 的关系是互补而非替代。MCP 管纵向的“能力连接”，A2A 管横向的“任务协作”。一个 Agent 通过 MCP 连接数据库和代码仓库，通过 A2A 把代码审查任务派给另一个 Agent。两者的组合构成了 Agent 系统的基本通信骨架。

三、运行时架构：托管 harness 的边界与保留项

OpenAI Agents API 的架构把 Agent 运行拆成三层：托管 harness、执行环境和业务应用。

托管 harness 是 OpenAI 运行模型与工具循环的那一层，负责维护会话、压缩上下文、编排子智能体、处理工具调用。执行环境是可选的沙箱，负责命令执行、文件存放和依赖安装。业务应用负责提交任务、接收事件和处理自定义函数。

这个分层的关键判断在于：沙箱是可替换的，harness 不是。

OpenAI 列出了九家沙箱合作方：Blaxel、Cloudflare、Daytona、DigitalOcean、E2B、Modal、Oracle Cloud Infrastructure、Runloop 和 Vercel。开发者可以选择 OpenAI 托管环境，也可以接入自备沙箱。但换沙箱改变的是命令在哪里执行，模型推理请求仍需路由至 OpenAI 端点。harness 本身不在可替换范围内。

计费方式反映了这个架构定位。Agents API 本身不收取平台附加费，费用由三部分构成：模型 token 用量、OpenAI 工具按标准价、托管沙箱按容器时长计费。容器会话按分钟计费，每个会话最低计 5 分钟。对于频繁创建短会话的场景，最低计费单位是一个需要纳入成本模型的因素。

程序化工具调用是这次发布中容易被低估的能力。在 Responses API 中，应用需要自行决定哪些工具允许模型直接调用。Agents API 默认启用程序化工具调用，由平台管理 Agent 循环。模型可以生成 JavaScript 来协调符合条件的工具，支持按工具设置 allowed_callers，并与流式输出、guardrails、审批和会话状态集成。这意味着工具编排的逻辑可以部分下沉到模型侧，而不是全部由应用层硬编码。

四、子智能体：隔离是相对的

多 Agent 文档里有一个容易被忽略的细节：子智能体各有上下文，但共享执行环境的文件系统。

这个设计选择在工程上意味着什么？上下文隔离容易理解——每个子智能体看到不同的对话历史，不会互相污染推理过程。但文件系统共享意味着，两个子智能体同时修改同一个文件时，仍然需要显式的协调机制。这不是协议能自动解决的问题，而是编排设计需要承担的职责。

在实践中，这会影响任务拆分的粒度。如果两个子任务需要修改同一组文件，把它们分配给不同的子智能体并不天然安全。要么串行化执行，要么在编排层引入文件锁或版本控制机制。Agents API 提供了 max_concurrent_subagents 参数来限制并发子智能体数量，但这个参数控制的是并发度，不是冲突检测。

五、接入层：多模型场景下的工程取舍

Agent API 的协议栈在收敛，但模型供应商的接入方式并没有同步收敛。OpenAI、Anthropic、Google 各自有不同的请求格式、认证方法和流式行为。当一个 Agent 需要在不同模型之间切换时——用推理能力强的模型做规划、用成本更低的模型执行子任务——应用层就需要处理这些差异。

统一接入层的价值不在于“让所有模型变得一样”，而在于把协议转换、凭证管理和路由分发收敛到一个可观测的层面。一个成熟的接入层应该提供三样东西：协议抽象（用一套 SDK 调用多个供应商）、流量治理（并发控制、限流、熔断、故障切换）和可观测性（Token 消耗、响应时延、状态码）。

koalaAPI 在这类场景中承担类似的角色。它提供 200 余个模型的接入能力，覆盖 20 余家模型及服务供应商，SLA 可用性标注为 99.99%。开发者使用一个 API Key 即可调用平台已接入的模型，Agent 侧的配置只需指向网关端点。对于需要频繁在模型之间切换或对比的 Agent 工作流，这种统一接入层减少的是配置管理的工作量，而不是模型能力本身的差异。

但需要明确边界：网关解决的是接入层的工程问题。它不会消除不同模型在系统提示词遵循、工具调用格式和上下文限制方面的差异。Agent 的行为在不同模型上仍然会有可观测的偏差。在把某个模型投入生产 Agent 循环之前，用真实工具调用链验证其可靠性，仍然是不可跳过的步骤。

六、设计 Agent API 的几个判断

如果你正在设计或选择 Agent API，有几个从当前实践中浮现的判断值得纳入考量。

状态管理的位置决定了系统的可运维性。 把会话状态交给平台，意味着应用不需要重建完整历史，但代价是状态的可观测性和可迁移性降低。如果会话数据对业务逻辑有直接价值，需要在架构中保留足够的审计和导出能力。

协议选择应该分层做。 先确定 Agent 需要连接哪些工具和数据源，用 MCP 解决。再确定是否需要与其他 Agent 协作，用 A2A 解决。不需要在第一天同时引入两个协议，但需要确保架构不会阻止后续的引入。

子智能体的文件共享需要显式协调。 上下文隔离是自动的，文件系统隔离不是。如果任务拆分涉及共享工作目录的并发写入，编排层必须处理冲突。

接入层的选择取决于模型切换的频率。 如果 Agent 只使用单一模型，直接对接供应商端点更简单。如果需要频繁切换或对比模型，统一接入层减少的是配置管理和密钥轮换的负担。

了解更多： https://koalaapi.com/