Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion contracts/agents-api/environment-files.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ The response is `{"object": "page", "data": [...], "next": …, "has_more": …}
- A `path` that does not exist, names a regular file, or passes through a symbolic link returns an empty page. Links are never followed.
- Each page reads the directory again; there is no snapshot. If the directory's regular files (their names or sizes) or the request's parameters changed since the token was issued, the token is rejected. Unchanged names and sizes do not prove unchanged contents.
- A directory with more than 1,024 entries of any kind returns 503 and no partial page. Permission errors, a missing workspace root and transport failures also return 503.
- When the daemon has no local workspace binding, the Claude Code adapter answers the read instead: a missing path returns 404, and a regular file or symbolic link returns 503.

Query errors, all with type and code `invalid_request_error` and a null `param` unless noted:

Expand Down
6 changes: 5 additions & 1 deletion contracts/agents-api/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ Each item is Core's deliberate or native behavior where the official service beh
- A JSON array body is rejected; the official service reads `[]` as `{}`.
- U+0000 in a stored string returns 400; the official service stores it.
- Not-found messages never name the resource; Core quotes a full metadata key where the official message abbreviates it.
- Resource IDs are UUIDs; official IDs carry a type prefix, such as `sess_` for Sessions.
- UUID identifiers also resolve in other spellings, such as uppercase or braces.
- The Files routes keep a local `unsupported_parameter` code for a repeated query key.
- Core has no CORS handling; the official service sends CORS headers.
Expand Down Expand Up @@ -108,6 +109,7 @@ Each item is Core's deliberate or native behavior where the official service beh

- `openai_hosted` and Template `capability_directories` must lie inside `/workspace`; the official service also accepts system paths such as `/etc` ([capability directories](./environments.md#plugins-and-capability-directories)).
- `env` cannot set `OPENAI_API_KEY`, which Core reserves ([env](./environments.md#env-and-setup-commands)); the official service accepts it.
- A `self_hosted` Session without pending input requests no connection ([activity](./environments.md#activity-and-required-actions)); one unused official Session switched to `requires_action` with `environment_connection` about five minutes after creation, and its deletion then returned 409.

**Files, Skills, Environment files and Artifacts** ([Files and Skills](./source-files.md), [Environment files and Artifacts](./environment-files.md))

Expand All @@ -117,7 +119,6 @@ Each item is Core's deliberate or native behavior where the official service beh
- Creating an Environment file over an existing regular file returns the "must not traverse symlinks or overwrite existing files" message. A parent symbolic link that stays inside the workspace is followed, and a parent that escapes the workspace or is a regular file gets a generic 400; the official service rejects symbolic-link parents.
- File names hold 1–1,024 bytes; the official service accepts empty and longer names.
- A `SKILL.md` front-matter key other than `name`, `description`, `license`, `compatibility` and `metadata` is rejected; the official service accepts unknown keys ([upload a bundle](./source-files.md#upload-a-bundle)).
- Artifact IDs are UUIDs.

**Vaults and Credentials** ([Vaults and Credentials](./vaults.md))

Expand Down Expand Up @@ -186,6 +187,9 @@ Each item is Core's deliberate or native behavior where the official service beh
- The official order between the pending-input error and an unknown result target.
- Whether a Session whose latest Turn failed accepts new input: Core starts a new Turn, and one official sample rejected the input.
- The event order when a waiting Turn resumes or is cancelled.
- A Turn with several pending function calls: Core lists them all in one `requires_action`; no official sample had parallel calls.
- Subagent task text and nesting: Core puts the native task prompt in the `create_subagent_call` content, while one official sample left it out; the `agent_id` of a nested child and the child's input Item have no official sample.
- Template `env` beside Session `env`: Core merges by key and the Session value wins ([inheritance](./environments.md#inheritance)).
- Failure reasons for npm, initial-file and Skill installation have no official sample.
- Codex behavior for an empty text part beside text, and for images in failed function results or as remote references.
- Official `HEAD` behavior on the routes where Core returns 405.
Expand Down
3 changes: 1 addition & 2 deletions contracts/agents-api/zh/environment-files.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Environment 文件与 Artifact"
source: contracts/agents-api/environment-files.md
source_hash: b6c51bd066cf70b6cce4c38ba1403dc3463574fcbc254bf64f8c98b6aeca9b93
source_hash: ad6e0c122104ff5600d07305902871253c81aef0525e12358a5cc8abdc42600a
---

Session 工作区保存由 agent 及其工具修改的实时文件。`/agents/environments/{environment_id}/files` 列出一个工作区目录,并在其中创建文件。Turn 完成时,Core 将工作区 `outputs/` 目录中的文件复制为不可变 Artifact,通过 `/agents/sessions/{session_id}/artifacts` 读取。Artifact 的生命周期长于 Environment;工作区文件则不是。
Expand Down Expand Up @@ -33,7 +33,6 @@ Session 工作区保存由 agent 及其工具修改的实时文件。`/agents/en
- `path` 不存在、指向普通文件或经过符号链接时返回空页。不跟随链接。
- 每页重新读取目录,不提供快照。token 签发后目录普通文件(名称或大小)或请求参数改变时,token 被拒绝。名称和大小未变不证明内容未变。
- 目录中任何类型条目合计超过 1,024 个时返回 503,不返回部分页。权限错误、工作区根缺失和传输失败也返回 503。
- daemon 无本地工作区绑定时,改由 Claude Code 适配器回答读取:路径缺失返回 404,普通文件或符号链接返回 503。

