양방향 에이전트 간 통신 (A2A)

EKB는 개방형 Agent2Agent (A2A) 프로토콜을 양방향으로 지원합니다:

방향	의미	설정 위치
아웃바운드	내 EKB 에이전트가 HTTPS로 외부 A2A 에이전트를 호출	에이전트 → Toolkits → Agent Communication → 대상 타입 External (A2A)
인바운드	EKB 외부 시스템이 인증된 A2A 엔드포인트를 통해 내 에이전트를 호출	에이전드 → External Access 탭 (에이전트 카드 URL + 접근 키)

태스크는 대화 전반에 걸쳐 유지되며 에이전트를 소유한 프로젝트에 격리됩니다.

이것은 EKB 내부의 다른 에이전트를 호출하는 것(같은 툴킷, 대상 타입 In EKB)과는 별개입니다. 내부 멀티 에이전트 패턴은 Agent Communication Toolkit을 참고하세요.

전제 조건

방향	필요한 것
아웃바운드	에이전트 편집 권한; Agent Communication 툴킷 활성화; 파트너의 HTTPS A2A 기본 URL (필요 시 베어러 토큰)
인바운드	에이전트 편집 권한; External Access 키 발급 능력; 파트너가 베어러 토큰으로 HTTPS를 통해 내 API 호스트를 호출할 수 있는 환경

아웃바운드: 외부 A2A 에이전트 호출

파트너나 제3자 시스템이 내 EKB 에이전트가 위임하고 싶은 A2A 호환 에이전트를 노출할 때 사용합니다.

구성

에이전트를 엽니다 → Toolkits → Agent Communication을 활성화합니다.
헬퍼 에이전트 구성을 추가합니다(UI에서는 이를 헬퍼 또는 대상 에이전트 카드라고 부를 수 있음).
Where this agent lives에서 **External (A2A)**를 선택합니다(In EKB가 아님).
외부 에이전트의 기본 URL을 입력합니다. HTTPS가 필수입니다.
- 기본 URL 또는 /.well-known/agent-card.json으로 끝나는 전체 에이전트 카드 URL을 붙여넣을 수 있습니다 — 둘 다 허용됩니다.
필요한 경우 파트너의 API 키 / 베어러 토큰을 제공합니다. 공유 구성에 리터럴을 붙여넣는 대신 **볼트(vault)**에 저장하는 것을 선호하세요.
Verify Connection을 클릭하여 저장전에 EKB가 에이전트 카드를 가져와 이름, 설명, 스킬, 도달 가능성을 확인하게 하세요.
에이전트 구성을 저장합니다.

런타임에 내 에이전트는 프로젝트 내 헬퍼에게 넘기는 것과 같은 방식으로 그 외부 에이전트에게 작업을 넘길 수 있습니다 — 컨텍스트는 A2A로 전달됩니다.

아웃바운드 필드 체크리스트

설정	참고
대상 타입	External (A2A)여야 함
URL	HTTPS만; `http://`는 거부됨
인증	파트너에 따라 선택적 베어러 / API 키
Verify Connection	저장 전에 사용; 실패는 대개 DNS, TLS, SSRF 차단 또는 비A2A URL을 의미

요건 및 제한

외부 대상은 HTTPS를 사용해야 합니다.
디스커버리와 호출은 EKB 백엔드를 통해 이루어집니다(SSRF 보호 포함). 검증된 URL은 백엔드가 실제로 도달할 수 있는 URL입니다 — 노트북에서만 호스트되는 호스트네임은 프로덕션에서 작동하지 않습니다.
파트너 토큰은 다른 모든 시크릿처럼 취급하세요: 붙여넣은 리터럴보다 복트 참조를 선호합니다.

인바운드: 다른 시스템이 내 EKB 에이전트를 호출하게 하기

다른 제품, 파트너 에이전트, 사용자 정의 A2A 클라이언트가 내 EKB 에이전트 중 하나를 호출해야 할 때 사용합니다.

에이전트 카드 URL

에이전드의 External Access 탭에서 다음과 같은 형태의 Agent Card URL을 얻습니다:

https://<your-api-host>/a2a/agents/<agent_id>/.well-known/agent-card.json

