Managed Agents고급 오케스트레이션

멀티 에이전트 세션

단일 세션 내에서 여러 에이전트를 조정합니다.

멀티 에이전트 오케스트레이션을 사용하면 하나의 에이전트가 다른 에이전트들과 협력하여 복잡한 작업을 완료할 수 있습니다. 에이전트는 각자 격리된 컨텍스트를 가지고 병렬로 작동할 수 있으며, 이는 출력 품질을 향상시키고 완료 시간을 단축하는 데 도움이 됩니다.

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

작동 방식

모든 에이전트는 동일한 샌드박스, 파일 시스템 및 볼트 자격 증명을 공유하지만, 각 에이전트는 자체 대화 기록을 가진 컨텍스트 격리 이벤트 스트림인 세션 스레드에서 실행됩니다. 코디네이터는 기본 스레드(세션 수준 이벤트 스트림과 동일)에서 활동을 보고하며, 코디네이터가 작업을 위임할 때 런타임에 추가 스레드가 생성됩니다.

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

각 에이전트는 모델, 시스템 프롬프트, 도구, MCP 서버 및 스킬 등 자체 구성을 사용합니다. 세션 수준 에이전트 구성 재정의는 예외이며, 코디네이터와 그 self 복사본에 적용됩니다. 도구, MCP 서버 및 컨텍스트는 공유되지 않습니다.

위임할 작업

멀티 에이전트 조정은 다양한 영역에 걸친 작업이 필요하거나, 여러 개의 명확하게 범위가 지정된 작업이 전체 목표에 기여하는 복잡한 작업에 가장 적합합니다.

잘 작동하는 패턴:

병렬화: 독립적인 하위 작업(여러 소스 검색, 개별 파일 분석)을 동시에 분산 처리하고 코디네이터가 결과를 종합하도록 합니다.
전문화: 단일 에이전트에 모든 기능을 로드하는 대신, 보안 에이전트나 문서화 에이전트와 같이 도메인에 특화된 시스템 프롬프트와 도구를 가진 에이전트로 라우팅합니다.
에스컬레이션: 복잡한 하위 작업의 일부에 대해 더 유능한 에이전트나 모델에 자문을 구합니다.

코디네이터 구성

에이전트를 정의할 때 multiagent를 설정하여 코디네이터가 위임할 수 있는 에이전트 목록을 선언하세요:

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

multiagent.agents는 다음 중 하나를 허용할 수 있습니다:

{"type": "agent", "id": agent.id}는 이전에 생성된 agent를 ID로 참조합니다. version이 지정되지 않은 경우, 참조는 코디네이터가 생성된 시점의 해당 에이전트 최신 버전으로 고정됩니다.
{"type": "agent", "id": agent.id, "version": agent.version}은 특정 에이전트 버전을 고정합니다.
{"type": "self"}는 코디네이터가 자신의 복사본을 생성할 수 있도록 허용합니다. 세션이 에이전트 구성 재정의와 함께 생성된 경우, 해당 재정의는 이러한 복사본에도 적용됩니다. ID로 참조된 목록 항목은 영향을 받지 않습니다.

multiagent.agents 목록을 포함한 코디네이터의 구성은 코디네이터가 생성되거나 업데이트될 때 스냅샷으로 저장됩니다. 참조된 에이전트는 해당 시점에 확인된 버전으로 고정되며, 이후 정의가 업데이트되어도 자동으로 반영되지 않습니다. 참조된 에이전트의 최신 버전에 위임하려면 코디네이터를 업데이트하여 목록이 해당 버전을 참조하도록 하세요.

코디네이터는 한 단계의 에이전트에만 위임할 수 있으며, 깊이 > 1은 무시됩니다. multiagent.agents에는 최대 20개의 고유 에이전트를 나열할 수 있지만, 코디네이터는 각 에이전트의 여러 복사본을 호출할 수 있습니다.

세션 생성

코디네이터를 참조하는 세션을 생성하세요. 코디네이터는 필요에 따라 목록에 있는 에이전트에게 위임합니다.

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

에이전트를 MCP 서버에 연결

MCP 서버는 에이전트 범위입니다(각 에이전트 정의가 자체 서버와 도구를 선언함). 반면 볼트 자격 증명은 세션 범위입니다(세션 생성 시 전달된 vault_ids가 모든 스레드에 적용됨). 통합 시 다음 두 가지 사항을 고려해야 합니다:

MCP 서버를 인증하려면 모든 에이전트에서 사용되는 모든 MCP 서버에 대한 볼트 자격 증명을 포함하세요.
에이전트의 접근을 제한하려면 해당 에이전트 정의에 필요한 서버만 선언하세요.

