콘텐츠로 건너뛰기
파운더 가격 — 얼리 고객에게 고정시작하기 →

에이전트 핸드오프 패턴: AI 에이전트 간 작업 라우팅

에이전트 핸드오프 패턴은 하나의 AI 에이전트가 작업, 축적된 컨텍스트, 실행 권한을 다른 에이전트로 전송하는 프로토콜입니다. 어떤 데이터가 경계를 넘는지, 무엇이 폐기되는지, 자격 증명이 작업과 함께 이동하는지를 결정합니다. 대부분의 핸드오프 실패는 라우팅 실패가 아니라 다운스트림 에이전트가 조용히 실패하거나 손상된 에이전트가 민감한 페이로드 데이터를 유출할 때만 표면화되는 컨텍스트 손실 또는 자격 증명 유출 실패입니다.

에이전트 핸드오프 패턴은 자율 AI 에이전트가 피어 또는 전문가 에이전트에게 작업을 위임하는 방법을 규정하는 소프트웨어 설계 패턴으로, 컨텍스트 전송을 위한 데이터 계약, 작업 전달을 위한 라우팅 메커니즘, 에이전트 간 자격 증명 또는 컨텍스트 유출을 방지하는 격리 보증을 지정합니다.

4가지 표준 핸드오프 패턴

푸시 핸드오프: 호출자가 피호출자를 직접 깨운다

푸시 핸드오프에서 호출 에이전트는 작업 컨텍스트를 포함하는 페이로드를 구성하고 수신 에이전트에 직접 알립니다. 일반적으로 함수 호출, 메시지 전송 또는 피호출자를 깨우는 API 호출을 통해 이루어집니다. 호출자는 피호출자가 받는 데이터, 받는 시기, 작업을 처리하는 에이전트를 정확히 제어합니다.

푸시 핸드오프는 OpenAI Agents SDK의 handoff() 프리미티브(GitHub 스타 27,133, MIT)가 사용하는 패턴입니다. 호출자는 선택적으로 전송 전에 컨텍스트 필드를 제거하거나 변환하는 input_filter 함수를 전달할 수 있습니다. input_filter 없이는 축적된 민감한 콘텐츠를 포함하여 전체 컨텍스트 창이 피호출자에게 전달됩니다.

강점: 낮은 지연 시간, 작업 라우팅에 대한 직접 제어, 관찰 가능성 도구에서 추적이 용이.
위험: 호출자가 자격 증명과 민감한 컨텍스트를 명시적으로 제거해야 함; 전문가 에이전트 추가 또는 제거 시 라우팅 로직 변경이 필요한 호출자-피호출자 간 긴밀한 결합.

풀 디스패치: 피호출자가 공유 큐에서 가져온다

풀 디스패치에서 호출 에이전트는 특정 에이전트에 직접 알리지 않고 공유 큐 또는 받은 편지함에 작업을 씁니다. 피호출 에이전트는 큐를 모니터링하고 자신의 역량에 맞는 작업을 요청합니다. 이를 통해 워커 풀 전체에서 부하 분산이 가능하고 호출자를 어떤 특정 에이전트가 작업을 처리할지에 대한 지식에서 분리합니다.

풀 디스패치는 자격 증명 노출을 줄입니다: 큐 메시지에는 작업 설명과 출력 키 포인터만 포함되며, 호출자의 전체 컨텍스트는 포함되지 않습니다.

강점: 수평 확장, 느슨한 결합, 동일한 워커 간 자연스러운 부하 분산.
위험: 부하 하에 큐 깊이가 무제한으로 증가할 수 있음; 작업 순서 보장은 큐 의미론에 따라 달라짐; 관찰 가능성에는 여러 큐 읽기에 걸친 작업 ID 상관이 필요.

블랙보드 라우팅: 포인터 기반 컨텍스트 격리