查询错误的 type 和 code 均为 `invalid_request_error`,除另有说明外 `param` 为 null:

Expand Down
8 changes: 6 additions & 2 deletions contracts/agents-api/zh/index.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "OpenAI 兼容性"
source: contracts/agents-api/index.md
source_hash: ab06803446379f5a4e3525070360654f67d2bf6e4285ae10af9ef1dd551f25ff
source_hash: 09fcf64102a376e53b2881621c21647afb7187e3899ef6c4b9f350fa7a2d95fe
---

Core 实现下方固定版本的 OpenAI Agents API。本台账列出各项资源的覆盖情况、相对于官方服务的所有差异以及已知缺口。
Expand Down Expand Up @@ -59,6 +59,7 @@ Core 自身字段位于 `x_agents_core` 中([Core extensions](../../../docs/zh
- JSON 数组请求体会被拒绝;官方服务会将 `[]` 读取为 `{}`。
- 存储的字符串中含有 U+0000 时会返回 400;官方服务会存储该字符。
- 未找到消息从不会指明具体资源;Core 会给完整的元数据键加引号,而官方消息会将其缩略。
- 资源 ID 均为 UUID;官方 ID 带有类型前缀,例如 Session 的 `sess_`。
- UUID 标识符也可按其他拼写形式解析,例如大写形式或带花括号的形式。
- 对于重复的查询键,Files 路由会保留本地 `unsupported_parameter` 代码。
- Core 不处理 CORS;官方服务会发送 CORS 标头。
Expand Down Expand Up @@ -111,6 +112,7 @@ Core 自身字段位于 `x_agents_core` 中([Core extensions](../../../docs/zh

- `openai_hosted` 和模板的 `capability_directories` 必须位于 `/workspace` 内;官方服务也接受 `/etc` 等系统路径([能力目录](environments.md#plugins-and-capability-directories))。
- `env` 不能设置 Core 保留的 `OPENAI_API_KEY`([env](environments.md#env-and-setup-commands));官方服务接受该变量。
- 没有待处理输入的 `self_hosted` Session 不会请求连接([活动状态](environments.md#activity-and-required-actions));一个未使用的官方 Session 在创建约五分钟后转为 `requires_action`,原因为 `environment_connection`,之后删除它返回 409。

**Files、Skills、Environment files 和 Artifacts**([Files and Skills](source-files.md)、[Environment files and Artifacts](environment-files.md))

Expand All @@ -120,7 +122,6 @@ Core 自身字段位于 `x_agents_core` 中([Core extensions](../../../docs/zh
- 在已有常规文件上创建 Environment file 会返回 "must not traverse symlinks or overwrite existing files" 消息。若父级符号链接仍位于工作区内,则会跟随该链接;若父级逸出工作区或父级本身是常规文件,则会返回通用 400;官方服务会拒绝父级符号链接。
- 文件名长度为 1–1,024 字节;官方服务接受空文件名和更长的文件名。
- `SKILL.md` front matter 中 `name`、`description`、`license`、`compatibility` 和 `metadata` 以外的键会被拒绝;官方服务接受未知键([上传 bundle](source-files.md#upload-a-bundle))。
- Artifact ID 均为 UUID。

**Vaults 和 Credentials**([Vaults and Credentials](vaults.md))

Expand Down Expand Up @@ -189,6 +190,9 @@ Core 自身字段位于 `x_agents_core` 中([Core extensions](../../../docs/zh
- 官方服务在待处理输入错误与未知结果目标之间的先后顺序。
- 最新 Turn 失败的 Session 是否接受新输入:Core 会开始新的 Turn,而一个官方样本拒绝了该输入。
- 等待中的 Turn 恢复或被取消时的事件顺序。
- 有多个待处理函数调用的 Turn:Core 在同一个 `requires_action` 中列出全部调用;官方样本中没有并行调用。
- Subagent 的任务文本和嵌套:Core 把原生任务提示放在 `create_subagent_call` 的内容中,而一个官方样本省略了它;嵌套子级的 `agent_id` 和子级的输入 Item 没有官方样本。
- 模板 `env` 与 Session `env` 并存:Core 按键合并,以 Session 的值为准([继承](environments.md#inheritance))。
- npm、initial-file 和 Skill 安装的失败原因没有官方样本。
- Codex 对文本旁的空文本部分、失败函数结果中的图像或远程引用图像的行为。
- 在 Core 返回 405 的路由上,官方服务的 `HEAD` 行为。
Expand Down
Loading