One core.Many agents._

一个 Agent 在终端里好用，和它能被产品稳定调用，中间还有一整层工程。OpenAgentCore 就是这一层。

选模型、选 Agent、选机器，是三个独立的决定。

每个 Session 指定自己的 Harness、模型服务和执行环境。Core 在执行前校验组合，不支持的直接拒绝。

 1from openai import OpenAI
 2
 3client = OpenAI()  # OPENAI_BASE_URL → your Core
 4
 5session = client.beta.agents.sessions.create(
 6    environment={"type": "openai_hosted"},
 7    input="修复失败的测试，并说明改动。",
 8    extra_body={
 9        "agent": {"model": MODEL, "x_agents_core": {"harness": "codex"}},
10        "x_agents_core": {"model_provider": {
11            "protocol": "responses",
12            "base_url": BASE_URL, "api_key": API_KEY,
13        }},
14    },
15)

• [api]

  与 OpenAI 相同的 API

  用官方 OpenAI SDK 或 HTTP，连接你自己的 Core 地址，不用学新客户端。

• [agent]

  自选 Agent

  每个 Session 运行一个原生 Harness：Codex、Claude Code 或 MiniMax Code，模型服务由你配置。

• [machine]

  自选机器

  托管沙箱（Docker、microsandbox、E2B），或你自己的 Linux、macOS、Windows 机器。

• [swap]

  部件可替换

  沙箱、Harness 和模型服务都通过明确的协议接入，替换任何一个都不动 Core。

每个部件，都通过协议接入。

Core 保存持久执行状态并调度工作；Runtime 在 Environment 中准备文件和能力，启动原生 Harness；Harness 调用模型和工具，经 Runtime 把事件回传给 Core。

生态组件API 命名空间

把一次执行，变成可以管理的 Session。

Session 表示一段持续的 Agent 工作，Turn 是其中一次输入的执行。它们都有标识和持久状态。四条约定，决定了“执行中”“等待处理”“已取消”“失败”分别意味着什么。

• client ──────╳  disconnect
  turn   ━━━━━━━━━━━━━━▶ completed

  连接 ≠ 任务

  关闭输出流只是观察者离开，已提交的工作仍由执行系统管理。

• POST  Idempotency-Key: a1f ──▶ turn_01
  POST  Idempotency-Key: a1f ──▶ turn_01

  重试有身份

  已支持的提交路径带稳定标识，响应丢失也不会重复创建工作。

• cancel ──▶ turn  in_progress
         ──▶ turn  cancelled  ✓ confirmed

  取消要有回执

  关闭输出流证明不了什么，Core 确认目标 Turn 的执行和清理状态。

• turn        ━━━━┫
  executor    ━━━━━━━━┫
  environment ━━━━━━━━━━━━━┫

  执行 ≠ 机器

  一轮任务结束、Executor 关闭、Environment 回收，是三个不同的生命周期。

!故障恢复有边界，而且是明确的：未知结果永远不会被当成成功。

不同接法，产品还要自己负责什么。

状态归基础设施，智能归 Harness。

设计背后的选择。

1. 01

   保留原生 Harness，也接受它的约束

   Runtime 和原生 Harness 运行在执行环境中，持久控制面放在 Core。原生引擎得以直接复用，运行环境、原生历史和恢复能力也因此仍然重要。

2. 02

   共享协议，保留真实差异

   某个 Harness 支持的能力，不会被默认赋予其他 Harness。Core 在执行前检查组合，不支持的明确拒绝，待验证的如实记录。

3. 03

   把简单留给调用者

   调用者只需要理解任务、输入、状态和结果。机器连接、原生执行器、资源清理，由清楚的组件边界承接。接口本身就是产品。

1.0 只是地基。

OpenAgentCore 仍处于 pre-release 阶段，支持范围以具体的 Harness、环境和操作组合为单位验收。接下来的方向：

1. harness

   Agent loop 与工具解耦

   Loop 运行在服务端，工具在用户本地或云端沙箱执行，工具层实现企业级鉴权。

2. compute

   更快、更密的计算

   存算分离、快速恢复状态，按需扩容沙箱容量。

3. storage

   更多存储介质

   S3、OSS、共享文件系统，以及面向 Agent 的文件系统。

4. apps

   基于 Agents API 的应用

   继续在公开 API 上打磨真实产品，和任何应用的接入方式完全一样。

一切细节，都在文档里。

共 21 页，直接读取仓库的 docs.json 生成。新增文档会自动出现在这里。文档正文为英文。