블랙보드 포인터 핸드오프에서 호출자는 공유 영구 저장소의 명명된 키(예: output/researcher/task_abc123)에 출력을 쓰고 피호출자에게 키 이름만 보냅니다. 피호출자는 키를 읽고 필요한 필드만 정확히 검색합니다. 원시 자격 증명, 중간 스크래치패드 콘텐츠, 호출자의 전체 컨텍스트는 핸드오프 메시지에 결코 나타나지 않습니다.

OpenLegion의 hand_off() 함수는 이 패턴을 기본으로 구현합니다: 블랙보드의 output/{agent_id}/{handoff_id}에 출력 데이터를 쓰고, 해당 키에 대한 포인터가 포함된 작업 항목을 수신자의 받은 편지함에 만들고, 수신자를 깨웁니다. Vault에 저장된 자격 증명은 메시에 의해 실행 시점에 주입됩니다.

강점: 최고의 자격 증명 격리, 피호출자는 필요한 것만 읽음, 키 버전 기록을 통한 완전한 감사 추적.
위험: 읽기 작업 추가; 적절한 접근 제어가 있는 신뢰할 수 있는 공유 저장소 필요.

스트리밍 핸드오프: 점진적 컨텍스트 전송

스트리밍 핸드오프에서 컨텍스트는 호출 에이전트가 생성함에 따라 완전한 출력을 기다리지 않고 토큰별 또는 청크별로 전송됩니다. 이는 실시간 파이프라인에서 엔드투엔드 지연 시간을 최소화합니다.

스트리밍 핸드오프는 자격 증명 노출 위험이 가장 높습니다: 스트림에는 호출자가 필터링하기 전에 추론 중간에 생성된 민감한 콘텐츠가 포함될 수 있습니다.

강점: 가장 낮은 엔드투엔드 지연 시간, 실시간 멀티 에이전트 협업.
위험: 보안 확보가 가장 어렵고, 관찰이 가장 복잡하며, 피호출자가 부분적인 컨텍스트를 적절히 처리해야 함.

OpenLegion의 견해: 컨텍스트 손실과 자격 증명 유출이 실제 핸드오프 버그인 이유

대부분의 멀티 에이전트 핸드오프 실패는 두 가지 범주로 나뉩니다: 컨텍스트 손실 버그와 자격 증명 유출 버그. 둘 다 설계로 방지할 수 있습니다.

컨텍스트 손실 수치: LLM 컨텍스트 압축 평가에서는 핸드오프 경계에서의 단순 잘라내기가 구조화된 요약과 비교하여 멀티홉 추론 작업의 작업 완료율을 저하시킨다고 일관되게 나타납니다. 해결책은 더 큰 컨텍스트 창이 아니라 완료된 작업, 남은 작업, 핵심 발견 사항을 위한 명시적 필드가 있는 구조화된 핸드오프 페이로드입니다.

자격 증명 유출: OWASP LLM06:2025(민감한 정보 공개)는 에이전트 간 메시지 전달을 통한 자격 증명 유출을 상위 10개 LLM 취약성 중 하나로 명시적으로 다루고 있습니다.

컨텍스트 손실 문제: 경계에서 무엇이 삭제되는가

컨텍스트 손실의 근본 원인은 호출 에이전트가 알고 있는 것과 핸드오프 페이로드가 전달하는 것 사이의 불일치입니다. 구조화된 핸드오프 페이로드는 이를 방지합니다: 호출자는 필드를 명시적으로 채웁니다: 작업 목표, 지금까지 완료된 작업, 미해결 하위 작업, 핵심 발견 사항, 출력 키 포인터.

핸드오프 페이로드를 통한 자격 증명 유출(OWASP LLM06:2025)

Google ADK의 transfer_to_agent()는 대화 기록을 포함한 전체 Session 객체를 수신 에이전트에 전달하여 기본적으로 최대 32K 토큰의 컨텍스트 전송을 생성합니다. 팀들은 핸드오프 구현을 AI 에이전트 보안: 자격 증명 격리 및 프롬프트 인젝션 방어에 대해 감사해야 합니다.

안전한 기본값으로서의 블랙보드 포인터 패턴

