Managed Agents에이전트에 작업 위임

세션 시작하기

에이전트를 실행하고 작업 수행을 시작하기 위한 세션을 생성합니다.

세션은 환경 내의 에이전트 인스턴스입니다. 각 세션은 별도로 생성된 에이전트와 환경을 참조하며, 여러 상호작용에 걸쳐 대화 기록을 유지합니다. 세션은 두 단계의 수명 주기를 따릅니다. 먼저 세션을 생성하여 샌드박스를 프로비저닝한 다음, 사용자 이벤트를 전송하여 작업을 시작합니다.

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

세션 생성하기

세션에는 agent ID와 environment ID가 필요합니다. 에이전트는 버전이 관리되는 리소스이며, agent ID를 문자열로 전달하면 최신 에이전트 버전으로 세션이 시작됩니다.

ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID"

세션을 특정 에이전트 버전에 고정하려면 객체를 전달하세요. 이를 통해 정확히 어떤 버전이 실행되는지 제어하고 새 버전의 롤아웃을 독립적으로 단계별로 진행할 수 있습니다.

ant beta:sessions create <<YAML
agent:
  type: agent
  id: $AGENT_ID
  version: 1
environment_id: $ENVIRONMENT_ID
YAML

세션에 대한 에이전트 구성 재정의하기

agent는 세 가지 형식으로 전달할 수 있습니다. 에이전트 ID 문자열, 고정 버전 객체(type: "agent"), 또는 재정의 객체입니다. 재정의 형식은 단일 세션에 대해 에이전트 구성의 일부를 변경합니다. 에이전트의 버전을 변경하지 않고 한 세션에서 다른 모델을 시도하거나 추가 도구를 부여하려는 경우 이 형식을 사용하세요. 재정의 형식의 경우 type을 agent_with_overrides로 설정하고 에이전트의 id와 선택적으로 version을 전달하세요(version을 생략하면 에이전트의 최신 버전이 사용됩니다). 그런 다음 세션에서 사용해야 하는 값과 함께 model, system, tools, mcp_servers, skills 중 원하는 항목을 포함하세요.

재정의 가능한 각 필드는 동일한 세 가지 규칙을 따릅니다.

필드를 생략하는 경우: 세션은 참조하는 에이전트 버전에서 값을 상속합니다.
필드를 null로 설정하거나, 목록 필드의 경우 빈 배열로 설정하는 경우: 세션은 해당 필드가 지워진 상태로 실행됩니다. 이 규칙은 system, mcp_servers, skills에 완전히 적용됩니다. 두 가지 예외가 있습니다.
- model은 절대 지울 수 없습니다. 세션에는 항상 모델이 필요하므로 model: null은 400 agent_model_required 오류를 반환합니다.
- 세션의 유효한 skills가 비어 있지 않은 경우 tools를 지우면 400 오류가 반환됩니다. 스킬에는 read 도구가 필요하기 때문입니다. 그 외의 경우 tools: null과 tools: []는 필드를 지웁니다.
필드에 값을 설정하는 경우: 해당 값이 에이전트의 값을 완전히 대체합니다. 재정의는 에이전트의 구성과 병합되지 않으므로, tools 재정의는 세션이 가져야 하는 모든 도구를 나열해야 합니다.

재정의는 생성하는 세션에만 적용됩니다. 에이전트 리소스를 수정하거나 새 에이전트 버전을 생성하지 않으므로, 동일한 에이전트를 참조하는 다른 세션은 영향을 받지 않습니다.

응답에서 agent 객체는 재정의가 적용된 후 세션이 실행되는 구성을 반영합니다. 해당 객체의 id와 version은 여전히 재정의가 적용된 에이전트와 버전을 식별합니다. 이를 통해 세션을 기본 에이전트로 추적할 수 있습니다.

# 응답의 `agent`는 해석된 스냅샷입니다: 각 오버라이드는 이 세션에 대해서만
# 해당 필드를 대체하며, agent 리소스는 id와 버전을 유지합니다.
ant beta:sessions create \
  --transform 'agent.{id,version,model,system}' \
  --format json <<YAML
agent:
  type: agent_with_overrides
  id: $AGENT_ID
  model:
    id: claude-sonnet-5
  system: null
environment_id: $ENVIRONMENT_ID
YAML

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

Vault를 통한 MCP 인증

에이전트가 인증이 필요한 MCP 도구를 사용하는 경우, 세션 생성 시 vault_ids를 전달하여 저장된 OAuth 자격 증명이 포함된 vault를 참조하세요. Anthropic이 사용자를 대신하여 토큰 갱신을 관리합니다. Vault를 생성하고 자격 증명을 등록하는 방법은 Vault로 인증하기를 참조하세요.

ant beta:sessions create <<YAML
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
vault_ids:
  - $VAULT_ID
YAML