Transfer Task 도구

Transfer Task 도구 (Transfer Task Tool)

에이전트가 전문화된 서브 에이전트에게 작업을 위임하고 그 결과를 받는 방법을 설명해요. 멀티 에이전트 오케스트레이션의 핵심 메커니즘이에요.

출처: 문서

본문

transfer_task 도구는 에이전트가 전문화된 서브 에이전트에게 작업을 위임하고 그 결과를 받게 해 줘요. 멀티 에이전트 오케스트레이션의 핵심 메커니즘이에요.

수동으로 추가할 필요 없어요 — 에이전트에 sub_agents가 설정되면 자동으로 사용 가능해요.

구성

sub_agents가 설정되면 도구가 암시적으로 활성화돼요:

agents:
  coordinator:
    model: openai/gpt-4o
    description: Coordinates work across specialists
    instruction: Analyze requests and delegate to the right specialist.
    sub_agents: [developer, researcher]

  developer:
    model: anthropic/claude-sonnet-4-5
    description: Expert software developer
    instruction: Write clean, production-ready code.
    toolsets:
      - type: filesystem
      - type: shell

  researcher:
    model: openai/gpt-4o
    description: Web researcher
    instruction: Search for information online.
    toolsets:
      - type: mcp
        ref: docker:duckduckgo

코디네이터 에이전트는 자동으로 developer 또는 researcher에게 위임할 수 있는 transfer_task 도구를 얻어요.

도구 인터페이스

transfer_task 도구는 세 파라미터를 받아요:

파라미터 타입 필수 설명
agent string ✓ 위임할 서브 에이전트 이름. 호출자의 sub_agents 아래에 나열되어야 함
task string ✓ 서브 에이전트가 달성해야 할 작업의 명확하고 간결한 설명
expected_output string ✓ 호출자가 기대하는 결과/형식 설명

호출은 서브 에이전트가 결과를 반환할 때까지 블록하고, 그 결과가 도구의 응답이 돼요. 비차단 병렬 위임에는 background_agents를 대신 사용하세요.

위임 한계

서브 에이전트는 자신의 sub_agents를 가질 수 있어서 다단계 위임 체인을 지원해요. 두 개의 런타임 가드가 체인을 제정신으로 유지하며, transfer_task와 run_background_agent 모두에 적용돼요:

  • 순환은 거부돼요. 활성 위임 체인에 이미 있는 에이전트를 겨냥한 위임(예: a → b → a)은 순환을 이름 붙인 오류로 실패해요.
  • 깊이는 중첩 위임 10개로 제한돼요. 루트 에이전트가 첫 서브 에이전트에게 위임하는 것이 깊이 1로 계산되고, 상한을 넘는 호출은 시도된 깊이를 명시한 오류로 실패해요.

거부된 위임은 호출 에이전트에 도구 오류를 반환하고 서브 에이전트를 절대 시작하지 않아요.

팁 더 보기 병렬 작업 위임은 Background Agents 문서를, 멀티 에이전트 패턴은 Multi-Agent 문서를 참고하세요.

더 알아보기 (Learn more)