A2A 연결 가이드
A2A는 서로 다른 플랫폼의 Agent를 연결하는 데 사용됩니다. 외부 플랫폼에서 AE Agent를 호출할 수도 있고, AE에 원격 Agent를 연결하여 현재 Agent가 작업을 위임하고 결과를 정리하도록 할 수도 있습니다.
기능 개요 및 준비 사항
| 연결 방향 | 활용 상황 | 설정 위치 |
|---|---|---|
| 외부 플랫폼에서 AE Agent 호출 | A2A를 지원하는 다른 플랫폼에서 AE Agent의 기능을 사용합니다. | AE의 Agent 페이지에서 Agent Card URL을 가져온 후, 호출 기능이 있는 외부 Agent의 대화 또는 A2A 설정 페이지를 통해 연결합니다. |
| AE에서 원격 Agent 호출 | 현재 Agent가 특정 작업을 원격 Agent에 위임하여 처리하도록 합니다. | MCP 페이지에서 “A2A 원격 Agent”를 추가한 후 대상 AE Agent에 연결합니다. |
Agent Card는 Agent의 이름, 기능, 프로토콜, 호출 URL을 설명하는 정보 파일입니다. 연결할 때 전체 Agent Card URL을 입력하고, 호출자가 해당 URL과 Card에 명시된 서비스 URL에 접근할 수 있는지 확인해야 합니다.
현재 연결하려면 A2A 1.0 JSON-RPC와 호환되는 클라이언트 또는 원격 서비스를 사용해야 합니다. AE Agent를 호출할 때는 해당 Agent에 접근할 권한이 있는 유효한 TE access token을 준비하고 대상 Agent를 활성화해야 합니다. 다른 플랫폼의 원격 Agent를 연결할 때는 해당 원격 서비스에서 제공하는 Bearer Token을 준비해야 합니다.
AE Agent를 외부 플랫폼에 연결
- Agent 페이지로 이동합니다. 기본 Agent를 호출하려면 페이지 상단의 A2A 1.0 지원 · 연결 방법 보기를 클릭합니다. 특정 Agent를 호출하려면 해당 Agent의 상세를 열고 외부 호출(A2A) 영역을 찾습니다.
- URL 복사를 클릭하여 해당 Agent의 Card URL을 가져옵니다. 기본 Agent와 특정 Agent의 URL은 서로 다르므로, 실제로 호출할 Agent에 표시된 URL을 복사해야 합니다.
- HTTP 요청을 실행하고 A2A 1.0 프로토콜에 따라 호출할 수 있는 외부 Agent의 대화에서 Card URL과 작업을 전달합니다. 플랫폼에서 제공하는 A2A 연결 설정 페이지를 사용할 수도 있습니다. Card를 읽는 요청과 이후 작업 요청에는 모두 다음 요청 헤더가 필요합니다.
Authorization: Bearer <TE_ACCESS_TOKEN>
A2A-Version: 1.0
<TE_ACCESS_TOKEN>을 유효한 TE access token으로 바꿉니다. 이 토큰은 기존 인증 방식을 통해 가져오며, A2A 연결 창에서는 토큰을 생성하지 않습니다. Card URL을 복사하는 것만으로는 인증을 완료할 수 없으며, 위 요청 헤더를 브라우저 Cookie로 대체할 수도 없습니다.
대화에서 작업을 시작할 때는 다음 지시문과 함께 방금 복사한 전체 Card URL을 전달할 수 있습니다.
이 Agent Card를 읽고, 설정된 TE 액세스 자격 증명을 사용하여 A2A 1.0 프로토콜에 따라 해당 Agent를 호출해 다음 작업을 완료해 주세요. “캠페인이 이번 금요일에 시자됩니다. 많은 참여 바랍니다.”를 오타가 없는 문구로 수정해 주세요.
외부 Agent는 실제로 Card를 읽고 프로토콜 요청을 전송해야 합니다. 일반 채팅 창에 링크와 텍스트를 전달했다고 해서 A2A 연결이 설정된 것은 아닙니다. 플랫폼에 요청을 실행할 수 있는 도구가 없으면 해당 플랫폼에서 지원하는 A2A 연결 방식을 사용해야 합니다.
처음 사용할 때는 간단한 텍스트 작업으로 먼저 검증합니다. 실행 중인 작업이 반환되면 작업 상태를 계속 조회합니다. 추가 입력이 필요한 경우 원래 작업에서 계속 답변합니다.
AE 연결 창에서 Card 내용 보기를 클릭하면 프로토콜, 입력 및 출력 형식, 전체 JSON을 확인하고 JSON을 복사할 수 있습니다. 이 미리보기는 현재 로그인한 사용자를 기준으로 생성됩니다. 외부 플랫폼에서 다른 자격 증명을 사용하는 경우 해당 자격 증명으로 실제 읽어 온 Card를 기준으로 해야 합니다.
외부 호출에는 토큰 소유 사용자의 권한이 적용되며, 해당 사용자가 볼 수 있고 활성화된 Agent에만 접근할 수 있습니다. 연결 URL은 외부 플랫폼이 속한 네트워크에서도 접근할 수 있어야 합니다.
MCP를 통해 A2A 원격 Agent 연결
- MCP 페이지로 이동하여 MCP 추가를 클릭합니다.
- 페이지에서 제공하는 옵션에 따라 개인 MCP를 선택합니다.
- 연결 방식 선택에서 A2A 원격 Agent를 선택하고 다음 설정을 입력합니다.
| 구성 항목 | 입력 설명 |
|---|---|
| 서비스 이름(필수) | copy_editor와 같이 알아보기 쉬운 이름을 입력합니다. 영문자로 시작해야 하며 영문자, 숫자, 밑줄, 하이픈만 사용할 수 있습니다. |
| Agent Card URL(필수) | 원격 Agent의 전체 A2A 1.0 Card URL을 입력합니다. 다른 AE Agent를 연결하는 경우 해당 Agent의 연결 창에서 복사한 URL을 사용합니다. 여기에 입력하는 것은 일반 MCP 서비스 URL이 아닌 Card URL입니다. |
| Bearer Token(필수) | 원격 Agent에 접근할 권한이 있는 토큰을 입력합니다. Bearer 접두사 없이 토큰 자체만 입력합니다. AE Agent를 연결하는 경우 유효한 TE access token을 사용합니다. |
| 추가 설정(선택) | 필요에 따라 표시 이름과 설명을 추가하여 사용자가 원격 Agent의 용도를 알아볼 수 있도록 합니다. |
| 이 주소의 사설 네트워크 또는 HTTP 접근 허용(선택) | 기본적으로 꺼져 있습니다. 사설 네트워크 또는 HTTP URL에 접근해야 하는 경우에만 켜며, 현재 URL의 호스트와 포트만 허용합니다. HTTP는 자격 증명과 데이터를 평문으로 전송하므로 HTTPS를 우선 사용하는 것이 좋습니다. |
| 원격 실행 모델(선택) | URL과 토큰을 입력한 후 모델 목록 불러오기를 클릭하고, 원격에서 사용을 허용하는 모델을 선택합니다. 선택하지 않으면 원격 기본 동작을 유지합니다. |
원격 모델 목록은 현재 연결 자격 증명의 접근 권한에 따라 달라집니다. 원격 Agent가 모델 선택을 지원하지 않으면 기본 동작을 유지하면 됩니다. 선택한 모델을 더 이상 사용할 수 없으면 목록을 다시 불러와 사용 가능한 모델을 선택하거나, 기본 동작으로 되돌린 후 저장해야 합니다.
입력을 완료한 후 MCP 저장을 클릭합니다. 플랫폼은 자격 증명을 포함하여 Agent Card를 읽고 호환되는 A2A 1.0 JSON-RPC 인터페이스를 제공하는지 확인합니다. 토큰은 암호화되어 저장되며, 서버에서 원격 Agent에 접근할 때 사용됩니다.
Agent에 연결하고 호출 검증
- Agent 페이지에서 Agent를 생성하거나, 관리 권한이 있는 Agent를 편집합니다.
- MCP 서비스 설정 단계에서 방금 생성한 A2A 원격 Agent 연결을 찾아 선택한 후 Agent를 저장합니다. 해당 연결이 활성화되어 있는지 확인합니다.
- 해당 Agent로 새 대화를 시작하고, 요청에서 어떤 원격 Agent에 어떤 작업을 위임할지 명확히 설명합니다.
- 실행 과정을 확인하여 원격 Agent의 도구 호출이 발생하고 결과가 반환되는지 확인합니다. 원격에서 추가 정보가 필요한 경우 안내에 따라 계속 답변합니다.
예를 들어 연결한 원격 Agent가 문구 교정용이라면 다음과 같이 입력할 수 있습니다.
문구 교정 Agent를 호출하여 다음 문장의 오타를 확인하고 수정 이유를 설명해 주세요. 캠페인이 이번 금요일에 시자됩니다. 많은 참여 바랍니다.
Agent의 지시문에 원격 Agent가 처리할 작업과 기대하는 반환 내용을 설명하면 적절한 시점에 작업을 위임하는 데 도움이 됩니다. 연결을 저장하거나 도구 목록을 불러온 것은 해당 설정 또는 도구 검색 단계가 성공했다는 의미일 뿐입니다. 처음 사용할 때는 실제 위임 작업을 한 번 실행하여 결과를 검증해야 합니다.
자주 묻는 질문 및 제한 사항
| 증상 | 확인 및 처리 방법 |
|---|---|
| Agent Card를 읽을 수 없거나 연결 저장 실패 | 전체 Card URL을 입력했는지, 토큰이 유효한지, 서비스가 A2A 1.0 JSON-RPC 인터페이스를 제공하는지 확인합니다. 플랫폼에서 Card와 Card에 명시된 호출 URL에 접근할 수 있는지 확인합니다. 사설 네트워크 또는 HTTP URL을 사용하는 경우 해당 접근 허용 스위치를 확인합니다. |
| 외부 플랫폼에서 AE Card를 읽거나 작업을 호출할 때 인증 실패 | Card를 읽는 요청과 작업 요청 모두에 Authorization 및 A2A-Version: 1.0 요청 헤더가 포함되어 있는지 확인합니다. 토큰 소유 사용자가 해당 Agent에 접근할 권한이 있는지, Agent가 활성화되어 있는지도 확인합니다. |
| 모델 목록을 읽을 수 없거나 선택한 모델을 사용할 수 없음 | URL, 토큰, 원격 모델 선택 기능을 확인합니다. 목록을 다시 불러와 현재 자격 증명으로 사용할 수 있는 모델을 선택합니다. 모델을 지정하지 않으려면 원격 기본 동작 유지를 선택합니다. |
| A2A Bearer Token을 저장할 수 없다는 메시지가 표시됨 | 서비스에 자격 증명 암호화가 설정되지 않았다는 메시지가 표시되면 관리자에게 서비스 설정을 완료하도록 요청한 후 다시 시도합니다. |
| 연결은 저장되었지만 Agent가 원격을 호출하지 않음 | 연결이 활성화되어 있고 대상 Agent의 MCP 서비스에서 선택되어 있는지 확인합니다. 새 대화에서 위임할 작업을 명확히 지정합니다. 호출은 발생했지만 실행에 실패한 경우 반환된 안내에 따라 원격 서비스, 권한, 네트워크를 확인합니다. 필요한 경우 관리자에게 실행 환경의 연결 가능 여부를 확인하도록 요청합니다. |
현재 연결은 A2A 1.0 JSON-RPC와 Bearer 인증을 지원하며 A2A 0.3과 호환되지 않습니다. 일반 MCP, REST 또는 gRPC의 연결 설정을 그대로 적용할 수 없습니다. 첨부 파일 전송, 스트리밍 응답 등의 기능은 양쪽에서 실제로 지원하고 명시한 기능에 따라 달라집니다. 먼저 텍스트 작업으로 연결을 검증하는 것이 좋습니다.

