diff --git a/contracts/agents-api/index.md b/contracts/agents-api/index.md index 05cffe0a4..84e391381 100644 --- a/contracts/agents-api/index.md +++ b/contracts/agents-api/index.md @@ -123,6 +123,7 @@ Each item is Core's deliberate or native behavior where the official service beh - Pinned Codex can lose command output emitted before its stream subscription. - Behind the [credential gateway](./model-execution.md#credential-gateway), pinned Codex compacts history locally and never calls `/responses/compact`. - Claude Code and MiniMax Code report no public usage. +- Claude Code and MiniMax Code do not support `native_session_recovery`: when a Session has a started Turn but Core has no recorded native Session ID, execution is rejected. Cold continuation with an already recorded native ID is a separate case; this declaration neither rejects it nor qualifies it. See [public-path qualification](./harness-onboarding.md#qualify-the-public-path). - Core gives no crash-safe or exactly-once guarantee for native side effects; claimed work fails on restart without replay. - Message images must be inline PNG or JPEG data URIs; remote URLs, `file_id` and `detail` are rejected. diff --git a/contracts/agents-api/zh/index.md b/contracts/agents-api/zh/index.md index b00f58fd8..76f496e68 100644 --- a/contracts/agents-api/zh/index.md +++ b/contracts/agents-api/zh/index.md @@ -1,7 +1,7 @@ --- title: "Agents API 覆盖台账" source: contracts/agents-api/index.md -source_hash: 8feb92673f53693a526366264e0ff5094f69112859bfa0882e217a2b3ca07282 +source_hash: 7f7326bcbc718daa44de601d9df6321d4e1a32fa713f081bc3877e4b23d000fd --- Core 旨在以下方固定版本为准支持完整的 OpenAI Agents API（[public API rule](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#public-api)）。本台账记录 Core 对各项资源实现了哪些内容、哪些契约保存其详细信息，并列出相对于 OpenAI 服务的所有已知差异和所有未解决缺口。[API namespaces and credentials](../../../docs/zh/api/index.md) 说明谁调用哪些 API；[Agents API guide](../../../docs/zh/api/public-agent-api.md) 介绍使用方法。 @@ -125,6 +125,7 @@ Core 自身字段位于 `x_agents_core` 中（[Core extensions](../../../docs/zh - 固定版本的 Codex 可能会丢失在订阅其流之前发出的命令输出。 - 在[凭据网关](./model-execution.md#credential-gateway)之后，固定版本的 Codex 在本地压缩历史，从不调用 `/responses/compact`。 - Claude Code 和 MiniMax Code 都不报告公共用量。 +- Claude Code 和 MiniMax Code 不支持 `native_session_recovery`：Session 已有启动过的 Turn，但 Core 未记录原生 Session ID 时，执行会被拒绝。已有原生 ID 时的冷启动续聊属于另一种情况；该声明既不拒绝它，也不证明它已通过验收。参见[公共路径验收](./harness-onboarding.md#qualify-the-public-path)。 - 对于原生副作用，Core 不提供崩溃安全或恰好一次保证；已认领的工作若不重放，会在重启后失败。 - 消息图像必须是内嵌的 PNG 或 JPEG data URI；远程 URL、`file_id` 和 `detail` 会被拒绝。 diff --git a/docs/architecture.md b/docs/architecture.md index 05404fea5..fc92831ca 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,29 +2,30 @@ title: "Architecture" --- -OpenAgentCore separates orchestration, compute and native execution. Core owns the API and durable state. Sandbox Providers manage compute. A Runtime daemon prepares an Environment and runs the selected Harness, whose native SDK or protocol owns the model and tool loop. +OpenAgentCore separates orchestration, compute and native execution. Core owns the API and durable state. Sandbox Providers manage compute. The Runtime runs on a Linux agent host near Core, prepares Environments through Sandbox I/O and runs each native Harness in a Session view. The Harness's upstream SDK or protocol owns the model and tool loop. ```mermaid flowchart TB - App["Application / official SDK"] <-->|"Agents API /v1: HTTP and SSE"| Core + App["Application / official SDK"] <-->|"Agents API /v1"| Core Web["Web administrator console"] <-->|"Core API /core/v1"| Core - Core["Core: authorization, configuration snapshots,
orchestration and durable state"] - Core --- DB[("PostgreSQL")] - Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider: Docker / E2B / microsandbox"] - SP -.->|"Provision compute and bootstrap Runtime"| R - User["User-machine installer"] -.->|"Start Runtime"| R - Core <-->|"Core–Runtime protocol:
preparation, execution, events and receipts"| R - subgraph Env["Environment: managed sandbox or user-owned machine"] - R["Runtime daemon"] --> P["Workspace and capability preparation"] - P -->|"Harness protocol"| A["Harness adapter"] - A <-->|"Native SDK or protocol"| H["Native Harness: model and tool loop"] - H <--> F["Workspace, tools and artifacts"] + Core <-->|"Durable state"| DB[("PostgreSQL")] + Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider"] + Core <-->|"Core–Runtime protocol"| R + subgraph Host["Linux agent host"] + R["Runtime: preparation and execution"] --> H["Session view: native Harness"] + H <-->|"Model and HTTP MCP"| G["Credential gateway"] + end + G <--> Upstream["Model provider / HTTP MCP servers"] + R <-->|"File / Process / Network"| Link["Core Link relay"] + Link <--> IO + SP -.->|"Provision and bootstrap"| IO + User["Self-hosted installer"] -.->|"Start"| IO + subgraph Env["Managed sandbox or self-hosted machine"] + IO["Sandbox I/O service"] <--> F["Workspace, tools and stdio MCP"] end - H <-->|"Model API"| Model["Model provider"] - H <-->|"MCP"| MCP["Local or remote MCP servers"] ``` -Dashed arrows show provisioning and installation. Solid arrows show component interactions, including in-process interfaces. The daemon initiates its authenticated WebSocket connection to Core. The [API index](./api/index.md) describes the application, operator and machine namespaces; [protocol boundaries](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) lists each protocol's code and owning document. +Dashed arrows show provisioning and installation. Solid arrows show component interactions, including in-process interfaces. The agent host connects to Core over an authenticated WebSocket; the agent host and Sandbox I/O connect to the Core Link relay. A Session with `environment: none` has an assignment and a private native home, with no sandbox workspace. The [API index](./api/index.md) describes the application, operator and machine namespaces; [protocol boundaries](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) lists each protocol's code and owning document. ## Component responsibilities @@ -33,7 +34,9 @@ Dashed arrows show provisioning and installation. Solid arrows show component in | Core | Authenticate callers, resolve and freeze configuration, schedule Turns, handle cancellation and pending interactions, persist resources and execution facts in PostgreSQL | [Core service](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/README.md) | | Sandbox Provider | Create, observe, renew and reclaim compute; start the Sandbox I/O service in it | [Sandbox Provider](./sandbox-provider.md), [Sandbox bootstrap](./sandbox-bootstrap.md) | | Sandbox node | Operate a Docker or microsandbox host and reconcile its assigned generation and allocations | [Sandbox node protocol](../contracts/agents-api/node-generation-protocol.md) | -| Runtime | Prepare the workspace and capabilities, manage Session Executors, execute Turns and report events and receipts | [Core–Runtime protocol](./runtime-protocol.md) | +| Runtime on the agent host | Prepare the workspace and capabilities through Sandbox I/O, manage Session views and Executors, execute Turns and report events and receipts | [Core–Runtime protocol](./runtime-protocol.md) | +| Sandbox I/O | Serve the sandbox's files, processes and network through the Core Link relay | [Sandbox link](./sandbox-link-protocol.md), [File access](./file-access-protocol.md), [Process](./process-protocol.md), [Network](./sandbox-network-protocol.md) | +| Credential gateway | Hold model and HTTP MCP credentials on the agent host and inject them into permitted upstream requests | [Model execution](../contracts/agents-api/model-execution.md#credential-gateway) | | Harness adapter | Validate native configuration, invoke the upstream SDK or protocol, translate events and confirm native cleanup | [Harness onboarding](../contracts/agents-api/harness-onboarding.md) | | Model provider | Serve the model protocol selected for the Harness | [Model execution](../contracts/agents-api/model-execution.md) | | Web | Let administrators configure and observe the installation through a server-side Core API connection | [Console server](./web/console-server.md) | @@ -42,8 +45,8 @@ The [repository map](./development.md#repository-map) locates these components. ## A Session, end to end -An application creates a Session through the Agents API. Core resolves its configuration and execution location. A managed Session obtains compute through the selected Sandbox Provider; a self-hosted Session waits for the user to run its installation command. A Session with `environment: none` uses a connected execution device without a workspace. The [application guide](./api/public-agent-api.md#create-a-session) describes these choices. +An application creates a Session through the Agents API. Core resolves and freezes its configuration. A managed Environment obtains compute through the selected Sandbox Provider; a self-hosted Environment waits for the user to run its installation command. In both cases Sandbox I/O must Serve the Environment's resource through the Link. The [application guide](./api/public-agent-api.md#create-a-session) describes these choices. -After the daemon connects, Core checks the available Harness and requested capabilities and binds the Session to that Runtime through a fenced [assignment](./runtime-protocol.md#session-assignments), which deleting the Session or releasing its Environment releases. The Runtime prepares a workspace Environment and its capability snapshot, then prepares or reuses the Session Executor. Each Turn runs through the native Harness. Core persists the output, tool interactions and receipts for application reads and events. Completion or cancellation settles the Turn; a healthy Executor can serve the next Turn in the same Environment. +Core binds every Session to an agent host through a fenced [assignment](./runtime-protocol.md#session-assignments). For a Session with an Environment, its Link resource must be Serving before Core sends the bind; Core separately waits for the agent host's bound acknowledgement before preparation or execution. The Runtime prepares the Environment and its capability snapshot, then prepares or reuses the Session Executor. Each Turn runs through the native Harness. Core persists output, tool interactions and receipts for application reads and events. Completion or cancellation settles the Turn; a healthy Executor can serve the next Turn. Session deletion or Environment release releases the assignment. Execution and compute have separate lifetimes: closing an Executor preserves its allocation and workspace until the Provider reclaims them. Preparation, connection and execution readiness have distinct states. The [Environment contract](../contracts/agents-api/environments.md) owns preparation, and the [Core–Runtime protocol](./runtime-protocol.md) owns ordering, receipts and failure handling. diff --git a/docs/configuration.md b/docs/configuration.md index 72c2b90ce..607b80ab0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -122,13 +122,13 @@ The named Docker volume `_data` contains these paths. Docker manages Li ## Docker node configuration -The node installer writes Docker’s host settings into the `native` object of the node’s configuration file, which only the Docker adapter reads. Deployment resources, the Runtime release and capacity remain in [Core’s database](#runtime-settings-web). +The node installer writes Docker’s host settings into the `native` object of the node’s configuration file, which only the Docker adapter reads. Deployment resources, the sandbox release and capacity remain in [Core’s database](#runtime-settings-web). | Field | Installer value | Meaning | | --- | --- | --- | | `host` | `unix:///var/run/docker.sock` | Explicit Docker Engine socket | -| `image` | The Runtime image’s local ID after loading | The release’s `image_id` or `image_manifest_digest`. The host’s image store decides which digest names the loaded image, so the value is node-local; the adapter accepts only these two | -| `network` | `oac-node-` | Runtime container network | +| `image` | The sandbox image’s local ID after loading | The release’s `image_id` or `image_manifest_digest`. The host’s image store decides which digest names the loaded image, so the value is node-local; the adapter accepts only these two | +| `network` | `oac-node-` | Sandbox container network | | `seccomp_file` | `/runtime/seccomp.json` | Matched distribution’s seccomp profile | The [Docker adapter](./sandbox-provider.md#docker-adapter) owns container isolation, volume layout and lifecycle behavior. diff --git a/docs/getting-started/install-options.md b/docs/getting-started/install-options.md index 28aecf694..c5b3917ab 100644 --- a/docs/getting-started/install-options.md +++ b/docs/getting-started/install-options.md @@ -110,11 +110,11 @@ curl -s -o /dev/null -w '%{http_code}\n' -H 'OpenAI-Beta: agents=v1' https://cor `401` means `/v1` reached Core, which asks for a key. `404` means it reached Web: fix the proxy, or application calls and every node connection will fail. -TLS verification stays on everywhere. With a private certificate authority, node hosts, self-hosted machines and the Runtime image must trust it. +TLS verification stays on everywhere. With a private certificate authority, the agent-host and sandbox images, node hosts and self-hosted machines must trust it for the HTTPS endpoints they call. ### Try it locally with a quick tunnel -A [Cloudflare quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) gives a trial installation with external ingress a temporary public HTTPS address. It forwards to one port, so put a local proxy with the same routes in front: +A [Cloudflare quick tunnel](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/) provides a temporary public HTTPS address for connection and download checks. [Quick Tunnels do not support SSE](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations), so Agents API streaming requires an HTTPS ingress that supports SSE. The tunnel forwards to one port, so put a local proxy with the same routes in front: ```caddyfile http://:8443 { diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 0640fe3d4..ad8d25448 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -22,7 +22,7 @@ This page follows the default path. Every flag, existing reverse proxies and off - Free port 8080 for Web. See [ports](./install-options.md#ports). Docker must be able to publish it; the installer does not change host policy. - For anything off this machine, the origin in `OAC_PUBLIC_URL` must be the address browsers, nodes and executors use. You can sign in on this machine first. -Sandbox nodes run on Linux amd64. When Core runs on macOS or Windows, connect a Linux node or use E2B. +Sandbox nodes run on Linux amd64. When the operator launcher runs on macOS or Windows, its Docker engine must still be Linux amd64; connect a Linux sandbox node or use E2B. ## Install diff --git a/docs/sandbox-provider.md b/docs/sandbox-provider.md index d6b209320..848c32c20 100644 --- a/docs/sandbox-provider.md +++ b/docs/sandbox-provider.md @@ -196,7 +196,7 @@ A [reset](../contracts/agents-api/sandbox-deployment.md#reset) is durable execut One snapshot and timestamp partition the held resources. Offline ownership comes from the allocation's or active placement's node, with the same 45-second connection and owner-epoch predicate as online presence, independently of provider readiness; no cleanup failure, offline state or empty read authorizes a synthetic release. At zero held resources, Core drains outside database transactions, rechecks under the deployment lock and clears the deployment in one transaction, then publishes a generation-bearing empty provider without fallible work. If the final write or drain fails, it restores the committed provider with a bounded owner context before releasing the mutation gate; if that recovery fails, admission stays fenced and the owner stops. -An administrator [Session archive](../contracts/agents-api/admin-api.md#session-archive) keeps its Project scope and hosted eligibility checks in a Session-first transaction, together with Environment expiry, cancellation, Runtime authority revocation and audit; a reset's background archive reconstructs the actual Project scope from trusted records and keeps the requester's provenance. The ordinary provider lifecycle releases compute and snapshots. Archive cancellation keeps a healthy receipt path until the terminal commit: only the archive that first revokes a device records its exact `archive_cancel_turn_id` (ordinary revocation clears it, and repeated cleanup keeps it), and the existing authenticated delivery may drain that cancellation for at most 20 seconds from the Turn's original `cancel_requested_at`. Core tracks the delivery through `done`, the cancellation acknowledgement and the terminal commit, independently of subscription removal, and grants no new connection, input, file or MCP authority or lease renewal. No transaction or lifecycle gate waits for the receipt, and a lost peer, expiry or restart falls back to ordinary failure and cleanup, never a fabricated cancelled outcome. +An administrator [Session archive](../contracts/agents-api/admin-api.md#session-archive) keeps its Project scope and hosted eligibility checks in a Session-first transaction, together with Environment expiry, cancellation and audit; a reset's background archive reconstructs the actual Project scope from trusted records and keeps the requester's provenance. For an allocated Environment, archive releases the Session's assignment without removing its native home and requests allocation cleanup. The ordinary provider lifecycle releases compute and snapshots. The shared agent-host credential remains valid. Cancellation follows the [Turn lifecycle](../contracts/agents-api/sessions-events.md#send-input): a cleanup request or confirmed sandbox release does not prove that the Turn has settled. ## Validate the integration @@ -227,7 +227,7 @@ The Docker Sandbox Provider ([`sandbox/docker`](https://github.com/MiniMax-AI/Op Create refuses to reuse retained volumes that have no container. It copies the Sandbox bootstrap file to `/home/runtime/sandbox-io-bootstrap.json` (mode 0600, UID 1000) and the `/environment` workspace, initialization and package directories into the container, which then runs `oac-sandbox-io --bootstrap-file /home/runtime/sandbox-io-bootstrap.json` as its entry point. The service is the container's first process and reaps its orphaned descendants, so the container needs no init process. When the created container does not have the configured CPU, memory and exact image, Create returns the error with `CreateSettled`. Docker has no lease, so Renew only reads the container state. Kill checks the ownership labels of the container and both volumes before removing any of them, then confirms that all three are gone. -The node uses the explicit Unix socket in its [provider configuration](./configuration.md#docker-node-configuration) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a Runtime. +The node uses the explicit Unix socket in its [provider configuration](./configuration.md#docker-node-configuration) and ignores `DOCKER_HOST`. No Docker socket, host home or Core credential is mounted into a sandbox. ### Seccomp profile diff --git a/docs/zh/architecture.md b/docs/zh/architecture.md index c43b15a1e..b48e129a4 100644 --- a/docs/zh/architecture.md +++ b/docs/zh/architecture.md @@ -1,32 +1,33 @@ --- title: "架构" source: docs/architecture.md -source_hash: bceec7f192812cd3d1895bb1b89c361c771dbb008ef50a44f2a153f8c555c925 +source_hash: 3370c6bf3fc8650530629fabf0ee40eca1e56890bab77ed3a7e9af5548c5f359 --- -OpenAgentCore 将编排、计算资源和原生执行分开。Core 负责 API 和持久状态。Sandbox Provider 管理计算资源。Runtime daemon 准备 Environment 并运行选定的 Harness；Harness 的原生 SDK 或协议负责模型与工具循环。 +OpenAgentCore 将编排、计算资源和原生执行分开。Core 负责 API 和持久状态。Sandbox Provider 管理计算资源。Runtime 在 Core 附近的 Linux agent host 上运行，通过 Sandbox I/O 准备 Environment，并在每个 Session 的视图中运行原生 Harness。Harness 的上游 SDK 或协议负责模型与工具循环。 ```mermaid flowchart TB - App["Application / official SDK"] <-->|"Agents API /v1: HTTP and SSE"| Core + App["Application / official SDK"] <-->|"Agents API /v1"| Core Web["Web administrator console"] <-->|"Core API /core/v1"| Core - Core["Core: authorization, configuration snapshots,
orchestration and durable state"] - Core --- DB[("PostgreSQL")] - Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider: Docker / E2B / microsandbox"] - SP -.->|"Provision compute and bootstrap Runtime"| R - User["User-machine installer"] -.->|"Start Runtime"| R - Core <-->|"Core–Runtime protocol:
preparation, execution, events and receipts"| R - subgraph Env["Environment: managed sandbox or user-owned machine"] - R["Runtime daemon"] --> P["Workspace and capability preparation"] - P -->|"Harness protocol"| A["Harness adapter"] - A <-->|"Native SDK or protocol"| H["Native Harness: model and tool loop"] - H <--> F["Workspace, tools and artifacts"] + Core <-->|"Durable state"| DB[("PostgreSQL")] + Core -->|"Sandbox Provider protocol"| SP["Sandbox Provider"] + Core <-->|"Core–Runtime protocol"| R + subgraph Host["Linux agent host"] + R["Runtime: preparation and execution"] --> H["Session view: native Harness"] + H <-->|"Model and HTTP MCP"| G["Credential gateway"] + end + G <--> Upstream["Model provider / HTTP MCP servers"] + R <-->|"File / Process / Network"| Link["Core Link relay"] + Link <--> IO + SP -.->|"Provision and bootstrap"| IO + User["Self-hosted installer"] -.->|"Start"| IO + subgraph Env["Managed sandbox or self-hosted machine"] + IO["Sandbox I/O service"] <--> F["Workspace, tools and stdio MCP"] end - H <-->|"Model API"| Model["Model provider"] - H <-->|"MCP"| MCP["Local or remote MCP servers"] ``` -虚线表示资源供应与安装。实线表示组件交互，包括进程内接口。daemon 主动向 Core 发起经过认证的 WebSocket 连接。[API 索引](api/index.md) 说明应用、运维和机器命名空间；[协议边界](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary) 列出各协议的代码和所属文档。 +虚线表示资源创建与安装，实线表示组件交互，包括进程内接口。agent host 通过已认证的 WebSocket 连接 Core；agent host 和 Sandbox I/O 连接 Core Link relay。`environment: none` 的 Session 有 assignment 和私有原生 home，没有沙箱工作区。[API 索引](./api/index.md)说明应用、操作员和机器的命名空间；[协议边界](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#protocols-at-every-boundary)列出每个协议的代码和拥有文档。 ## 组件职责 {#component-responsibilities} @@ -35,7 +36,9 @@ flowchart TB | Core | 认证调用方，解析并冻结配置，调度 Turn，处理取消和待处理交互，将资源与执行事实持久化到 PostgreSQL | [Core 服务](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/README.md) | | Sandbox Provider | 创建、观察、续期和回收计算资源；在其中启动 Sandbox I/O 服务 | [Sandbox Provider](sandbox-provider.md)、[沙箱引导](sandbox-bootstrap.md) | | Sandbox node | 运行 Docker 或 microsandbox 主机，协调分配给它的 generation 与 allocation | [Sandbox node 协议](../../contracts/agents-api/zh/node-generation-protocol.md) | -| Runtime | 准备工作区和能力，管理 Session Executor，执行 Turn 并报告事件与回执 | [Core–Runtime 协议](runtime-protocol.md) | +| agent host 上的 Runtime | 通过 Sandbox I/O 准备工作区和能力，管理 Session 视图和 Executor，执行 Turn 并报告事件与回执 | [Core–Runtime 协议](./runtime-protocol.md) | +| Sandbox I/O | 通过 Core Link relay 提供沙箱文件、进程和网络服务 | [Sandbox link](./sandbox-link-protocol.md)、[文件访问](./file-access-protocol.md)、[进程](./process-protocol.md)、[网络](./sandbox-network-protocol.md) | +| 凭据网关 | 在 agent host 上持有模型和 HTTP MCP 凭据，并将其注入允许的上游请求 | [模型执行](../../contracts/agents-api/zh/model-execution.md#credential-gateway) | | Harness adapter | 验证原生配置，调用上游 SDK 或协议，转换事件并确认原生清理完成 | [Harness 接入](../../contracts/agents-api/zh/harness-onboarding.md) | | Model provider | 提供 Harness 选定的模型协议 | [模型执行](../../contracts/agents-api/zh/model-execution.md) | | Web | 让管理员通过服务端 Core API 连接配置与观察安装实例 | [控制台服务端](web/console-server.md) | @@ -44,8 +47,8 @@ flowchart TB ## Session 的完整流程 {#a-session-end-to-end} -应用通过 Agents API 创建 Session。Core 解析其配置与执行位置。托管 Session 通过选定的 Sandbox Provider 获取计算资源；自托管 Session 等待用户运行安装命令。`environment: none` 的 Session 使用已连接的执行设备，不提供工作区。[应用指南](api/public-agent-api.md#create-a-session) 说明这些选项。 +应用通过 Agents API 创建 Session。Core 解析并冻结其配置。托管 Environment 通过选定的 Sandbox Provider 获取计算资源；自托管 Environment 等待用户运行安装命令。两种情况下，Sandbox I/O 都必须通过 Link Serve 该 Environment 的资源。[应用指南](api/public-agent-api.md#create-a-session)说明这些选项。 -daemon 连接后，Core 检查可用 Harness 和请求的能力，并通过受约束的[分配](./runtime-protocol.md#session-assignments)把 Session 绑定到该 Runtime；删除 Session 或释放其 Environment 会释放该分配。Runtime 准备工作区 Environment 及其能力快照，然后准备或复用 Session Executor。每个 Turn 通过原生 Harness 运行。Core 持久化输出、工具交互和回执，供应用读取和接收事件。完成或取消使 Turn 结算；健康的 Executor 可以在同一 Environment 中执行下一个 Turn。 +Core 通过受约束的[分配](./runtime-protocol.md#session-assignments)把每个 Session 绑定到 agent host。对于带有 Environment 的 Session，Core 发送 bind 前，该 Environment 的 Link resource 必须处于 Serving；在准备或执行前，Core 还要单独等待 agent host 的 bound 确认。Runtime 准备 Environment 及其能力快照，然后准备或复用 Session Executor。每个 Turn 通过原生 Harness 运行。Core 持久化输出、工具交互和回执，供应用读取和接收事件。完成或取消使 Turn 结算；健康的 Executor 可以执行下一个 Turn。删除 Session 或释放 Environment 会释放该分配。 执行与计算资源拥有独立生命周期：关闭 Executor 后，其 allocation 和工作区保留到 Provider 回收为止。准备、连接和执行就绪具有不同状态。[Environment 契约](../../contracts/agents-api/zh/environments.md) 负责准备规则，[Core–Runtime 协议](runtime-protocol.md) 负责顺序、回执和故障处理。 diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md index 8b77e8ca3..7e3bfa550 100644 --- a/docs/zh/configuration.md +++ b/docs/zh/configuration.md @@ -1,7 +1,7 @@ --- title: "配置参考" source: docs/configuration.md -source_hash: 9356569940dd30051693b6f16e0a80a843451f80185b8c618660c656163fcf87 +source_hash: 879929d69336b8212a8421d604b18076325afcad5ff336e34aa0aed8a0d1fb8c --- Core 安装的每项设置都恰好只有一个归属位置，分属以下三类： @@ -126,13 +126,13 @@ Web 的 **System** 页面显示该安装的地址、默认模型和沙箱配置 ## Docker 节点配置 {#docker-node-configuration} -节点安装程序会将 Docker 的主机设置写入节点配置文件的 `native` 对象，只有 Docker 适配器读取它。部署资源、Runtime 发行版本和容量仍存储在 [Core 的数据库](#runtime-settings-web)中。 +节点安装程序会将 Docker 的主机设置写入节点配置文件的 `native` 对象，只有 Docker 适配器读取它。部署资源、沙箱发行版本和容量仍存储在 [Core 的数据库](#runtime-settings-web)中。 | 字段 | 安装程序设置的值 | 含义 | | --- | --- | --- | | `host` | `unix:///var/run/docker.sock` | 显式 Docker Engine 套接字 | -| `image` | 加载后 Runtime 镜像的本地 ID | 发行版本的 `image_id` 或 `image_manifest_digest`。主机的镜像存储决定由哪个 digest 指代已加载的镜像，因此该值属于节点本地；适配器只接受这两个值 | -| `network` | `oac-node-` | Runtime 容器网络 | +| `image` | 加载后沙箱镜像的本地 ID | 发行版本的 `image_id` 或 `image_manifest_digest`。主机的镜像存储决定由哪个 digest 指代已加载的镜像，因此该值属于节点本地；适配器只接受这两个值 | +| `network` | `oac-node-` | 沙箱容器网络 | | `seccomp_file` | `/runtime/seccomp.json` | 所匹配发行版的 seccomp 配置文件 | [Docker 适配器](sandbox-provider.md#docker-adapter)负责容器隔离、卷布局和生命周期行为。 diff --git a/docs/zh/getting-started/install-options.md b/docs/zh/getting-started/install-options.md index 5999b779b..f281a02e1 100644 --- a/docs/zh/getting-started/install-options.md +++ b/docs/zh/getting-started/install-options.md @@ -1,7 +1,7 @@ --- title: "安装选项" source: docs/getting-started/install-options.md -source_hash: a6920271d21280686ae8df889f8de499da4dc2572bc1a80d4a567e3861a1c520 +source_hash: e600effab6cb2c4d1ee31c54781eb3a6bd9ad8d8f794078f3b827385bb450f68 --- [默认安装](install.md)无需任何选项。本页介绍安装选项、Compose 部署和反向代理配置。 @@ -114,11 +114,11 @@ curl -s -o /dev/null -w '%{http_code}\n' -H 'OpenAI-Beta: agents=v1' https://cor `401` 表示 `/v1` 已到达 Core，Core 正在要求提供密钥。`404` 表示请求已到达 Web：请修复反向代理，否则应用调用和每个节点连接都会失败。 -所有位置都必须保持启用 TLS 验证。使用私有证书颁发机构时，节点主机、自托管机器和 Runtime 镜像必须信任该机构。 +所有位置都必须保持启用 TLS 验证。使用私有证书颁发机构时，agent-host 和沙箱镜像、节点主机以及自托管机器必须信任其访问的 HTTPS 端点所使用的机构。 ### 使用快速隧道进行本地试用 {#try-it-locally-with-a-quick-tunnel} -[Cloudflare 快速隧道](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)会为使用外部入口的试用安装提供一个临时公共 HTTPS 地址。它只会转发到一个端口，因此需要在前面放置一个具有相同路由的本地代理： +[Cloudflare 快速隧道](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/)提供临时公共 HTTPS 地址，可用于连接和下载检查。[Quick Tunnel 不支持 SSE](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations)，因此 Agents API 流式调用需要支持 SSE 的 HTTPS 入口。隧道只转发到一个端口，因此需要在前面放置一个具有相同路由的本地代理： ```caddyfile http://:8443 { diff --git a/docs/zh/getting-started/install.md b/docs/zh/getting-started/install.md index df4812da7..7cf999372 100644 --- a/docs/zh/getting-started/install.md +++ b/docs/zh/getting-started/install.md @@ -1,7 +1,7 @@ --- title: "安装 Core 和 Web" source: docs/getting-started/install.md -source_hash: baa93565e3ec6c26752f692a3ad7771dc1b5259f98350620381b4d4315014a2e +source_hash: 0753c0a4b761a6cb16181413a6567245be03cb4805469a65e0aebf2bea344a9f --- 一条命令即可在 Linux amd64 Docker 引擎上安装 Core、Web 控制台、agent host 和 PostgreSQL。操作员启动器也可在 macOS 和 Windows 上运行。用 Core 密钥登录 Web，设置默认模型并签发 Project API 密钥。应用使用这些密钥调用 Core。Session 在你添加的节点上的沙箱中运行，也可以在 E2B 上运行。 @@ -24,7 +24,7 @@ source_hash: baa93565e3ec6c26752f692a3ad7771dc1b5259f98350620381b4d4315014a2e - Web 的 8080 端口空闲。参阅[端口](install-options.md#ports)。Docker 必须能发布该端口；安装程序不会修改主机策略。 - 本机以外的访问要求 `OAC_PUBLIC_URL` 就是浏览器、节点和执行器使用的地址。可以先在本机登录。 -沙箱节点运行在 Linux amd64 上。在 macOS 或 Windows 上部署 Core 时，可连接 Linux 节点，或使用 E2B。 +沙箱节点运行在 Linux amd64 上。操作员启动器在 macOS 或 Windows 上运行时，其 Docker 引擎仍必须是 Linux amd64；请连接 Linux 沙箱节点或使用 E2B。 ## 安装 {#install} diff --git a/docs/zh/sandbox-provider.md b/docs/zh/sandbox-provider.md index 843e73206..5dc9f7145 100644 --- a/docs/zh/sandbox-provider.md +++ b/docs/zh/sandbox-provider.md @@ -1,7 +1,7 @@ --- title: "添加 Sandbox Provider" source: docs/sandbox-provider.md -source_hash: 6378777af8dce6438d8796b51f5b737837e2ce56092fe2c48baf0ba91c0e4aea +source_hash: 11794813cac6e3f5613935905eeee54fb72c3bdd4d05b4e84f9f4b0702f26aba --- **Sandbox Provider** 为 Core 管理的 Environment 提供计算资源，以及在其中启动 [Sandbox I/O 服务](#oac-sandbox-io)的有界引导流程；该服务是 Provider 启动的唯一进程。本指南说明如何添加 Provider，并作为 Core 驱动 Provider 的参考。接口为 [`SandboxProvider`](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/services/core/internal/sandbox/sandbox_provider.go)。 @@ -198,7 +198,7 @@ Worker lease、Session lock 与 per-node gate 对每个 provider 负责 suspensi 一个 snapshot 和 timestamp 对持有资源分区。离线 ownership 来自 allocation 或 active placement 的 node，与 online presence 使用同一 45 秒 connection 和 owner-epoch predicate，独立于 provider readiness；cleanup failure、offline state 或空 read 都不授权合成 release。held resource 为零时，Core 在数据库事务外 drain，在 deployment lock 下复查，并在一个事务中清空 deployment，再发布携带 generation 的空 provider，没有可失败工作。最终 write 或 drain 失败时，在释放 mutation gate 前使用有界 owner context 恢复已提交 provider；恢复失败时 admission 保持 fenced，owner 停止。 -管理员 [Session archive](../../contracts/agents-api/zh/admin-api.md#session-archive) 在 Session-first transaction 中保留 Project scope 与 hosted eligibility 检查，并一起处理 Environment expiry、cancellation、Runtime authority revocation 和 audit；reset 的后台 archive 从可信记录重建实际 Project scope，保留请求方 provenance。普通 provider lifecycle 释放 compute 和 snapshot。archive cancellation 在 terminal commit 前保留健康 receipt path：仅首次撤销 device 的 archive 记录精确 `archive_cancel_turn_id`（普通 revocation 清空它，重复 cleanup 保留它），现有已认证 delivery 可从 Turn 原 `cancel_requested_at` 起最多 20 秒排空该 cancellation。Core 独立于 subscription removal，通过 `done`、cancellation acknowledgement 和 terminal commit 跟踪 delivery，不授予新 connection、input、file 或 MCP authority，也不续期 lease。事务或 lifecycle gate 不等待 receipt，peer 丢失、到期或重启回到普通 failure 与 cleanup，不虚构 cancelled outcome。 +管理员 [Session archive](../../contracts/agents-api/zh/admin-api.md#session-archive) 在 Session-first transaction 中保留 Project scope 与 hosted eligibility 检查，并一起处理 Environment expiry、cancellation 和 audit；reset 的后台 archive 从可信记录重建实际 Project scope，保留请求方 provenance。对于已有 allocation 的 Environment，archive 释放 Session 的 assignment，保留其原生 home，并请求 allocation cleanup。普通 provider lifecycle 释放 compute 和 snapshot。共享的 agent-host 凭据仍然有效。取消遵循 [Turn 生命周期](../../contracts/agents-api/zh/sessions-events.md#send-input)：请求 cleanup 或确认沙箱已释放，都不能证明 Turn 已结算。 ## 验证集成 {#validate-the-integration} @@ -229,7 +229,7 @@ Docker Sandbox Provider（[`sandbox/docker`](https://github.com/MiniMax-AI/OpenA Create 拒绝复用没有 container 的保留 volume。它将沙箱引导文件复制到 `/home/runtime/sandbox-io-bootstrap.json`（mode 0600、UID 1000），并将 `/environment` workspace、initialization 和 package directory 放入 container；container 以 `oac-sandbox-io --bootstrap-file /home/runtime/sandbox-io-bootstrap.json` 作为 entry point 运行。该服务是 container 的第一个进程，并回收其孤儿后代进程，因此 container 不需要 init process。创建的 container 不具备配置的 CPU、memory 和精确 image 时，Create 返回 error 和 `CreateSettled`。Docker 没有 lease，因此 Renew 仅读取 container state。Kill 在删除前检查 container 和两个 volume 的 ownership label，再确认三者都已不存在。 -node 使用 [provider 配置](configuration.md#docker-node-configuration)中的明确 Unix socket，忽略 `DOCKER_HOST`。不将 Docker socket、host home 或 Core credential 挂载进 Runtime。 +node 使用 [provider 配置](configuration.md#docker-node-configuration)中的明确 Unix socket，忽略 `DOCKER_HOST`。不将 Docker socket、host home 或 Core credential 挂载进沙箱。 ### Seccomp profile {#seccomp-profile} diff --git a/services/core/internal/deployment/storage.go b/services/core/internal/deployment/storage.go index 3c1e05ea7..c2ce9d00d 100644 --- a/services/core/internal/deployment/storage.go +++ b/services/core/internal/deployment/storage.go @@ -159,10 +159,7 @@ type SessionArchiveTx interface { // one. FindAllocation(environment string) (Allocation, bool, error) // RequestArchiveCleanup releases the Session's Runtime assignment without - // home removal, revokes the allocation's device and records that its - // resources await cleanup. The device's first revocation records the - // Session's active Turn whose cancellation was requested, which the - // archived cancellation receipt reports. + // home removal and records that its allocation's resources await cleanup. RequestArchiveCleanup(current Allocation) error // ReleasePlacement releases the node placement of the Session's // Environments that have no allocation.