Handoff 도구

Handoff 도구 (Handoff Tool)

에이전트가 현재 대화의 제어권을 같은 구성 파일의 다른 에이전트에게 넘기는 방법을 설명해요.

출처: 문서

본문

handoff 도구는 에이전트가 현재 대화의 제어권을 같은 구성 파일에 있는 다른 에이전트에게 넘기게 해 줘요. 하위 작업을 위임하고 결과를 수집하는 transfer_task와 달리, handoff는 수신 에이전트가 사용자와 직접 대화를 계속하도록 세션을 다시 연결해요.

이것이 handoffs 라우팅의 핵심 메커니즘이에요 — 라우터 에이전트가 사용자 요청을 분류하고 전문가에게 넘겨서, 그 전문가가 나머지 세션을 소유하는 패턴이죠.

참고 로컬 전용 handoff 도구는 같은 구성 파일에서 로컬 이름으로 선언된 에이전트만 겨냥해요. 네트워크 연결을 열지 않아요. 네트워크상의 원격 에이전트에 위임하려면 A2A 도구셋을 사용하세요.

구성

에이전트가 비어 있지 않은 handoffs: 목록을 선언하면 도구가 암시적으로 활성화돼요. toolsets: 아래에 - type: handoff를 추가하지 마세요 — 그것은 도구셋 유형이 아니에요.

agents:
  router:
    model: openai/gpt-4o
    description: Routes questions to the right specialist
    instruction: |
      Classify the user's question and hand off to the most appropriate
      specialist. If unsure, ask a clarifying question first.
    handoffs: [billing, support]

  billing:
    model: openai/gpt-4o
    description: Billing specialist
    instruction: Answer billing questions.

  support:
    model: openai/gpt-4o
    description: Technical support specialist
    instruction: Help with technical issues.

라우터 에이전트는 자동으로 대화를 billing 또는 support로 전환할 수 있는 handoff 도구를 얻어요.

도구 인터페이스

handoff 도구는 파라미터 하나를 받아요:

파라미터 타입 필수 설명
agent string ✓ 대화를 넘길 에이전트의 로컬 이름. 현재 에이전트의 handoffs: 필드에 나열된 이름만 유효한 대상

팁 더 보기 하위 작업 위임(호출자가 제어권을 유지하고 결과를 기다림)은 Transfer Task 문서를, 네트워크상의 원격 에이전트 연결은 A2A 도구셋을, 더 넓은 패턴은 Handoffs Routing 문서를 참고하세요.

더 알아보기 (Learn more)