AnthropicClaude 托管智能体
创建会话
创建会话。使用当前 API Key 所属工作区的资源。
先调用「创建智能体」，用返回的智能体 ID 替换示例 ID。
POST
/anthropic/v1/sessions◐ 部分支持请求体
agentstring | object必填会话要运行的智能体：直接写智能体 ID 字符串（固定用最新版本），或传对象指定 id 与 version（见子字段）。
▸ 展开子字段（8）
idstring必填会话要运行的智能体 ID。
typestring必填引用类型，目前只有 agent。
versionnumber可选固定使用的智能体版本；省略用最新版本。
mcp_serversarray可选替换本会话的 MCP 服务器列表：传入的数组整体生效；传空数组清除，省略沿用智能体的配置。
modelstring | object可选替换本会话的模型：模型名字符串（如 claude-opus-5）或配置对象；省略沿用智能体自身的模型。
skillsarray可选替换本会话的 Skill 列表；传空数组清除，省略沿用智能体的配置。
systemstring可选替换本会话的系统提示词，最长 100,000 字符；传 null 清除，省略沿用智能体的。
toolsarray可选替换本会话的工具配置；传空数组清除，省略沿用智能体的配置。
environment_idstring必填会话运行所在的环境 ID，决定容器的基础环境。
budgetobject可选○ 未支持会话的预算上限设置。
▸ 展开子字段（2）
max_list_costobject必填预算内列表类调用的花费上限。
typestring必填预算类型，目前只有 max_list_cost。
initial_eventsarray可选创建时按顺序发给会话的初始事件，支持 user.message 与 user.define_outcome，一次最多 50 条。
metadataobject可选会话的自定义元数据键值对。
resourcesarray可选◐ 部分支持要挂载进会话容器的资源（如代码仓库、文件）。
titlestring可选会话标题，便于在控制台辨认。
vault_idsarray可选○ 未支持保险库 ID 列表：会话里智能体可以使用这些已存凭据。
返回
200
先创建智能体，将示例 agent_123 换成返回的 id。Anthropic 兼容 API 的 environment_id 必填，可用 node22 或租户自建 cloud 环境；/agent/v1 可省略 environment_id 得到轻量机器。不支持内联智能体覆盖、预算与凭据库。 支持 file 类型资源的持久化、查询和解除关联，单会话最多 500 条。文件须属于当前租户且有效。默认路径为 /mnt/session/uploads/<file_id>，自定义路径归一到该目录，拒绝父目录遍历。不修改文件内容；本批尚不将资源同步到沙箱。
错误按 Claude Managed Agents 格式返回，参见 错误码
响应
HTTP 200
Successful response
application/json
| 名称 | 类型 | 说明 |
|---|---|---|
| id | string | |
| agent | object | Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time. |
| agent.id | string | |
| agent.description | null | string | |
| agent.mcp_servers | array<object> | |
| agent.model | object | Model identifier and configuration. |
| agent.multiagent | null | object | Resolved coordinator topology with full agent definitions for each roster member. |
| agent.name | string | |
| agent.skills | array<object> | |
| agent.system | null | string | |
| agent.tools | array<object> | |
| agent.type | string | |
| agent.version | number | |
| archived_at | null | string | A timestamp in RFC 3339 format |
| budget | null | object | A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`. |
| budget.max_list_cost | object | A monetary amount in a specific currency. |
| budget.type | string | |
| created_at | string | A timestamp in RFC 3339 format |
| environment_id | string | |
| metadata | object | |
| outcome_evaluations | array<object> | Per-outcome evaluation state. One entry per `define_outcome` event sent to the session. |
| outcome_evaluations[].completed_at | null | string | A timestamp in RFC 3339 format |
| outcome_evaluations[].description | string | What the agent should produce. |
| outcome_evaluations[].explanation | null | string | Grader's verdict text from the most recent evaluation. For `satisfied`, explains why criteria are met; for `needs_revision` (intermediate), what's missing; for `failed`, why unrecoverable. |
| outcome_evaluations[].iteration | number | 0-indexed revision cycle the outcome is currently on. |
| outcome_evaluations[].outcome_id | string | Server-generated outc_ ID for this outcome. |
| outcome_evaluations[].result | string | Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal. |
| outcome_evaluations[].type | string | |
| resources | array<object> | |
| resources[].id | string | |
| resources[].created_at | string | A timestamp in RFC 3339 format |
| resources[].mount_path | string | null | string | Filesystem path where the store is mounted in the session container, e.g. /mnt/memory/user-preferences. Derived from the store's name. Output-only. |
| resources[].type | string | |
| resources[].updated_at | string | A timestamp in RFC 3339 format |
| resources[].url | string | |
| resources[].checkout | null | object | |
| resources[].file_id | string | |
| resources[].memory_store_id | string | The memory store ID (memstore_...). Must belong to the caller's organization and workspace. |
| resources[].access | null | string | Access mode for an attached memory store. |
| resources[].description | string | Description of the memory store, snapshotted at attach time. Rendered into the agent's system prompt. Empty string when the store has no description. |
| resources[].instructions | null | string | Per-attachment guidance for the agent on how to use this store. Rendered into the memory section of the system prompt. Max 4096 chars. |
| resources[].name | null | string | Display name of the memory store, snapshotted at attach time. Later edits to the store's name do not propagate to this resource. |
| stats | object | Timing statistics for a session. |
| stats.active_seconds | number | Cumulative time in seconds the session spent in `running` status. Excludes idle time. |
| stats.duration_seconds | number | Elapsed time since session creation in seconds. For terminated sessions, frozen at the final update. |
| status | string | SessionStatus enum - `rescheduling` - Transient error occurred, retrying automatically. - `running` - Agent is actively executing. - `idle` - Agent is waiting for input, including user messages or tool confirmations. Sessions start in idle. - `terminated` - Session has ended, either due to an error or completion. |
| title | null | string | |
| type | string | |
| updated_at | string | A timestamp in RFC 3339 format |
| usage | object | Cumulative token usage for a session across all turns. |
| usage.active_seconds | number | Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once, unlike `stats.active_seconds`, which sums each thread's own active time. This is the duration the session's runtime cost is priced on. |
| usage.cache_creation | object | Prompt-cache creation token usage broken down by cache lifetime. |
| usage.cache_read_input_tokens | number | Total tokens read from prompt cache. |
| usage.input_tokens | number | Total input tokens consumed across all turns. |
| usage.list_cost | null | object | A monetary amount in a specific currency. |
| usage.output_tokens | number | Total output tokens generated across all turns. |
| usage.server_tool_use | null | object | Cumulative count of server-executed tool invocations, broken down by tool. |
| vault_ids | array<string> | Vault IDs attached to the session at creation. Empty when no vaults were supplied. |
| deployment_id | null | string | Deployment ID when the session was created from a deployment reference. Null otherwise. |