세션 시작

세션은 환경 내에서 실행 중인 에이전트 인스턴스입니다. 각 세션은 에이전트와 환경(각각 별도로 생성됨)을 참조하며, 여러 상호작용에 걸쳐 대화 기록을 유지합니다.

모든 Managed Agents API 요청에는 managed-agents-2026-04-01 베타 헤더가 필요합니다. SDK는 베타 헤더를 자동으로 설정합니다.

세션 생성

세션에는 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")

세션을 특정 에이전트 버전에 고정하려면 객체를 전달하세요. 이를 통해 실행할 버전을 정확히 제어하고 새 버전의 단계적 출시를 독립적으로 관리할 수 있습니다.

에이전트는 모델, 시스템 프롬프트, 도구, MCP 서버를 포함하여 세션 내에서 Claude가 동작하는 방식을 정의합니다. 자세한 내용은 에이전트 설정을 참조하세요.

볼트를 통한 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"