> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telloai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 외부 에이전트 쓰기

> 다른 팀의 A2A 에이전트를 도구로 등록해 Tello 에이전트가 통화 중 호출하게 해요.

## 할 수 있는 일

외부 A2A 에이전트를 **도구**로 등록하면, Tello 에이전트가 통화 중 필요할 때 그 에이전트를
호출해요. 주문 조회나 재고 확인처럼 대화 밖에 있는 판단을 다른 팀 에이전트에 맡기고, 돌아온
답을 통화에서 이어 말해요.

[외부에서 호출받기](/developer/a2a/inbound)와 방향이 반대예요. 이쪽은 **Tello가
클라이언트**가 되고 상대가 A2A 서버예요.

## 시작하기 전에

상대에게 두 가지를 받아요.

* **Agent Card URL**: `.well-known/agent-card.json`까지 포함한 **전체 주소**예요. 베이스
  주소가 아니에요.
* **인증 값**: 상대가 인증을 요구할 때만요.

상대 카드가 아래 요건을 만족해야 Tello가 붙을 수 있어요. 상대 쪽에 그대로 전달하세요.

| 카드 필드                                      | 필요한 값        | 어기면                        |
| ------------------------------------------ | ------------ | -------------------------- |
| `supportedInterfaces[0].protocolBinding`   | `"JSONRPC"`  | 맞는 전송 계층을 못 찾아 호출이 실패해요    |
| `supportedInterfaces[0].protocolVersion`   | `"1.0"`      | `0.3`이면 호환 경로로 빠져 동작이 달라져요 |
| `supportedInterfaces[0].tenant`            | `""` (빈 문자열) | 요청에 `tenant`가 실려요          |
| `securitySchemes` · `securityRequirements` | 비워 두기        | 카드가 잘못 분류될 수 있어요           |

카드에는 **스킬이 하나 이상** 있어야 해요. 등록한 도구를 호출할 때 스킬 id가 함께 넘어가요.

## 사용 방법

[도구 관리](/agents/tools)에서 `도구 추가`를 누르고 **타입**을 `A2A`로 골라요. **URL**에
Agent Card 전체 주소를 넣고, 인증 방식과 값을 채워요. **설명**은 AI가 이 도구를 언제 쓸지
판단하는 근거라 구체적으로 적어요.

등록한 뒤 [에이전트 관리](/agents/manage)의 **도구** 탭에서 에이전트에 연결해야 실제 통화에
쓰여요.

<Warning>
  A2A 도구를 등록할 때 서버가 Agent Card를 **자동으로 조회하지 않아요.** 이름·설명·인증을 직접
  입력해요. 주소가 틀려도 등록은 되고, 통화 중 호출할 때 실패해요.
</Warning>

### 인증

도구에 설정한 인증 방식이 그대로 헤더가 돼요. 이 헤더는 **Agent Card 조회와 JSON-RPC 호출
양쪽**에 붙어요.

| 인증 방식     | 붙는 헤더                              |
| --------- | ---------------------------------- |
| 없음        | (없음)                               |
| Bearer 토큰 | `Authorization: Bearer <값>`        |
| API Key   | `X-API-Key: <값>`                   |
| Basic 인증  | `Authorization: Basic <base64(값)>` |

인증 값은 저장할 때 암호화돼요. 수정할 때 비워 두면 기존 값이 유지돼요.

### 상대가 받게 되는 요청

Tello는 카드가 광고한 주소로 A2A `SendMessage`를 보내요. 메시지는 텍스트 파트 하나예요.

```json theme={null}
{
  "messageId": "<uuid>",
  "role": "ROLE_USER",
  "parts": [{ "text": "3월 2일 주문 A-1의 배송 상태를 알려줘", "mediaType": "text/plain" }],
  "metadata": { }
}
```

* **텍스트 파트 하나만 봐도 요청이 이해돼야 해요.** A2A에서 `metadata`는 선택이고 상대가
  무시해도 되는 값이라, Tello는 요청 전체를 텍스트에 담아 보내요.
* `metadata`는 게이트웨이가 한 글자도 읽지 않고 그대로 전달해요. 그 안의 규약은 양쪽이
  알아서 정하면 돼요.

### 상대가 돌려줘야 하는 응답

`Message`나 `Task` 어느 쪽으로 답해도 돼요. Tello가 답변 텍스트를 이렇게 뽑아요.

| 상대 응답                  | 읽는 곳                     |
| ---------------------- | ------------------------ |
| `Message`              | 텍스트 파트를 이어 붙여요           |
| `Task` (진행 중이거나 되물을 때) | `status.message`를 먼저 읽어요 |
| `Task` (그 밖의 상태)       | 아티팩트의 텍스트를 먼저 읽어요        |

되묻는 상태(`input-required` 등)에서 아티팩트를 먼저 읽으면 질문 대신 중간 산출물이 넘어가요.
그래서 되묻는 상태만 `status.message`를 우선해요.

<Warning>
  텍스트가 하나도 없는 응답으로 태스크가 끝나면 호출이 실패해요. 빈 응답을 돌려주지 마세요.
</Warning>

## 제한

| 항목            | 값                                      |
| ------------- | -------------------------------------- |
| 호출 타임아웃       | **15초.** Agent Card 조회부터 응답까지 전체를 포함해요 |
| Agent Card 캐시 | **60초.** 카드를 바꿔도 최대 1분은 옛 카드로 호출돼요     |
| 재시도           | **없어요.** 실패는 한 번 전달되고 끝나요              |

통화 중 호출이라 상대가 느리면 대화가 멈춰요. **상대 에이전트의 응답 시간은 15초보다 충분히
짧아야 해요.**

## 주의사항

* URL은 Agent Card **전체 주소**예요. 베이스 주소를 넣으면 카드를 찾지 못해요.
* 도구를 저장한 뒤에는 타입을 바꿀 수 없어요. 삭제하고 다시 등록해요.
* 도구를 삭제하면 그 도구를 연결한 에이전트에서도 함께 빠져요.
* 카드를 바꿨는데 반영되지 않으면 캐시 60초를 기다려요.
* 시나리오의 **Tool 호출** 노드에는 A2A 도구를 연결할 수 없어요. API Request만 돼요.
  자세한 건 [도구 관리](/agents/tools)를 보세요.

## 관련 문서

* [외부에서 호출받기](/developer/a2a/inbound)
* [도구 관리](/agents/tools)
* [에이전트 관리](/agents/manage)
* [연동 준비](/developer/overview)