이것을 상대방에게 전달하세요. 그들의 A2A 클라이언트가 카드를 읽어 에이전트가 무엇을 할 수 있고 요청을 어디로 보내야 하는지 파악합니다.

카드 URL만 공유하는 것으로는 접근이 부여되지 않습니다 — 호출자는 여전히 내가 발급한 키가 필요합니다.

카드는 에이전트의 이름, 설명, 스킬(기본 채팅 스킬), JSON-RPC 엔드포인트를 기술합니다. 이 엔드포인트에 대한 스트리밍은 광고되지 않습니다.

접근 키

에이전트를 엽니다 → External Access.
나중에 키를 구분할 수 있도록 키에 레이블을 붙입니다(예: Acme partner integration).
키를 생성하고 토큰을 즉시 복사하세요 — 해시만 저장되며 시크릿은 한 번만 표시됩니다.
파트너에게 전달합니다:
- Agent Card URL
- 베어러 토큰
더 이상 필요 없는 키는 폐기하세요. 시크릿을 잃으면 폐기하고 새 키를 발급합니다(이전 평문은 검색할 수 없음).

키는 해당 에이전트에 한정됩니다. 에이전트 A에 대한 유효한 토큰은 에이전트 B에 사용할 수 없습니다.

외부 호출자가 접하는 것

리소스	메서드 / 경로	목적
에이전트 카드	`GET /a2a/agents/{agent_id}/.well-known/agent-card.json`	디스커버리 (인증됨)
JSON-RPC	`POST /a2a/agents/{agent_id}/rpc`	`message/send` 및 관련 A2A 메서드

다음으로 인증합니다:

Authorization: Bearer <access-key>

파트너 체크리스트 (인바운드)

베어러 토큰으로 에이전트 카드를 가져옵니다.
카드에서 광고된 JSON-RPC 엔드포인트를 읽습니다.
같은 베어러 토큰으로 A2A JSON-RPC 요청을 보냅니다.
태스크가 에이전트의 소유 프로젝트에 계속 연결됨을 예상합니다(아래 참조).

프로젝트 격리

인바운드 A2A 실행은 에이전트를 소유한 프로젝트에서 실행됩니다. 여러 프로젝트에 존재하는 템플릿 에이전트는 호출자 간에 공유되지 않습니다: 각 호출은 올바른 프로젝트 컨텍스트에 고정되어 한 테넌트의 대화가 다른 테넌트로 새어 나가지 않습니다.

전형적인 설정

목표	방향	설정
EKB "매니저" 에이전트가 파트너의 전문 에이전트에게 질문	아웃바운드	Agent Communication → External (A2A) + Verify Connection
파트너 제품이 내 지원 에이전트와 채팅	인바운드	External Access 키 + 카드 URL
내 EKB 에이전트 둘이 협업	내부 (A2A 아님)	Agent Communication → In EKB

문제 해결

증상	확인할 사항
Verify Connection 실패	HTTPS URL; 파트너 카드 경로; EKB 백엔드의 네트워크 경로; 필요 시 베어러 토큰
`http://` 거부	HTTPS 사용
파트너가 401 수신	베어러 누락/잘못됨; 폐기된 키; 다른 에이전트용으로 발급된 키
파트너가 브라우저에서 카드 URL은 읽지만 호출 불가	카드만으로는 부족 — `Authorization: Bearer …`를 보내야 함
인바운드 호출의 잘못된 프로젝트 데이터	에이전트를 소유하는 프로젝트 확인; 격리는 소유 프로젝트 단위
Public Chatbot / Interfaces와 혼동	A2A는 에이전트-프로토콜 통합이지 웹사이트 위젯이나 게시된 인터페이스 URL이 아님

전제 조건​

아웃바운드: 외부 A2A 에이전트 호출​

구성​

아웃바운드 필드 체크리스트​

요건 및 제한​

인바운드: 다른 시스템이 내 EKB 에이전트를 호출하게 하기​

에이전트 카드 URL​

접근 키​

외부 호출자가 접하는 것​

파트너 체크리스트 (인바운드)​

프로젝트 격리​

전형적인 설정​

문제 해결​

관련 문서​