연구 에이전트는 고객의 계정을 찾고, 플랜을 확인하고, 지난 네 개의 인보이스를 가져왔습니다. 이는 "고객이 환불을 원합니다."라는 한 줄 요약과 함께 결제 에이전트에게 인계되었습니다. 이제 계정, 플랜, 인보이스에 대해 아무것도 모르는 결제 에이전트는 계정 ID를 묻는 것으로 시작합니다.
첫 번째 에이전트가 수집한 모든 사실은 경계에서 버려졌습니다. 이것이 바로 인계 문제입니다. 이 문제로 인해 두 번의 비용이 발생합니다. 한 번은 중복된 API 호출에서, 다른 한 번은 두 번째 에이전트가 첫 번째 에이전트보다 적은 정보로 작업하면서 발생하는 오류에서 말입니다.
이 가이드는 인계를 통해 무엇이 살아남아야 하는지, 팀이 상태를 전달하는 세 가지 방법과 각각의 작동 시기, 요약이 예상보다 더 많은 것을 잃는 이유, 그리고 인계가 주장하는 바를 전달했는지 테스트하는 방법을 다룹니다. 운영 환경에서 에이전트가 고장나는 이유에 대한 저희 게시물은 손실된 상태를 핵심적인 실패 모드로 다룹니다. 이 가이드는 그 문제의 다중 에이전트 버전입니다.
Apidog가 등장하는 이유는 가장 저렴한 해결책이 일반적으로 데이터를 전혀 전달하지 않고 대신 식별자를 전달하는 것이기 때문입니다. 이는 모든 에이전트가 동일한 방식으로 동일한 레코드를 가져올 수 있는 경우에만 작동합니다.
경계를 실제로 넘어야 하는 것
모든 것은 아닙니다. 전체 대화를 복사하는 인계는 아무것도 복사하지 않는 인계만큼이나 잘못된 것입니다. 다만 방향이 다를 뿐입니다. 두 번째 에이전트는 전체 컨텍스트 창을 상속받으며 어떤 부분이 중요한지 파악해야 합니다.
네 가지 범주를 구분할 가치가 있습니다.
식별자. 계정 ID, 주문 ID, 작업 ID, 티켓 번호. 이들은 작고 안정적이며, 수신 에이전트가 필요한 모든 것을 가져올 수 있게 합니다. 이들은 전달해야 할 가장 가치 있는 것이며 가장 흔하게 누락됩니다.
이미 내려진 결정. "고객은 정책 3에 따라 환불 자격이 있습니다." 수신 에이전트는 이를 다시 논쟁해서는 안 됩니다. 만약 그렇게 한다면, 하나의 작업 내에서 두 에이전트가 의견 충돌을 일으키게 됩니다.
제약 조건. 예산 한도, 승인 허용, 이미 수행된 작업. 이를 잃으면 작업이 두 번 청구되거나 동일한 승인을 두 번 요청하게 됩니다. 이는 AI 에이전트의 멱등성에 대한 저희 게시물과 직접적으로 연결됩니다.
미해결 질문. 첫 번째 에이전트가 해결하지 못한 것. 이를 명시적으로 전달하면 두 번째 에이전트가 묵묵히 추정하는 것을 방지합니다.
건너갈 필요가 없는 것: 원시 API 응답, 추론 기록, 그리고 수신 에이전트가 한 번의 호출로 스스로 가져올 수 있는 모든 것.
상태를 전달하는 세 가지 방법
전체 대화를 전달. 간단하며, 하나의 짧은 작업에서 두 에이전트에게 효과적입니다. 대화 기록이 길어지면 실패하는데, 수신 에이전트가 대부분의 예산을 기록을 읽는 데 사용하고 관련 사실이 중간에 묻히기 때문입니다. 도구 응답을 컨텍스트 창에서 제외하기에 대한 저희 게시물은 모델이 중간에서 정보를 잃는 이유를 설명합니다.
요약을 전달. 첫 번째 에이전트가 인계 메시지를 작성하고, 두 번째 에이전트가 이를 시작점으로 삼습니다. 이는 대부분의 프레임워크에서 기본이며 특정 방식으로 정보 손실이 발생합니다. 모델은 내러티브 방향으로 요약하고 식별자에서는 멀어집니다. 요약을 요청하면 "고객은 2년 동안 구독자였고 불만을 가지고 있습니다"라는 내용이 "계정 8812, 프로 플랜, 인보이스 4개, 인보이스 inv_44에 대한 환불 승인" 대신 제공됩니다.
구조화된 인계 객체 전달. 첫 번째 에이전트가 스키마를 채웁니다. 두 번째 에이전트는 산문이 아닌 필드를 읽습니다. 설정하는 데 더 많은 작업이 필요하지만, 이것이 가장 견고한 방법입니다.
{
"task_id": "task_2026_08_26_0031",
"from_agent": "research",
"to_agent": "billing",
"entities": {
"customer_id": "cus_8812",
"invoice_ids": ["inv_41", "inv_42", "inv_43", "inv_44"],
"subscription_id": "sub_119"
},
"decisions": [
{ "decision": "refund_eligible", "value": true, "basis": "policy 3.2, charged twice in one cycle" }
],
"constraints": {
"max_refund_cents": 4900,
"human_approval_granted": false,
"actions_taken": ["read_invoices"]
},
"open_questions": ["Customer has not confirmed which invoice to refund"],
"summary": "Customer cus_8812 was double-charged in August. Refund of one invoice is approved under policy 3.2, up to 4900 cents. Awaiting the customer's choice of invoice."
}
산문은 여전히 summary 필드에 나타나는데, 이는 스키마가 담지 못하는 뉘앙스를 전달하기 때문입니다. 이는 구조화된 필드를 대체하는 것이 아니라 함께 존재하며, 이것이 바로 핵심입니다.
인계가 실행되기 전에 객체를 검증하십시오. `customer_id`가 누락된 경우, 두 번째 에이전트가 세 번의 호출 후에 이를 발견하도록 하는 대신 경계에서 즉시 명확하게 실패하도록 하십시오.
페이로드가 아닌 참조 전달
인계의 가장 강력한 버전은 거의 데이터를 전달하지 않습니다. ID를 전달하고, 수신 에이전트가 필요한 것을 가져옵니다.
이것은 세 가지 이유로 작동합니다. 상태는 최신으로 유지되므로, 두 에이전트 사이에 변경 사항이 발생하면 두 번째 에이전트가 오래된 사본이 아닌 현재 값을 보게 됩니다. 인계는 수만 개의 토큰 대신 수백 바이트로 작게 유지됩니다. 그리고 모든 읽기가 프롬프트 간에 복사된 텍스트가 아닌 API 호출로 나타나므로 감사 추적이 개선됩니다.
이것은 한 가지를 요구합니다. 모든 에이전트가 올바른 권한으로 동일한 API에 접근할 수 있어야 합니다. 이는 공짜가 아닙니다. 각 에이전트는 자신이 수행하는 작업에 맞춰 범위가 지정된 자체 자격 증명이 필요하며, 이는 에이전트를 위한 최소 권한 API 키에 대한 저희 게시물의 논점입니다. 읽기 전용 연구 토큰을 가진 결제 에이전트는 환불을 발행할 수 없으며, 결제 토큰을 가진 연구 에이전트는 폭발 반경 문제입니다.
재가져오기가 비싸거나 느린 경우, 오케스트레이터에 레코드를 캐시하고 캐시 항목에 대한 참조를 전달하십시오. 수신 에이전트는 여전히 데이터를 명시적으로 요청하므로 패턴은 동일하게 유지되지만, 두 번째 읽기는 저렴합니다.
실제로 인계가 실패하는 지점
네 가지 실패 유형이 대부분의 사건을 설명합니다.
누락된 식별자. 요약은 "고객"이라고 말하고 ID를 전혀 제공하지 않아서, 두 번째 에이전트가 이름으로 검색하여 두 개의 일치하는 항목을 찾고 잘못된 것을 선택합니다. 인계가 진행되기 전에 필요한 엔티티 ID가 존재하는지 유효성 검사를 통해 이를 방지하십시오.
반복된 작업. 첫 번째 에이전트가 이미 이메일을 보냈습니다. 인계는 이를 기록하지 않습니다. 두 번째 에이전트가 다시 보냅니다. 인계 객체에 actions_taken을 기록하고, 쓰기 작업 전에 이를 확인하며, 반복을 무해하게 만드는 멱등성 키로 뒷받침하십시오.
누락된 승인. 첫 번째 에이전트가 실행되는 동안 사람이 환불을 승인했습니다. 이를 알지 못하는 두 번째 에이전트가 다시 요청합니다. 사용자는 두 번째 프롬프트를 귀 기울이지 않는 시스템으로 인식합니다. 승인을 명시적인 제약 조건으로 전달하고, 에이전트가 아닌 작업에 범위가 지정된 것으로 처리하십시오.
자신감 있는 날조. 수신 에이전트가 인계에 포함되지 않은 값을 필요로 할 때, 묻는 대신 내러티브에 맞는 값을 날조합니다. 이것은 완료된 작업처럼 보이기 때문에 가장 위험한 실패입니다. 방어책은 open_questions 필드와 수신 에이전트의 프롬프트에 있는 엄격한 규칙입니다. 즉, 필수 식별자가 없으면 중단하고 물어봐야 합니다.
반복은 이 네 가지를 모두 악화시킵니다. 에이전트 A가 B에게 인계하고 B가 A에게 다시 인계할 때, 복사본의 복사본처럼 각 전달마다 상태가 저하됩니다. 홉 수를 제한하고, 각 경계에서 다시 빌드하는 대신 원래 작업 객체를 모든 홉을 통해 전달하십시오.
에이전트만이 아닌 경계를 테스트하세요
인계는 통합 지점이므로, 통합 지점으로서 테스트해야 합니다.
인계 객체에 대해 단언하십시오. 고정된 시나리오에 대해 첫 번째 에이전트를 실행하고 생성된 객체를 확인하십시오: 필수 식별자 존재, 결정 기록, 작업 목록. 이는 그것을 생성한 에이전트가 비결정적일지라도 구조화된 페이로드에 대한 결정적 단언이며, 이것이 유용한 테스트가 되는 이유입니다. 일반적인 접근 방식은 비결정적 AI 에이전트 테스트에 대한 저희 가이드에 있습니다.
수신자를 독립적으로 테스트하십시오. 결제 에이전트에 수동으로 만든 인계 객체를 제공하고 그 동작을 확인하십시오. 그런 다음, 고객 ID가 제거된 의도적으로 손상된 객체를 제공하고, 추측 대신 질문하는지 확인하십시오. 이 두 번째 테스트가 날조를 잡아내는 테스트입니다.
둘 다 목(mock)에 대해 실행하십시오. 실제 환불을 발행하는 인계 테스트는 한 번만 실행할 테스트입니다. 운영 환경 대신 목(mock)에 대해 에이전트 실행하기에 대한 저희 게시물을 따라, 모든 변경 사항에서 스위트가 실행될 수 있도록 두 에이전트 모두 목(mock) 엔드포인트를 가리키도록 하십시오. Apidog에서는 목(mock)이 두 에이전트가 모두 호출하는 동일한 API 정의에서 나오므로, 둘은 결코 멀어지지 않습니다.
모든 인계를 기록하십시오. 작업 ID와 함께 각 경계에서 전체 객체를 기록하십시오. 다중 에이전트 실행이 잘못될 경우, 인계 로그는 어떤 에이전트가 정보를 가지고 있었고 어떤 에이전트가 정보를 잃었는지 알려주며, 이것이 보통 전체 조사의 핵심입니다. 에이전트 도구 호출 추적에 대한 저희 게시물은 해당 기록에 무엇이 더 포함되어야 하는지 다룹니다.
프레임워크가 제공하는 것
대부분의 오케스트레이션 프레임워크는 인계 기본 기능을 제공하며, 의존하기 전에 각 기능이 실제로 경계를 넘어 무엇을 이동시키는지 아는 것이 도움이 됩니다.
OpenAI Agents SDK 인계 문서는 인계를 에이전트가 호출할 수 있는 도구로 모델링하며, 이는 모델이 제어권이 언제 전달되는지 결정한다는 의미입니다. 이는 편리하지만, 시스템의 가장 비결정적인 부분에 결정을 맡기므로, 나갈 때 유효성 검사와 함께 사용해야 합니다.
LangGraph의 다중 에이전트 가이드는 정반대의 접근 방식을 취합니다. 즉, 상태는 모든 노드가 읽고 쓰는 명시적인 그래프 객체입니다. 이는 위에서 설명한 구조화된 인계와 밀접하게 관련되어 있으며, 여러분에게 남겨진 주요 작업은 어떤 필드가 필수인지 결정하는 것입니다.
다중 에이전트 연구 시스템 구축에 대한 Anthropic의 글은 운영 세부 사항, 특히 하위 에이전트가 유용하게 스스로 작동하기 전에 얼마나 많은 지시가 필요한지에 대해 읽어볼 가치가 있습니다.
공통된 핵심은 다음과 같습니다. 모든 프레임워크는 무언가를 이동시킵니다. 어떤 사실이 핵심적인지 여러분을 대신해서 결정해 주는 프레임워크는 없습니다. 그 목록은 여러분이 작성해야 하며, 실행이 잘못되었을 때 검토할 가치가 있는 것입니다.
작업 객체를 대화 외부에 유지
한 가지 구조적 변경으로 모든 종류의 버그를 방지할 수 있습니다. 작업 상태를 작업 ID를 키로 하여 영구적인 곳에 저장하고, 모든 에이전트가 메시지를 통해 전달하는 대신 이를 읽고 쓰도록 하십시오.
대화는 상태를 담는 데 부적절한 컨테이너입니다. 요약에 의해 압축되고, 잘리고, 다시 작성되며, 이러한 작업 중 어느 것도 여러분이 잃어서는 안 되는 필드가 무엇인지 알지 못합니다. 데이터베이스의 한 행은 그런 문제가 없습니다.
패턴은 간단합니다. 턴이 시작될 때 에이전트는 작업 객체를 로드합니다. 작업을 수행할 때, `actions_taken`에 추가하고 저장합니다. 인계 시, 작업 ID를 전달하고 수신 에이전트는 동일한 객체를 로드합니다. 중요한 것은 프롬프트에 전달되지 않으므로, 중요한 것이 요약되어 사라질 수 없습니다.
이는 또한 재개 지점을 제공합니다. 실행이 네 번째 단계에서 중단되더라도, 작업 객체는 첫 세 단계에서 확립된 모든 것을 여전히 보유하고 있으며, 재시도는 아무것도 없는 상태에서 시작하는 대신 그 지점에서 시작합니다.
플랫폼이 상태를 유지할 수 있는 곳
에이전트가 개발자 머신에서 CLI 런타임으로 실행되는 경우, 위에서 설명한 영구적인 작업 객체는 여러분이 구축해야 하는 것입니다. 일부 에이전트 작업 관리 플랫폼은 이미 이를 모델링하고 있으며, 여러분이 직접 작성하기 전에 그것이 어떻게 생겼는지 아는 것이 가치가 있습니다.
Sharkly는 바로 이 단위를 중심으로 구축된 사람과 에이전트를 위한 작업 관리 시스템입니다. 태스크는 목표, 상태, 담당자, 실행을 위해 할당된 에이전트 또는 크루, 코멘트, 에이전트의 실행 상태 및 결과를 담고 있습니다. 크루는 리더 에이전트를 다른 에이전트 및 사람들과 짝지어주므로, 여러 전문가가 필요한 태스크는 프롬프트를 통해 수동으로 전달되는 대신 재사용 가능한 그룹에 할당됩니다. 상태가 대화가 아닌 태스크에 존재하기 때문에, 두 에이전트 간의 인계는 한쪽이 요약을 잘하는 능력에 의존하지 않습니다.
런타임은 여러분이 이미 사용하는 어떤 것이든 유지됩니다. Claude Code, Codex 등은 여러분이 등록한 컴퓨터에서 작업을 실행합니다. 플랫폼은 작업 기록, 할당, 그리고 그 주변의 검토 루프를 제공합니다. 영구적인 작업 패턴을 직접 구축하고 있다면, Sharkly 문서가 어떤 필드가 중요한지 확인하는 데 유용한 참고 자료가 될 것입니다.
인계를 위한 체크리스트
- 인계를 위한 정의된 스키마가 존재하며, 경계에서 유효성 검사가 이루어집니다.
- 엔티티 식별자는 선택 사항이 아닌 필수 필드입니다.
- 결정에는 그 근거가 포함되어, 수신자가 추론을 다시 할 필요가 없습니다.
- 이미 수행된 작업은 기록되며 쓰기 전에 확인됩니다.
- 승인 및 예산은 에이전트가 아닌 작업과 함께 이동합니다.
- 미해결 질문은 명시적이며, 수신자는 추정하는 대신 질문합니다.
- 재가져오기가 저렴한 경우 데이터는 참조로 전달됩니다.
- 홉 수는 제한되며, 원래 작업 객체는 모든 홉을 통해 유지됩니다.
- 모든 인계는 작업 ID와 함께 기록됩니다.
- 경계 테스트는 의도적으로 불완전한 인계를 포함하여 목(mock)에 대해 CI에서 실행됩니다.
대부분의 다중 에이전트 실패는 추론 실패가 아닙니다. 그것은 한 에이전트에는 존재했지만 다음 에이전트에는 존재하지 않았던 사실입니다. 경계를 스키마와 테스트를 갖춘 인터페이스로 설계하면, 두 번째 에이전트가 첫 번째 에이전트가 이미 답변한 질문을 묻는 것을 멈출 것입니다. Apidog 다운로드를 통해 두 에이전트가 의존하는 API 옆에 목(mock)과 경계 테스트를 유지하십시오.
자주 묻는 질문
구조화된 인계는 두 에이전트에게 가치가 있나요? 짧은 작업에서 두 에이전트의 경우, 대화를 전달하는 것은 일반적으로 괜찮습니다. 구조화된 객체는 세 명 이상의 에이전트, 긴 작업, 또는 인계가 프로세스나 실행 경계를 넘는 모든 곳에서 그 가치를 발휘합니다.
모델이 인계 객체를 작성해야 할까요, 아니면 코드가 구축해야 할까요? 가능한 곳에서는 코드가 해야 합니다. 식별자, 수행된 작업, 승인은 모델의 기억이 아닌 실제로 일어난 일로부터 오케스트레이터에 의해 채워져야 합니다. 모델은 summary와 미해결 질문만 작성하도록 하십시오.
루프에서 컨텍스트 손실을 어떻게 막나요? 각 경계에서 다시 생성하는 대신, 하나의 작업 객체를 전체 실행을 통해 전달하고 업데이트하십시오. 그런 다음 홉 수를 제한하십시오. 작업이 몇 개 이상의 홉을 필요로 한다면, 분해가 잘못되었을 가능성이 큽니다.
내장된 인계 지원이 있는 프레임워크는 어떤가요? 이를 사용하되, 실제로 무엇을 전송하는지 확인하십시오. 많은 경우 메시지 기록만 전달하며 다른 것은 전달하지 않습니다. 이는 식별자가 텍스트에 나타나는 경우에만 살아남는다는 의미입니다. 프레임워크가 전달하는 것과 함께 구조화된 페이로드를 추가하십시오.
하위 에이전트에게 별도의 API 자격 증명이 필요한가요? 네, 각 에이전트가 수행하는 작업에 맞춰 범위가 지정되어야 합니다. 여러 에이전트 간에 하나의 강력한 키를 공유하는 것은 손상을 제한하고 어떤 에이전트가 호출했는지 파악하는 능력을 제거합니다. 에이전트를 위한 최소 권한 API 키에 대한 저희 게시물은 설정 방법을 다룹니다.
요약 필드에는 얼마나 많은 내용이 포함되어야 할까요? 구조화된 필드에 담을 수 없는 의도와 뉘앙스를 다루는 몇 문장 정도입니다. 만약 ID와 금액을 나열하기 시작한다면, 그것들은 유효성 검사가 가능한 구조화된 필드에 속해야 합니다.