Deep Agent Builder 멀티에이전트 개념
멀티에이전트는 부모 에이전트가 업무 일부를 서브에이전트에 맡기고 결과를 이어서 사용하는 실행 구조입니다. 이 페이지는 연결 조건, 실행 전 권한 검사, 산출물 전달 경계를 설명합니다. 실제 연결과 저장은 에이전트 수정을 먼저 확인하세요.
부모 에이전트와 서브에이전트의 관계
부모 에이전트는 사용자의 요청과 전체 실행 흐름을 관리합니다. 서브에이전트는 부모가 위임한 작업을 처리합니다. 두 에이전트를 연결했다고 해서 자원, 권한, 결과 표시가 모두 같은 방식으로 동작하는 것은 아닙니다.
서브에이전트 연결은 에이전트 설정의 참조 목록으로 저장됩니다. 연결 대상은 호출자가 소유하고 보관되지 않은 일반 에이전트여야 합니다. Super Agent는 대상이 될 수 없습니다. 자기 자신을 연결하거나 순환 참조를 만들면 저장이 거부됩니다.
구성을 점검할 때는 다음 세 범위를 나눠 봅니다.
| 구분 | 확인할 내용 |
|---|---|
| 구성 | 부모가 어떤 서브에이전트를 참조하는가 |
| 실행 | 현재 사용자가 연결된 자원을 사용할 권한이 있는가 |
| 결과 | 산출물이 사용자 화면과 부모 모델에 어떻게 전달되는가 |
연결할 때 확인할 조건
서브에이전트를 추가할 때는 다음 순서로 확인합니다.
- 부모와 대상이 호출자 소유 범위에 있는지 확인합니다.
- 대상이 보관 상태가 아니며 Super Agent가 아닌지 확인합니다.
- 중복 연결, 자기 참조, 순환 참조가 없는지 확인합니다.
- 저장 후 부모의 서브에이전트 참조 목록을 확인합니다.
- 실행 전에 부모가 사용하는 model, tool, middleware, skill과 직접 연결된 서브에이전트가 권한 검사 대상에 포함되는지 확인합니다.
저장 성공만으로 실행 성공을 판단하지 마세요. 연결 목록은 설정 상태입니다. 실행 가능 여부는 실행 시점의 권한과 자원 상태를 다시 통과해야 합니다.
실행 전 권한 검사
실행을 시작하면 서비스 계층이 부모 에이전트, 선택한 thread, 실행 모드에 연결된 자원을 모아 권한을 평가합니다. 허용 결과는 실행의 권한 묶음으로 보존되어 실행 런타임에 전달됩니다.
실행 런타임은 이 묶음을 다음과 같이 다시 확인합니다.
- 권한 묶음이 만료되지 않았는가
- 실행 ID와 부모 에이전트 식별자가 서로 맞는가
- 같은 권한 묶음을 재사용한 요청이 아닌가
- 실제로 사용할 model, tool, middleware, skill과 직접 연결된 서브에이전트가 포함됐는가
- 필요한 자원에 RESOURCE_CAN_USE 권한이 있는가
검사에 실패하면 graph를 구성하거나 호출하기 전에 실행이 중단됩니다. 권한 거부, 정책 결정 시간 초과, 만료, 재사용은 서로 다른 실패 원인으로 확인해야 합니다.
이 페이지는 동적으로 새 서브에이전트를 찾아 위임하는 내부 API의 계약을 설명하지 않습니다. 동적 위임을 지원한다고 확대 해석하지 말고, 권한 묶음과 실행 전 검사 결과를 기준으로 현재 실행 경계를 확인하세요.
산출물이 전달되는 방식
서브에이전트의 task 결과는 두 경로로 나뉩니다.
- 사용자 화면에는 원본 task 결과가 표시됩니다.
- 부모 모델의 다음 요청에는 같은 산출물 전체 대신 짧은 placeholder가 전달됩니다.
placeholder에는 산출물 식별자, 파싱된 유형과 제목, 본문 문자 수, 필요할 때 원문을 조회하라는 안내가 남습니다. 부모가 후속 작업에 원문이 필요하면 부모 전용 산출물 조회 경로로 식별자를 조회할 수 있습니다. 조회 결과에서는 산출물 표시용 태그가 제거되므로 같은 산출물이 다시 카드처럼 렌더링되지 않습니다.
서브에이전트 결과가 화면에 보였다는 사실과 부모의 다음 답변에 그 내용이 포함됐다는 사실은 별도로 확인해야 합니다. 원문이 필요하지 않은 후속 작업이라면 조회하지 않는 것이 기본입니다.
대표적인 실패와 판단
| 상황 | 먼저 확인할 것 | 다음 판단 |
|---|---|---|
| 저장이 거부됨 | 소유자, 보관 상태, Super Agent 여부, 자기 참조와 cycle | 대상 구성을 바꾼 뒤 다시 저장합니다. 권한 오류를 입력 오류로 보지 않습니다. |
| 저장은 됐지만 실행되지 않음 | 직접 연결된 자원의 RESOURCE_CAN_USE, 권한 묶음 만료와 실행 ID | 설정 화면이 아니라 실행 전 권한 검사 결과를 확인합니다. |
| 결과는 보이지만 부모가 이어 쓰지 못함 | 산출물 식별자와 placeholder 상태 | 부모 전용 원문 조회가 필요한지 판단합니다. 자동 병합됐다고 가정하지 않습니다. |
| 같은 산출물이 두 번 표시됨 | 원본 결과와 후속 조회 결과를 함께 렌더링했는지 | 후속 조회 결과의 표시용 태그 제거 여부를 확인합니다. 화면 합성으로 문제를 가리지 않습니다. |
구성 완료 확인
멀티에이전트 구성을 완료했다고 판단하려면 다음을 각각 확인합니다.
- 부모 에이전트의 서브에이전트 참조 목록이 의도한 값입니다.
- 자기 참조나 순환 참조가 없습니다.
- 부모와 직접 연결된 자원을 현재 사용자가 사용할 권한이 있습니다.
- 실행 전 권한 검사에서 직접 연결된 서브에이전트가 허용 목록에 포함됩니다.
- 실행 결과에서 사용자에게 표시된 원본 산출물과 부모가 받은 placeholder를 구분할 수 있습니다.
- 원문이 필요한 후속 작업에서만 부모 전용 조회 경로를 사용합니다.
관련 문서: 에이전트 수정