블랙보드 포인터 패턴은 애플리케이션 레이어 필터링에 의존하는 대신 프로토콜 레벨에서 자격 증명 노출을 제거합니다. OpenLegion의 Vault에 저장된 자격 증명은 에이전트 컨텍스트에 절대 주입되지 않습니다.

주요 프레임워크의 핸드오프 구현 방법

OpenAI Agents SDK: input_filter를 사용한 handoff()(27,133 스타)

openai/openai-agents-python(GitHub 스타 27,133, MIT 라이선스)은 handoff()를 푸시 패턴으로 구현합니다. input_filter 매개변수는 v0.0.5(2025년 3월)에 추가되었으며 명시적 옵트인이 필요합니다.

from agents import Agent, handoff, RunContextWrapper

def strip_credentials(ctx: RunContextWrapper, input_data: ResearchInput) -> ResearchInput:
    return ResearchInput(task=input_data.task, context=input_data.context)

researcher = Agent(
    name="researcher",
    handoffs=[handoff(writer_agent, input_filter=strip_credentials)]
)

Google ADK: transfer_to_agent()와 Session 객체 전송(20,100 스타)

google/adk-python(GitHub 스타 20,100, Apache-2.0)은 transfer_to_agent()를 통해 핸드오프를 구현하며, 대화 기록을 포함한 전체 Session 객체를 전달합니다. 수신 에이전트는 모든 것을 받고 불필요한 기록을 명시적으로 삭제해야 합니다.

LangGraph: 공유 타입 상태를 사용한 Command(goto=)

LangGraph(langchain-ai/langgraph, Apache-2.0)는 선택적 상태 업데이트와 함께 Command(goto='노드_이름')을 통해 에이전트 라우팅을 구현합니다. 상태는 그래프의 모든 노드에서 공유되는 타입 딕셔너리입니다. LangGraph의 공유 상태 모델은 노드 간 자격 증명 격리를 제공하지 않습니다.

from langgraph.types import Command

def researcher_node(state: AgentState) -> Command:
    result = researcher.invoke(state)
    return Command(
        goto="writer",
        update={"research_output": result, "completed_steps": state["completed_steps"] + ["research"]}
    )

OpenLegion: 블랙보드 포인터와 받은 편지함 전달을 사용한 hand_off()

OpenLegion의 hand_off() 함수는 블랙보드 포인터 핸드오프를 기본으로 구현합니다.

hand_off(
    to="writer",
    summary="조사 완료: langchain-alternative, 소스 자료 2847단어",
    data='{"topic": "langchain-alternative", "sources_key": "research/langchain-alt-sources", "word_count_target": 3000}'
)

핸드오프 데이터 계약

포함할 항목: 작업 요약, 출력 키, 관련 기록

잘 설계된 핸드오프 페이로드는 구조화된 사양이며 트랜스크립트 덤프가 아닙니다. 포함할 항목:

  • 작업 요약(200단어 이내): 피호출자가 달성해야 할 사항
  • 출력 키 포인터: 호출자의 출력이 저장된 블랙보드 키
  • 완료된 작업 요약: 이미 수행된 것, 사실로서 기술
  • 미해결 하위 작업: 피호출자가 담당하는 특정 항목
  • 구조화된 매개변수: 피호출자의 작업에 필요한 타입 입력

제외할 항목: 원시 자격 증명, 전체 컨텍스트 창, 중간 스크래치패드

핸드오프 페이로드에서 제외할 항목:

  • API 키, 토큰, 자격 증명: 실행 시점에 메시에 의해 주입되어야 함
  • 전체 대화 트랜스크립트: 관련 요약으로 잘라내기
  • 중간 추론 스크래치패드: 호출자의 사고 과정은 피호출자에게 유용하지 않음
  • 피호출자의 역할에 필요하지 않은 데이터: 컨텍스트에도 최소 권한 적용

핸드오프 라우팅 메커니즘

정적 라우팅: 하드코딩된 에이전트 ID

