세션 시작

빌드에이전트에 작업 위임

세션 시작

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

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

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

세션 생성

세션에는 agent ID와 environment ID가 필요합니다. 에이전트는 버전이 지정된 리소스입니다. agent ID를 문자열로 전달하면 최신 에이전트 버전으로 세션을 시작합니다.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

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

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

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

볼트를 통한 MCP 인증

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

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

세션 시작

세션을 생성하면 환경과 에이전트가 프로비저닝되지만 작업은 시작되지 않습니다. 작업을 위임하려면 사용자 이벤트를 사용하여 세션에 이벤트를 보냅니다. 세션은 진행 상황을 추적하는 상태 머신으로 작동하며 이벤트가 실제 실행을 주도합니다.

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

에이전트의 응답을 스트리밍하고 도구 확인을 처리하는 방법은 이벤트 및 스트리밍을 참조하세요.

세션 상태

세션은 다음 상태를 거쳐 진행됩니다:

상태	설명
`idle`	에이전트가 사용자 메시지 또는 도구 확인을 포함한 입력을 기다리고 있습니다. 세션은 `idle` 상태로 시작합니다.
`running`	에이전트가 적극적으로 실행 중입니다.
`rescheduling`	일시적 오류가 발생했으며 자동으로 재시도 중입니다.
`terminated`	복구 불가능한 오류로 인해 세션이 종료되었습니다.

기타 세션 작업

세션 검색

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

세션 나열

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

세션 보관

세션을 보관하여 새 이벤트가 전송되는 것을 방지하면서 기록을 보존합니다:

client.beta.sessions.archive(session.id)

세션 삭제

세션을 삭제하여 기록, 이벤트 및 관련 컨테이너를 영구적으로 제거합니다. running 상태의 세션은 삭제할 수 없습니다. 즉시 삭제해야 하는 경우 인터럽트 이벤트를 보내세요.

파일, 메모리 저장소, 환경 및 에이전트는 독립적인 리소스이며 세션 삭제의 영향을 받지 않습니다.

client.beta.sessions.delete(session.id)

Was this page helpful?

빌드에이전트에 작업 위임

세션 시작

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

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

세션 생성

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

pinned_session = client.beta.sessions.create(
    agent={"type": "agent", "id": agent.id, "version": 1},
    environment_id=environment.id,
)

볼트를 통한 MCP 인증

vault_session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    vault_ids=[vault.id],
)

세션 시작

client.beta.sessions.events.send(
    session.id,
    events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)

에이전트의 응답을 스트리밍하고 도구 확인을 처리하는 방법은 이벤트 및 스트리밍을 참조하세요.

세션 상태

세션은 다음 상태를 거쳐 진행됩니다:

상태	설명
`idle`	에이전트가 사용자 메시지 또는 도구 확인을 포함한 입력을 기다리고 있습니다. 세션은 `idle` 상태로 시작합니다.
`running`	에이전트가 적극적으로 실행 중입니다.
`rescheduling`	일시적 오류가 발생했으며 자동으로 재시도 중입니다.
`terminated`	복구 불가능한 오류로 인해 세션이 종료되었습니다.

기타 세션 작업

세션 검색

retrieved = client.beta.sessions.retrieve(session.id)
print(f"Status: {retrieved.status}")

세션 나열

for session in client.beta.sessions.list():
    print(f"{session.id}: {session.status}")

세션 보관

세션을 보관하여 새 이벤트가 전송되는 것을 방지하면서 기록을 보존합니다:

client.beta.sessions.archive(session.id)

세션 삭제

파일, 메모리 저장소, 환경 및 에이전트는 독립적인 리소스이며 세션 삭제의 영향을 받지 않습니다.

client.beta.sessions.delete(session.id)

Was this page helpful?