다중 에이전트 세션

다중 에이전트 오케스트레이션을 통해 하나의 에이전트가 다른 에이전트들과 조정하여 복잡한 작업을 완료할 수 있습니다. 에이전트들은 자신의 격리된 컨텍스트로 병렬로 작동할 수 있으며, 이는 출력 품질을 개선하고 완료 시간을 단축하는 데 도움이 됩니다.

작동 방식

모든 에이전트는 동일한 컨테이너와 파일 시스템을 공유하지만, 각 에이전트는 자신의 세션 스레드에서 실행됩니다. 스레드는 자신의 대화 기록을 가진 컨텍스트 격리 이벤트 스트림입니다. 코디네이터는 기본 스레드(세션 수준 이벤트 스트림과 동일)에서 활동을 보고합니다. 추가 스레드는 코디네이터가 위임을 결정할 때 런타임에 생성됩니다.

스레드는 지속적입니다. 코디네이터는 이전에 호출한 에이전트에게 후속 메시지를 보낼 수 있으며, 그 에이전트는 이전 턴의 모든 것을 유지합니다.

각 에이전트는 해당 에이전트가 생성될 때 정의된 자신의 구성(모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬)을 사용합니다. 도구와 컨텍스트는 공유되지 않습니다.

위임할 항목

다중 에이전트 세션은 전체 목표 내에 여러 개의 잘 정의된, 특화된 작업이 있을 때 가장 잘 작동합니다:

• 코드 리뷰: 초점이 맞춰진 시스템 프롬프트와 읽기 전용 도구를 가진 리뷰어 에이전트.
• 테스트 생성: 프로덕션 코드를 건드리지 않고 테스트를 작성하고 실행하는 테스트 에이전트.
• 연구: 웹 도구를 가진 검색 에이전트로 코디네이터에게 발견 사항을 요약합니다.

호출 가능한 에이전트 선언

에이전트를 정의할 때, 호출할 수 있는 다른 에이전트의 ID를 나열합니다:

callable_agents의 각 항목은 기존 에이전트의 ID여야 합니다. 위임의 한 수준만 지원됩니다. 코디네이터는 다른 에이전트를 호출할 수 있지만, 그 에이전트들은 자신의 에이전트를 호출할 수 없습니다.

그런 다음 오케스트레이터를 참조하는 세션을 생성합니다:

호출 가능한 에이전트는 오케스트레이터의 구성에서 해결됩니다. 세션 생성 시 이들을 참조할 필요가 없습니다.

세션 스레드

세션 수준 이벤트 스트림(/v1/sessions/:id/stream)은 기본 스레드로 간주되며, 모든 스레드 전체의 모든 활동에 대한 축약된 보기를 포함합니다. 호출된 에이전트의 개별 추적을 볼 수는 없지만, 그들의 작업의 시작과 끝을 볼 수 있습니다. 세션 스레드는 특정 에이전트의 추론과 도구 호출을 자세히 살펴볼 수 있는 곳입니다.

세션 상태도 모든 에이전트 활동의 집계입니다. 최소한 하나의 스레드가 running이면, 전체 세션 상태도 running이 됩니다.

세션의 모든 스레드를 다음과 같이 나열합니다:

특정 스레드에서 이벤트를 스트리밍합니다:

스레드의 과거 이벤트를 나열합니다:

다중 에이전트 이벤트 유형

이러한 이벤트는 최상위 세션 스트림에서 다중 에이전트 활동을 표시합니다.

스레드의 도구 권한 및 사용자 정의 도구

callable_agent 스레드가 클라이언트에서 뭔가가 필요할 때(always_ask 도구를 실행할 권한 또는 사용자 정의 도구의 결과), 요청은 session_thread_id 필드와 함께 세션 스트림에 표시됩니다. 응답을 게시할 때 동일한 session_thread_id를 포함하여 플랫폼이 대기 중인 스레드로 라우팅하도록 합니다.

• session_thread_id가 있음: 이벤트는 서브에이전트 스레드에서 발생했습니다. 회신에서 이를 반복합니다.
• session_thread_id가 없음: 이벤트는 기본 스레드에서 왔습니다. 필드 없이 회신합니다.
• tool_use_id로 요청과 응답을 일치시킵니다.

아래 예제는 도구 확인 핸들러를 확장하여 회신을 라우팅합니다. 동일한 패턴이 user.custom_tool_result에 적용됩니다.

ant beta:agents create <<YAML
name: Engineering Lead
model: claude-opus-4-7
system: You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.
tools:
  - type: agent_toolset_20260401
callable_agents:
  - type: agent
    id: $REVIEWER_AGENT_ID
    version: $REVIEWER_AGENT_VERSION
  - type: agent
    id: $TEST_WRITER_AGENT_ID
    version: $TEST_WRITER_AGENT_VERSION
YAML

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

for thread in client.beta.sessions.threads.list(session.id):
    print(f"[{thread.agent_name}] {thread.status}")

with client.beta.sessions.threads.stream(
    thread.id,
    session_id=session.id,
) as stream:
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.thread_idle":
                break

for event in client.beta.sessions.threads.events.list(
    thread.id,
    session_id=session.id,
):
    print(f"[{event.type}] {event.processed_at}")

for event_id in stop.event_ids:
    pending = events_by_id[event_id]
    confirmation = {
        "type": "user.tool_confirmation",
        "tool_use_id": event_id,
        "result": "allow",
    }
    # Echo session_thread_id when the request came from a subagent thread
    if pending.session_thread_id is not None:
        confirmation["session_thread_id"] = pending.session_thread_id
    client.beta.sessions.events.send(session.id, events=[confirmation])