정적 라우팅은 특정 유형의 각 핸드오프를 특정 명명된 에이전트로 보냅니다. 구현이 간단하고 추적이 용이합니다. 대상 에이전트를 사용할 수 없거나 과부하이거나 교체된 경우 중단됩니다.

동적 라우팅: LLM이 선택한 전문가

동적 라우팅은 LLM 호출을 사용하여 작업 특성에 따라 적절한 전문가 에이전트를 선택합니다. 유연성을 제공하지만 지연 시간을 추가하고 LLM이 작업을 잘못 분류할 경우 라우팅 오류 가능성이 있습니다.

조건부 라우팅: 규칙 기반 에스컬레이션

조건부 라우팅은 대상 에이전트를 선택하기 위한 결정론적 규칙을 적용합니다. LLM 기반 라우팅보다 예측 가능하지만 각 라우팅 조건에 대한 명시적 규칙 정의가 필요합니다.

폴백 및 타임아웃 처리

각 핸드오프는 타임아웃 창 내에 피호출자가 응답하지 않을 경우의 처리를 정의해야 합니다. 옵션:

  • 같은 피호출자로 재시도: 실패가 일시적일 가능성이 높을 때 적절
  • 대체 에이전트로 재라우팅: 기본 피호출자를 지속적으로 사용할 수 없을 때 적절
  • 운영자에게 에스컬레이션: 작업에 인간 판단이 필요할 때 적절
  • 블랙보드에 실패 기록 후 계속: 다운스트림 작업이 선택적일 때 적절

핸드오프 패턴 보안 및 신뢰성 비교

차원푸시 핸드오프풀 디스패치블랙보드 라우팅스트리밍 핸드오프
라우팅 메커니즘피호출자에 대한 직접 깨우기 호출공유 큐/받은 편지함 요청키 쓰기+피호출자 감시점진적 토큰 스트림
컨텍스트 격리호출자가 페이로드 제어; input_filter 필요큐 메시지만가장 높음: 피호출자는 명명된 키만 읽음가장 낮음: 전체 컨텍스트가 경계를 넘음
자격 증명 노출 위험중간: input_filter 옵트인에 따라 다름낮음: 큐는 작업 포인터만 보유매우 낮음: 자격 증명은 페이로드에 없음높음: 스트림에 민감한 컨텍스트 포함 가능
관찰 가능성핸드오프당 단일 추적 이벤트큐 깊이+요청 이벤트키 버전 기록+받은 편지함 이벤트토큰 수준 추적 필요
지연 시간가장 낮음낮음(큐 읽기 오버헤드)낮음(블랙보드 읽기 오버헤드)가장 낮은 엔드투엔드(스트리밍)
최적 용도긴밀하게 결합된 전문가 위임부하 분산된 워커 풀비동기 분리된 파이프라인실시간 협업

자주 묻는 질문

에이전트 핸드오프 패턴이란 무엇인가요?

에이전트 핸드오프 패턴은 하나의 AI 에이전트에서 다른 에이전트로 작업을 전송하기 위한 프로토콜입니다. 어떤 컨텍스트 데이터가 경계를 넘는지, 수신 에이전트에게 어떻게 알리는지, 자격 증명 또는 메모리 유출을 방지하는 격리 보증을 지정합니다. 4가지 표준 패턴은 푸시 핸드오프, 풀 디스패치, 블랙보드 포인터 라우팅, 스트리밍 핸드오프로, 각각 보안, 지연 시간, 관찰 가능성에서 서로 다른 트레이드오프를 가집니다.

OpenAI Agents SDK는 핸드오프를 어떻게 구현하나요?

OpenAI Agents SDK(GitHub 스타 27,133, MIT)는 handoff()를 푸시 패턴으로 구현합니다. 호출 에이전트는 대상 에이전트와 전송 전에 컨텍스트에서 필드를 제거하는 선택적 input_filter 함수로 handoff()를 호출합니다. input_filter 매개변수는 v0.0.5(2025년 3월)에 추가되었으며 명시적 옵트인이 필요합니다; 없으면 전체 컨텍스트 창이 피호출자에게 전달됩니다.