세션 생성 시 에이전트 구성 재정의를 사용하면 코디네이터와 그 self 복사본의 MCP 서버를 교체할 수 있습니다.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

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

이 예제에서는 리서처만 GitHub MCP 서버를 선언하므로 코디네이터는 접근 권한이 없습니다. 세션의 vault_ids가 리서처의 스레드에 GitHub 자격 증명을 제공합니다.

서버를 선언한 후에도 에이전트의 MCP 호출이 인증에 실패하는 경우, 자격 증명의 mcp_server_url이 스킴과 후행 슬래시를 포함하여 에이전트의 mcp_servers[].url과 정확히 일치하는지 확인하세요.

스레드

세션 수준 이벤트 스트림(/v1/sessions/:id/events/stream)은 기본 스레드로 간주되며, 모든 스레드의 모든 활동에 대한 요약된 뷰를 포함합니다. 서브에이전트의 전체 활동은 볼 수 없지만, 작업의 시작과 종료, 그리고 도구 권한 요청과 같은 차단 이벤트는 볼 수 있습니다.

세션 스레드는 특정 에이전트의 활동을 자세히 살펴보는 곳입니다.

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

최대 25개의 동시 스레드가 지원됩니다. 코디네이터는 목록에 있는 단일 에이전트의 여러 복사본을 호출하여 하나의 agent와 연결된 여러 스레드를 생성할 수 있습니다.

기본 스레드 이벤트

이러한 이벤트는 /v1/sessions/:id/events/stream의 기본 스레드에서 멀티 에이전트 활동을 표시합니다.

유형	설명
`session.thread_created`	스레드가 생성되었습니다. `session_thread_id`와 `agent_name`을 포함합니다.
`session.thread_status_running`	스레드가 활동을 시작했습니다.
`session.thread_status_idle`	스레드와 연결된 에이전트가 입력을 기다리고 있습니다. 에이전트가 중지된 이유를 나타내는 `stop_reason`을 포함합니다.
`session.thread_status_terminated`	스레드가 보관되었거나 종료 오류가 발생했습니다.
`agent.thread_message_received`	에이전트가 코디네이터에게 결과를 전달했습니다. `from_session_thread_id`, `from_agent_name` 및 `content`를 포함합니다.
`agent.thread_message_sent`	코디네이터가 다른 에이전트에게 후속 메시지를 보냈습니다. `to_session_thread_id`, `to_agent_name` 및 `content`를 포함합니다.

세션 스레드 이벤트

중요한 이벤트는 기본 스레드로 프록시됩니다. 그러나 특정 에이전트의 추론 및 도구 호출을 조사하고 싶을 수 있습니다. 이를 위해 연결된 세션 스레드에서 이벤트를 스트리밍하거나 나열하세요.

도구 권한 및 커스텀 도구

서브에이전트가 always_ask 도구를 실행하기 위한 권한이나 커스텀 도구의 결과와 같이 클라이언트로부터 무언가가 필요한 경우, 해당 이벤트는 발생한 세션 스레드를 식별하는 session_thread_id와 함께 기본 스레드에 교차 게시됩니다.

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

user.tool_confirmation(tool_use_id 포함) 또는 user.custom_tool_result(custom_tool_use_id 포함)를 게시하세요. 서버가 응답을 올바른 스레드로 자동 라우팅합니다.

다음 예제는 응답을 라우팅하도록 도구 확인 핸들러를 확장합니다. 동일한 패턴이 user.custom_tool_result에도 적용됩니다.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )

Was this page helpful?

Managed Agents고급 오케스트레이션

멀티 에이전트 세션

단일 세션 내에서 여러 에이전트를 조정합니다.

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

작동 방식

위임할 작업

잘 작동하는 패턴:

병렬화: 독립적인 하위 작업(여러 소스 검색, 개별 파일 분석)을 동시에 분산 처리하고 코디네이터가 결과를 종합하도록 합니다.
전문화: 단일 에이전트에 모든 기능을 로드하는 대신, 보안 에이전트나 문서화 에이전트와 같이 도메인에 특화된 시스템 프롬프트와 도구를 가진 에이전트로 라우팅합니다.
에스컬레이션: 복잡한 하위 작업의 일부에 대해 더 유능한 에이전트나 모델에 자문을 구합니다.

코디네이터 구성

에이전트를 정의할 때 multiagent를 설정하여 코디네이터가 위임할 수 있는 에이전트 목록을 선언하세요:

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

multiagent.agents는 다음 중 하나를 허용할 수 있습니다:

