開始一個會話

會話是在環境中執行的代理實例。每個會話參考一個代理和一個環境（兩者都是分別建立的），並在多次互動中維護對話歷史。

所有 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"