Google ADK는 에이전트 핸드오프를 어떻게 구현하나요?

Google ADK(GitHub 스타 20,100, Apache-2.0)는 대화 기록을 포함한 전체 Session 객체를 수신 에이전트에 전달하는 transfer_to_agent()를 사용합니다. 기본적으로 최대 32K 토큰의 컨텍스트 전송이 생성됩니다. 수신 에이전트는 전체 기록을 받고 관련 없는 이전 컨텍스트를 명시적으로 삭제해야 합니다.

블랙보드 포인터 핸드오프 패턴이란 무엇이며 왜 더 안전한가요?

블랙보드 포인터 핸드오프에서 호출자는 공유 저장소(output/agent-id/task-id 등)의 명명된 키에 출력을 쓰고, 피호출자에게 데이터 자체가 아닌 키 포인터만 보냅니다. 피호출자는 필요한 필드만 읽습니다. 자격 증명은 핸드오프 메시지에 결코 나타나지 않아 OWASP LLM06:2025(민감한 정보 공개) 유출 벡터를 제거합니다. OpenLegion의 hand_off()는 이 패턴을 기본으로 구현합니다.

에이전트 핸드오프에는 어떤 보안 위험이 있나요?

주요 위험은 자격 증명 유출입니다: 핸드오프 중에 전달되는 컨텍스트 객체에 환경 변수, 베어러 토큰 또는 API 키를 포함하는 프레임워크는 이를 수신 에이전트에 노출합니다. 수신 에이전트는 손상되었거나 더 넓은 네트워크 접근 권한을 가질 수 있습니다. OWASP LLM06:2025는 이를 상위 10개 LLM 취약성으로 식별합니다. 이차적 위험은 컨텍스트 포이즈닝입니다.

핸드오프 실패와 타임아웃을 어떻게 처리하나요?

견고한 핸드오프 파이프라인은 타임아웃과 폴백 경로를 정의합니다: 같은 피호출자로 재시도, 대체 전문가로 재라우팅, 인간 운영자에게 에스컬레이션, 또는 블랙보드에 실패 기록 작성. 호출 에이전트는 핸드오프 ID를 추적하고 작업 완료 이벤트를 모니터링해야 합니다.

핸드오프 페이로드에 어떤 데이터를 포함해야 하나요?

포함할 항목: 간결한 작업 요약(200단어 미만), 공유 저장소의 출력 데이터 키에 대한 포인터, 완료된 작업 사실, 미해결 하위 작업, 피호출자의 역할에 필요한 구조화된 매개변수. 제외할 항목: 원시 API 자격 증명, 전체 대화 트랜스크립트, 중간 추론 스크래치패드, 피호출자의 역할에 필요하지 않은 데이터.

OpenLegion에서의 안전한 에이전트 핸드오프

핸드오프 경계는 대부분의 멀티 에이전트 신뢰성 문제가 시작되는 곳입니다. 컨텍스트 손실은 다운스트림 작업 품질을 저하시키고, 페이로드의 자격 증명 유출은 파이프라인 길이와 함께 증가하는 유출 위험을 생성합니다.

OpenLegion의 블랙보드 포인터 핸드오프는 프로토콜 레벨에서 두 가지 문제 모두를 해결합니다. hand_off()는 출력을 명명된 키에 쓰고, 수신자의 받은 편지함에 포인터만 전달하며, Vault 프록시 자격 증명 주입에 의존합니다. 수신자는 블랙보드에서 필요한 것만 읽으며 그 이상은 읽지 않습니다.

핸드오프 프로토콜이 놓치는 실패를 감지하는 모니터링 레이어는 에이전트 관찰 가능성: 파이프라인 단계 전반에 걸친 핸드오프 추적을 참조하세요. 어떤 핸드오프 패턴을 선택할지 결정하는 프레임워크 레이어는 프로덕션 배포를 위한 AI 에이전트 프레임워크 비교를 참조하세요.

OpenLegion에서 안전한 멀티 에이전트 파이프라인 구축 →