{"type": "agent", "id": agent.id}는 이전에 생성된 agent를 ID로 참조합니다. version이 지정되지 않은 경우, 참조는 코디네이터가 생성된 시점의 해당 에이전트 최신 버전으로 고정됩니다.
{"type": "agent", "id": agent.id, "version": agent.version}은 특정 에이전트 버전을 고정합니다.
{"type": "self"}는 코디네이터가 자신의 복사본을 생성할 수 있도록 허용합니다. 세션이 에이전트 구성 재정의와 함께 생성된 경우, 해당 재정의는 이러한 복사본에도 적용됩니다. ID로 참조된 목록 항목은 영향을 받지 않습니다.

세션 생성

코디네이터를 참조하는 세션을 생성하세요. 코디네이터는 필요에 따라 목록에 있는 에이전트에게 위임합니다.

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

에이전트를 MCP 서버에 연결

MCP 서버를 인증하려면 모든 에이전트에서 사용되는 모든 MCP 서버에 대한 볼트 자격 증명을 포함하세요.
에이전트의 접근을 제한하려면 해당 에이전트 정의에 필요한 서버만 선언하세요.

세션 생성 시 에이전트 구성 재정의를 사용하면 코디네이터와 그 self 복사본의 MCP 서버를 교체할 수 있습니다.

research_agent = client.beta.agents.create(
    name="researcher",
    model="claude-haiku-4-5",
    mcp_servers=[
        {"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"},
    ],
    tools=[{"type": "mcp_toolset", "mcp_server_name": "github"}],
)

coordinator = client.beta.agents.create(
    name="coordinator",
    model="claude-opus-4-8",
    tools=[{"type": "agent_toolset_20260401"}],
    multiagent={
        "type": "coordinator",
        "agents": [{"type": "agent", "id": research_agent.id}],
    },
)

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

스레드

세션 스레드는 특정 에이전트의 활동을 자세히 살펴보는 곳입니다.

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

기본 스레드 이벤트

이러한 이벤트는 /v1/sessions/:id/events/stream의 기본 스레드에서 멀티 에이전트 활동을 표시합니다.

유형	설명
`session.thread_created`	스레드가 생성되었습니다. `session_thread_id`와 `agent_name`을 포함합니다.
`session.thread_status_running`	스레드가 활동을 시작했습니다.
`session.thread_status_idle`	스레드와 연결된 에이전트가 입력을 기다리고 있습니다. 에이전트가 중지된 이유를 나타내는 `stop_reason`을 포함합니다.
`session.thread_status_terminated`	스레드가 보관되었거나 종료 오류가 발생했습니다.
`agent.thread_message_received`	에이전트가 코디네이터에게 결과를 전달했습니다. `from_session_thread_id`, `from_agent_name` 및 `content`를 포함합니다.
`agent.thread_message_sent`	코디네이터가 다른 에이전트에게 후속 메시지를 보냈습니다. `to_session_thread_id`, `to_agent_name` 및 `content`를 포함합니다.

세션 스레드 이벤트

도구 권한 및 커스텀 도구

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["toolu_01XYZ..."]
  }
}

user.tool_confirmation(tool_use_id 포함) 또는 user.custom_tool_result(custom_tool_use_id 포함)를 게시하세요. 서버가 응답을 올바른 스레드로 자동 라우팅합니다.

다음 예제는 응답을 라우팅하도록 도구 확인 핸들러를 확장합니다. 동일한 패턴이 user.custom_tool_result에도 적용됩니다.

for event_id in stop.event_ids:
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.tool_confirmation",
                "tool_use_id": event_id,
                "result": "allow",
            }
        ],
    )

Was this page helpful?

작동 방식

위임할 작업

코디네이터 구성

세션 생성

에이전트를 MCP 서버에 연결

스레드

기본 스레드 이벤트

세션 스레드 이벤트

도구 권한 및 커스텀 도구

작동 방식

위임할 작업

코디네이터 구성

세션 생성

에이전트를 MCP 서버에 연결

스레드

기본 스레드 이벤트

세션 스레드 이벤트

도구 권한 및 커스텀 도구

작동 방식

위임할 작업

코디네이터 구성

세션 생성

에이전트를 MCP 서버에 연결

스레드

기본 스레드 이벤트

세션 스레드 이벤트

도구 권한 및 커스텀 도구

작동 방식

위임할 작업

코디네이터 구성

세션 생성

에이전트를 MCP 서버에 연결

스레드

기본 스레드 이벤트

세션 스레드 이벤트

도구 권한 및 커스텀 도구