启动会话

会话是环境中运行的代理实例。每个会话引用一个代理和一个环境（两者都是单独创建的），并在多次交互中维护对话历史。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 标头。SDK 会自动设置 beta 标头。

创建会话

会话需要一个 agent ID 和一个 environment ID。代理是版本化资源；将 agent ID 作为字符串传入会使用最新的代理版本启动会话。

session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
SESSION_ID=$(jq -r '.id' <<< "$session")

要将会话固定到特定的代理版本，请传入一个对象。这样您可以精确控制运行哪个版本，并独立地分阶段推出新版本。

代理定义了 Claude 在会话中的行为方式，包括模型、系统提示、工具和 MCP 服务器。有关详细信息，请参阅代理设置。

通过保险库进行 MCP 身份验证

如果您的代理使用需要身份验证的 MCP 工具，请在会话创建时传入 vault_ids 以引用包含存储的 OAuth 凭据的保险库。Anthropic 代表您管理令牌刷新。有关如何创建保险库和注册凭据的信息，请参阅使用保险库进行身份验证。

创建会话会配置环境和代理，但不会启动任何工作。要委派任务，请使用用户事件向会话发送事件。会话充当状态机，跟踪进度，而事件驱动实际执行。

有关如何流式传输代理的响应和处理工具确认的信息，请参阅事件和流式传输。

会话状态

会话通过这些状态进行：

状态	描述
`idle`	代理正在等待输入，包括用户消息或工具确认。会话以 `idle` 开始。
`running`	代理正在主动执行
`rescheduling`	发生了临时错误，正在自动重试
`terminated`	会话因不可恢复的错误而结束

其他会话操作

检索会话

列出会话

归档会话

归档会话以防止发送新事件，同时保留其历史记录：

删除会话

删除会话以永久移除其记录、事件和关联的容器。running 会话无法删除；如果需要立即删除，请发送中断事件。

文件、内存存储、环境和代理是独立资源，不受会话删除的影响。

pinned_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": {"type": "agent", "id": "$AGENT_ID", "version": 1},
  "environment_id": "$ENVIRONMENT_ID"
}
EOF
)
PINNED_SESSION_ID=$(jq -r '.id' <<< "$pinned_session")

vault_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "vault_ids": ["$VAULT_ID"]
}
EOF
)
VAULT_SESSION_ID=$(jq -r '.id' <<< "$vault_session")

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "events": [
    {
      "type": "user.message",
      "content": [{"type": "text", "text": "List the files in the working directory."}]
    }
  ]
}
EOF

retrieved=$(curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")
echo "Status: $(jq -r '.status' <<< "$retrieved")"

curl -fsSL https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "\(.id): \(.status)"'

curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"