diff --git a/AGENTS.md b/AGENTS.md index 95f19d2ca..7bac569df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,6 +44,17 @@ Do not multiply entities without necessity. The long-term goal is minimal code, - Fix shared lifecycle, admission, cancellation, reuse and performance problems in the common flow, never in a branch selected by Harness, Runtime or vendor name. Core preparation and execution never branch on operating system or Environment source; platform support requires native CI builds and automated tests. - Each Harness runs its own model and tool loop through a maintained upstream SDK or native protocol, in the Environment's declared workspace directory. Its native history or configuration directory is never the workspace. Never build a second executor, a hand-written model/tool loop or a compatibility framework to fabricate parity. The public API and persistence never depend on one engine's native item types. +### Core assembles, Harnesses run natively + +Choosing a Harness and a model behaves like running that Harness locally with that model. The only differences are the cloud Environment, isolation, credentials and unattended operation. + +- Core assembles configuration and passes it through. When a Harness or model natively supports what an official field expresses, the adapter maps the field to the native setting and the native side runs it. If the provider cannot run it, the provider's own error returns unchanged. Core qualifies nothing on a provider's behalf. It adds nothing to model input and has no fallback, retry or substitute path. Authentication, isolation and credential protection are assembly and stay in Core. +- A Harness joins through one declaration file, `internal/harnessconfig//declaration.go`, plus its adapter code ([declare the Harness](contracts/agents-api/harness-onboarding.md#declare-the-harness)). The declaration is the only source of support facts, and every other projection is generated from it. +- An official field with no native home returns a typed error. Dropping it silently would be a fallback. +- A default defined by the pinned official API applies. Everything else follows the native default, and Core sends nothing for it. +- An adapter overrides a native default only when the Harness cannot otherwise run unattended in the cloud. The allowed reasons are: tools run without approval prompts, no ask-the-user tool, the workspace and state paths, credential isolation, bounded failure instead of waiting, no work that outlives its Turn, and no feature that needs an account credential Core does not hold. Each override has a one-line reason beside it, and the adapter guide lists it. +- Never branch on the model or provider. When a model lacks a feature, the Harness handles it as it would locally. + ### Public API - The target is the complete OpenAI Agents API (`openai/openai-python` `beta/agents`) as pinned in [`contracts/agents-api/upstream.json`](contracts/agents-api/upstream.json): paths, methods, headers, field presence, nullability, discriminators, defaults, status transitions, pagination, errors and streaming. Engine limitations are gaps to close, never grounds to narrow or redefine the contract. Operations or fields newer than the pinned baseline wait for a protocol upgrade. diff --git a/README.ja.md b/README.ja.md index f24107b01..e12d93c55 100644 --- a/README.ja.md +++ b/README.ja.md @@ -16,7 +16,7 @@ - **OpenAI と同じ API。** `OPENAI_BASE_URL` を設定すれば、[公式 OpenAI SDK](https://developers.openai.com/api/docs/libraries)または直接の HTTP リクエストがそのまま動作します。 -- **自分のエージェント、自分のモデル。** 各 Session は Codex、Claude Code、MiniMax Code のいずれかをネイティブに実行し、設定したモデルプロバイダーを使用します。詳しくは [Harness の機能](https://openagentcore.dev/contracts/agents-api/harness-capabilities)をご覧ください。 +- **自分のエージェント、自分のモデル。** 各 Session は Codex、Claude Code、MiniMax Code のいずれかを手元のマシンと同じようにネイティブに実行し、設定したモデルプロバイダーを使用します。詳しくは [Harness の機能](https://openagentcore.dev/contracts/agents-api/harness-capabilities)をご覧ください。 - **計算資源は休止し、ワークスペースは残る。** microsandbox と独立したワークスペースストレージの組み合わせでは、アイドル状態のサンドボックスが計算資源を解放し、互換性のあるノードでファイルをそのまま再開します。E2B、Docker、自分の Linux、macOS、Windows マシンでも Session を実行できます。詳しくは[Sandbox Provider protocol](https://openagentcore.dev/docs/sandbox-provider)をご覧ください。 - **置き換え可能なコンポーネント。** サンドボックスプロバイダー、ワークスペースファイルシステム、Harness、モデルプロバイダーは、[定義されたプロトコル](AGENTS.md#protocols-at-every-boundary)を通じて接続されます。 diff --git a/README.md b/README.md index 9b74794a9..e0074a0cd 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The OpenAI Agents API, open source and self-hosted. Run Codex, Claude Code or Mi - **Same API as OpenAI.** Set `OPENAI_BASE_URL` and the [official OpenAI SDK](https://developers.openai.com/api/docs/libraries), or plain HTTP, works unchanged. -- **Your agent, your model.** Each Session runs Codex, Claude Code or MiniMax Code natively, with the model provider you configure. See [Harness capabilities](https://openagentcore.dev/contracts/agents-api/harness-capabilities). +- **Your agent, your model.** Each Session runs Codex, Claude Code or MiniMax Code natively, as it runs on your machine, with the model provider you configure. See [Harness capabilities](https://openagentcore.dev/contracts/agents-api/harness-capabilities). - **Compute that sleeps, workspaces that stay.** On microsandbox with independent workspace storage, idle sandboxes release compute and resume on a compatible node with their files intact. E2B, Docker and your own Linux, macOS or Windows machine also run Sessions. See [Sandbox Provider protocol](https://openagentcore.dev/docs/sandbox-provider). - **Replaceable parts.** Sandbox Providers, workspace filesystems, Harnesses and model providers plug in through [defined protocols](AGENTS.md#protocols-at-every-boundary). diff --git a/README.zh-CN.md b/README.zh-CN.md index 55c0f052e..2c7f9e50a 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -16,7 +16,7 @@ - **与 OpenAI 相同的 API。** 设置 `OPENAI_BASE_URL` 后，[官方 OpenAI SDK](https://developers.openai.com/api/docs/libraries)或直接的 HTTP 调用无需改动即可使用。 -- **你的 Agent，你的模型。** 每个 Session 原生运行 Codex、Claude Code 或 MiniMax Code，并使用你配置的模型提供商。详见 [Harness 能力](https://openagentcore.dev/zh/contracts/agents-api/harness-capabilities)。 +- **你的 Agent，你的模型。** 每个 Session 原生运行 Codex、Claude Code 或 MiniMax Code，使用你配置的模型提供商，与在本机运行一致。详见 [Harness 能力](https://openagentcore.dev/zh/contracts/agents-api/harness-capabilities)。 - **计算会休眠，工作区会保留。** 在 microsandbox 配合独立工作区存储时，空闲沙箱释放计算资源，并在兼容节点上带着文件恢复。E2B、Docker 以及你自己的 Linux、macOS 或 Windows 机器同样可以运行 Session。详见[沙箱提供商协议](https://openagentcore.dev/zh/docs/sandbox-provider)。 - **部件可替换。** 沙箱提供商、工作区文件系统、Harness 和模型提供商都通过[既定协议](AGENTS.md#protocols-at-every-boundary)接入。 diff --git a/contracts/agents-api/harness-capabilities.md b/contracts/agents-api/harness-capabilities.md index ed3e0595c..57636381c 100644 --- a/contracts/agents-api/harness-capabilities.md +++ b/contracts/agents-api/harness-capabilities.md @@ -4,6 +4,8 @@ title: "Harness capabilities" This page lists what each Harness supports on each placement. Core decides admission from the Harness's declaration in `internal/harnessconfig//declaration.go`, and the Runtime that runs the Session must also advertise the operation. The linked contracts define each operation; [Harness onboarding](./harness-onboarding.md#qualify-the-adapter) describes how a Harness is qualified. +Anything this page does not list follows the Harness's native behavior with the selected model, as in a local run. Each adapter guide lists the native defaults it overrides for unattended cloud execution ([design rule](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#core-assembles-harnesses-run-natively)). + | Status | Meaning | | --- | --- | | Verified | Core admits it, and real-model acceptance through the pinned official client passed on that placement | diff --git a/contracts/agents-api/harness-onboarding.md b/contracts/agents-api/harness-onboarding.md index 1a0f3566e..098bbe718 100644 --- a/contracts/agents-api/harness-onboarding.md +++ b/contracts/agents-api/harness-onboarding.md @@ -49,7 +49,7 @@ Implement the mandatory text lifecycle and handle every extension explicitly. Qu ## Architecture rules -[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) applies to every Harness. These rules are Harness-specific: +[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) and [Core assembles, Harnesses run natively](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#core-assembles-harnesses-run-natively) apply to every Harness. These rules are Harness-specific: - Keep required lifecycle declarations, extension interfaces and registration methods in `agent/harness.go`. Result types, errors and Registry storage may stay in focused files. - Use the existing `proto.SupportedAgentKind` and `AgentKindCapabilities` schema. Do not add a second capability descriptor or a combined optional interface. - Onboarding does not require feature equality. Harnesses need not match each other's optional features, and MCP, functions, images or verbosity control are not required to register. Verify the common lifecycle obligations and use the same public assertions for each declared operation. An omitted declaration or a missing extension implementation blocks onboarding; a native difference does not. diff --git a/contracts/agents-api/zh/harness-capabilities.md b/contracts/agents-api/zh/harness-capabilities.md index 77c4a4520..df837f84d 100644 --- a/contracts/agents-api/zh/harness-capabilities.md +++ b/contracts/agents-api/zh/harness-capabilities.md @@ -1,11 +1,13 @@ --- title: "Harness 能力" source: contracts/agents-api/harness-capabilities.md -source_hash: c76b7f62749647860c2623546574eadf28552aa4e525dad072dfc637091bb4b0 +source_hash: c471671c3e4518b2968fc36fd5310edf449de5684fc976ebf0c015996aca3b6c --- 本页列出每个 Harness 在每种部署位置支持的能力。Core 根据 `internal/harnessconfig//declaration.go` 中 Harness 的声明决定准入，运行 Session 的 Runtime 也必须声明操作。所链接契约定义各操作；[Harness 接入](harness-onboarding.md#qualify-the-adapter)说明资格验证方法。 +本页未列出的行为遵循 Harness 在所选模型下的原生行为，与本地运行一致。每个适配器指南列出它为云端无人值守执行而覆盖的原生默认值（[设计规则](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#core-assembles-harnesses-run-natively)）。 + | 状态 | 含义 | | --- | --- | | 已验证 | Core 允许准入，且该位置通过固定版本官方客户端的真实模型验收 | diff --git a/contracts/agents-api/zh/harness-onboarding.md b/contracts/agents-api/zh/harness-onboarding.md index 0fe34bd27..999b63022 100644 --- a/contracts/agents-api/zh/harness-onboarding.md +++ b/contracts/agents-api/zh/harness-onboarding.md @@ -1,7 +1,7 @@ --- title: "Harness 协议" source: contracts/agents-api/harness-onboarding.md -source_hash: 9440f55f079d3a54c6fa4f2bd9e7063edc1370440057874412e86b8b2bd19fc7 +source_hash: 23717fd39df7a88a93bb12a7b4e68862f6ea7d514054d4765673df3b3ea98b96 --- **Harness** 是一种运行模型和工具循环的原生代理引擎（Codex、Claude Code、MiniMax Code）；**Harness 适配器**将 Runtime 的 Executor 和 Turn 契约转换到该引擎的 SDK 或协议。Harness 协议是 Runtime 与适配器之间的契约：适配器接口及其生命周期义务、声明、注册和验收。本文面向添加或维护 Harness 的开发者。 @@ -51,7 +51,7 @@ Environment 提供执行资源。受管 E2B、Docker 和 microsandbox 机器以 ## 架构规则 {#architecture-rules} -[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) 适用于每个 Harness。以下规则为 Harness 专有： +[Complexity stays in the adapter](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#complexity-stays-in-the-adapter) 和 [Core assembles, Harnesses run natively](https://github.com/MiniMax-AI/OpenAgentCore/blob/main/AGENTS.md#core-assembles-harnesses-run-natively) 适用于每个 Harness。以下规则为 Harness 专有： - 将必需的生命周期声明、扩展接口和注册方法保留在 `agent/harness.go` 中。结果类型、错误和 Registry 存储可以保留在聚焦的文件中。 - 使用现有的 `proto.SupportedAgentKind` 和 `AgentKindCapabilities` schema。不要添加第二套能力描述符或组合式可选接口。 - 接入不要求功能完全一致。Harness 不必匹配彼此的可选功能，并且注册时不强制要求 MCP、函数、图像或详细程度控制。验证通用生命周期义务，并对每个声明的操作使用相同的公共断言。缺少声明或扩展实现会阻止接入；原生差异不会。