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

# Conectar agentes pelo AI Gateway

> Conecte agentes A2A externos ao Toqan Router, invoque-os pela Responses API e exponha Agents internos por meio de transportes A2A.

Use o **Agents Gateway** para conectar agentes do [A2A Protocol](https://a2a-protocol.org/latest/) nas duas direções:

> [card] [Chamar um agente externo](#connect-an-external-a2a-agent)
>
> Registre um endpoint A2A remoto e invoque-o pela Responses API do **AI Gateway** com `model: "agent/<key>"`.

> [card] [Expor um Agent interno](#expose-an-internal-agent-through-a2a)
>
> Ofereça aos clientes A2A um endpoint por Agent, sustentado por um Agent interno do **Toqan Router**.

As duas direções usam chaves de API, escopo de projeto, limites de taxa e traces do **Toqan Router**.

## Conectar um agente A2A externo

O registro de um Agent externo busca e valida seu Agent Card antes de salvar a conexão. O **Toqan Router** armazena o card em cache para exibição e metadados de descoberta, enquanto cada invocação descobre o card atual antes de selecionar um transporte.

### Registrar pelo AI Studio

**1. Abra o criador de Agents**

Abra um projeto ou uma pasta no **AI Studio**, selecione , selecione **Agent** e, em seguida, **Connect External Agent**.

**2. Insira a conexão**

Insira a chave do Agent, o nome de exibição, a URL do Agent e, opcionalmente, a URL do Agent Card. Deixe a versão do protocolo e o transporte preferido em branco para selecionar automaticamente uma interface compatível do card.

**3. Adicione cabeçalhos de autenticação**

Adicione até 20 cabeçalhos de saída. Mantenha **Encrypt** ativado para credenciais e outros segredos.

**4. Crie o Agent**

Selecione **Create agent**. O registro só é concluído quando o Agent Card está acessível, é válido e anuncia o protocolo e o transporte solicitados.

Abra o Agent externo no **Agent Studio** para editar a conexão, selecionar **Test connection** ou atualizar o Agent Card em cache. Publique as alterações da conexão antes de testar, pois o teste usa a configuração armazenada. Um teste de conexão busca o card ativo sem persisti-lo. Atualizar o card substitui os metadados em cache da conexão armazenada.

### Registrar pela API

Use uma chave de API com a permissão `a2a.create`:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/agents/external \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "remote-support",
    "display_name": "Remote Support",
    "description": "Support Agent hosted outside Toqan Router",
    "path": "Default/agents",
    "agent_url": "https://agents.example.com/support",
    "headers": {
      "Authorization": {
        "value": "Bearer remote-agent-token",
        "encrypted": true
      }
    },
    "protocol_version": "1.0",
    "preferred_transport": "JSONRPC"
  }'
```

Omita `card_url` para descobrir o card a partir de `agent_url`. Omita `protocol_version` e `preferred_transport` para selecionar a primeira interface compatível anunciada pelo card. O `protocol_version` aceito é `1.0` ou `0.3`; `1.0` combina com `JSONRPC`, `HTTP+JSON` ou `GRPC`, e `0.3` combina com `JSONRPC`.

`card_url` pode estar em outra origem, mas as interfaces anunciadas pelo card não. Toda invocação HTTP vai para a origem de `agent_url`, e uma interface gRPC precisa ao menos compartilhar o mesmo host, porque um listener gRPC usa sua própria porta. O registro é recusado quando o card não anuncia nenhuma interface nessa origem.

Um Agent do **Toqan Router** pode chamar um Agent externo adicionando a chave dele a `team_of_agents` e habilitando a tool `call_sub_agent`. As chamadas carregam `X-Orq-A2A-Hops`; quando uma cadeia atinge cinco saltos, a próxima chamada é rejeitada como um loop de autochamada, com uma mensagem informando que a solicitação já passou por cinco agents A2A.

> [!NOTE]
>
> Os valores de cabeçalhos criptografados são criptografados em repouso e retornados como strings vazias nas operações de leitura. Ao atualizar um cabeçalho criptografado existente, envie um valor vazio para preservar o segredo armazenado. Envie o mapa `headers` completo desejado, pois a atualização substitui o mapa.

Gerencie Agents externos com estes endpoints:

| Operação | Endpoint | Permissão |
| - | - | - |
| Criar | `POST /v2/agents/external` | `a2a.create` |
| Listar | `GET /v2/agents/external` | `a2a.list` |
| Consultar por chave ou ID | `GET /v2/agents/external/{agent_key}` | `a2a.view` |
| Atualizar | `PATCH /v2/agents/external/{agent_key}` | `a2a.update` |
| Excluir | `DELETE /v2/agents/external/{agent_key}` | `a2a.delete` |
| Atualizar o card em cache | `POST /v2/agents/external/{agent_key}:refreshCard` | `a2a.update` |
| Testar a conexão armazenada | `POST /v2/agents/external/{agent_key}:testConnection` | `a2a.view` |

As solicitações de listagem aceitam `limit`, `starting_after` e `ending_before`. Não envie os dois campos de cursor na mesma solicitação.

Atualize uma conexão e valide-a novamente:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH https://router.toqan.ai/eu/v2/agents/external/remote-support \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_url": "https://agents.example.com/support/v2",
    "protocol_version": "1.0",
    "preferred_transport": "HTTP+JSON"
  }'
```

Teste ou atualize a conexão salva:

```bash Test connection theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/agents/external/remote-support:testConnection \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash Refresh card theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/agents/external/remote-support:refreshCard \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Invocar um Agent externo

Chame um Agent externo registrado pela Responses API padrão. Mantenha o prefixo de modelo `agent/`:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/remote-support",
    "input": "Summarize the open support cases."
  }'
```

O **AI Gateway** mapeia texto, URLs de imagens, URLs de arquivos e entradas de arquivos em base64 para partes de mensagem A2A. Artefatos de texto remotos se tornam mensagens de assistant da Responses API. Partes de dados A2A estruturadas se tornam texto JSON. O uso de tokens é informado como zero, pois o Agent remoto não fornece o uso de modelos do **Toqan Router**.

### Saída em streaming

Defina `stream: true` para receber server-sent events padrão da Responses API:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -N -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/remote-support",
    "input": "Summarize the open support cases.",
    "stream": true
  }'
```

Quando o Agent Card ativo anuncia streaming, o gateway mapeia as atualizações de artefatos e de status A2A para eventos da Responses API. Quando o card não anuncia streaming, o gateway conclui uma chamada A2A bloqueante e emite um stream sintético compatível da Responses API.

### Continuar uma tarefa interrompida

Quando uma tarefa remota retorna `input_required` ou `auth_required`, a Responses API retorna uma resposta incompleta. Passe o ID dessa resposta como `previous_response_id` para continuar no mesmo contexto A2A:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent/remote-support",
    "previous_response_id": "resp_01K6D8QESESZ6SAXQPJPFQXPFT",
    "input": "Use the enterprise account."
  }'
```

O gateway mantém privados os identificadores do contexto e da tarefa remotos. Armazene a resposta do **Toqan Router** mantendo o armazenamento de respostas ativado antes de usar `previous_response_id`.

### Limites de Agents externos na v1

A execução externa na v1 usa um contrato restrito:

* O mapeamento A2A remoto oferece suporte a `input`, `stream` e `previous_response_id`. Os controles gerenciados pelo gateway, como o armazenamento de respostas, continuam se aplicando.
* Entrada aceita: uma string ou mensagens de usuário contendo texto, URLs de imagens, URLs de arquivos ou dados de arquivos em base64.
* Os controles de solicitação não compatíveis incluem `tools` e `tool_choice` fornecidos pelo chamador, novas tentativas, fallbacks, balanceamento de carga, parâmetros de amostragem, modo em segundo plano e formatação de saída diferente da padrão.
* `instructions` não são aplicadas ao Agent remoto. Configure o comportamento dele no endpoint remoto.
* Partes de saída de arquivos remotos não são mapeadas na v1. Retorne texto ou partes de dados estruturados.
* Tarefas A2A com falha ou rejeitadas são mapeadas para Responses com falha. Tarefas canceladas são mapeadas para Responses canceladas. Tarefas que exigem entrada ou autenticação são mapeadas para Responses incompletas.

## Expor um Agent interno por A2A

Todo Agent interno do **Toqan Router** tem um endpoint A2A. Abra o Agent no **Agent Studio**, expanda **Expose via A2A** e copie a URL do Agent, a URL do Agent Card e a permissão necessária `a2a.execute`.

> [!WARNING]
>
> Não use o registro de um Agent externo como endpoint de entrada. Apenas Agents internos do **Toqan Router** podem ser expostos pelo gateway A2A.

### Descobrir o Agent Card

Busque o caminho padrão do Agent Card com uma chave de API do **Toqan Router** com escopo definido:

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://router.toqan.ai/eu/v2/a2a/my-agent/.well-known/agent-card.json \
  -H "Authorization: Bearer $TOQAN_API_KEY"
```

O card anuncia as interfaces A2A 1.0 JSON-RPC, HTTP + JSON e gRPC, entrada e saída de texto, suporte a streaming, autenticação bearer e as skills publicadas do Agent.

### Enviar uma mensagem JSON-RPC

Quando `A2A-Version` está ausente, o endpoint base usa por padrão o contrato de compatibilidade A2A 0.3. Defina `A2A-Version: 1.0` para usar o contrato A2A 1.0.

```bash A2A 1.0 theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/a2a/my-agent \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "A2A-Version: 1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "message-1",
        "role": "ROLE_USER",
        "parts": [{"text": "Summarize the account."}]
      }
    }
  }'
```

```bash A2A 0.3 compatibility theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v2/a2a/my-agent \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "A2A-Version: 0.3" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "request-1",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "message-1",
        "role": "user",
        "parts": [{"kind": "text", "text": "Summarize the account."}]
      }
    }
  }'
```

Valores de `A2A-Version` não compatíveis retornam `400`.

### Usar outro transporte A2A

| Binding | Endpoint |
| - | - |
| JSON-RPC | `POST /v2/a2a/{agent_key}` |
| HTTP + JSON | `/v2/a2a/{agent_key}/message:send`, `/message:stream`, `/tasks` e `/tasks/{task_id}` |
| Connect ou gRPC-Web | `/v2/a2a/{agent_key}/lf.a2a.v1.A2AService/{Method}` |
| gRPC nativo | `lf.a2a.v1.A2AService` com a chave do Agent no campo `tenant` da solicitação |

Envie a chave de API como `Authorization: Bearer <token>` para HTTP, Connect e metadados gRPC. A chave de API precisa incluir `a2a.execute` e ter acesso ao projeto do Agent. Autenticação, escopo de projeto, cota e limites de taxa são aplicados antes da execução.

### Limites de entrada na v1

* A execução de mensagens bloqueante e em streaming é compatível.
* A consulta e a listagem de tarefas são compatíveis para Responses armazenadas que pertencem ao Agent roteado.
* A execução não bloqueante não é compatível.
* O cancelamento e as assinaturas de tarefas não são compatíveis.
* A configuração de notificações push e os Agent Cards estendidos não são compatíveis.
* Os Agent Cards anunciam `streaming: true` e `pushNotifications: false`.

## Controles de segurança

O registro e a execução de Agents externos aplicam os seguintes controles:

* HTTPS é obrigatório para as URLs do Agent, do card e das interfaces anunciadas.
* Destinos de rede loopback, privados, link-local, de metadados e unique-local são bloqueados antes da conexão, incluindo formas numéricas alternativas de IP e respostas DNS que resolvem para faixas bloqueadas.
* Redirecionamentos não são seguidos.
* O tamanho do Agent Card e o tempo de busca são limitados.
* Cabeçalhos criptografados são mascarados nas fronteiras da API. Os cabeçalhos de trace em tempo de execução são gerenciados pelo **Toqan Router** e não podem ser substituídos por cabeçalhos de conexão armazenados.
* Os cabeçalhos armazenados são enviados apenas para interfaces na origem configurada do agente ou do card. As demais interfaces anunciadas são validadas e excluídas antes da seleção do transporte.
* Chaves de API restritas a projetos só podem gerenciar, invocar ou expor Agents em projetos permitidos.

HTTP simples está disponível apenas para desenvolvimento em localhost quando `ENVIRONMENT` é `local` ou `development` e `A2A_ALLOW_HTTP_LOCALHOST` é `true`. Mantenha essa configuração desativada em ambientes implantados.

## Configuração auto-hospedada

| Variável | Serviço | Padrão | Finalidade |
| - | - | - | - |
| `A2A_PUBLIC_BASE_URL` | Responses API | `http://localhost:<PORT>` localmente; caso contrário, obrigatório | Base HTTP ou HTTPS absoluta usada nos Agent Cards internos. Fora de ambientes locais, a entrada A2A é desativada quando não está definida |
| `A2A_GRPC_PORT` | Responses API | `9092` | Porta do listener gRPC A2A nativo |
| `A2A_GRPC_PUBLIC_URL` | Responses API | não definido | Destino público de conexão gRPC nativo anunciado nos Agent Cards internos; quando não está definido, o card omite a interface gRPC. Use `host:port`, `dns:///host:port` ou `passthrough:///host:port` |
| `A2A_ALLOW_HTTP_LOCALHOST` | Platform API e Responses API | `false` | Permite HTTP simples para localhost apenas em ambientes locais ou de desenvolvimento |
| `A2A_CARD_TIMEOUT_SECONDS` | Platform API e Responses API | `10` | Tempo limite de busca do Agent Card |
| `A2A_MAX_CARD_BYTES` | Platform API e Responses API | `1048576` | Tamanho máximo da resposta do Agent Card |
| `A2A_MAX_HEADERS` | Platform API | `20` | Número máximo de cabeçalhos de conexão armazenados para um agente externo |
| `A2A_INVOKE_TIMEOUT_SECONDS` | Responses API | `300` | Tempo limite da invocação A2A externa bloqueante |
| `A2A_STREAM_IDLE_TIMEOUT_SECONDS` | Responses API | `300` | Intervalo máximo de inatividade durante a leitura de um stream A2A externo |

Defina todas as durações, limites de bytes e limites de cabeçalhos como inteiros positivos. Em ambientes implantados, defina `A2A_PUBLIC_BASE_URL` como a origem HTTP pública do **AI Gateway** e `A2A_GRPC_PUBLIC_URL` como um destino gRPC nativo acessível externamente, como `agents.example.com:443` ou `dns:///agents.example.com:443`. Não inclua `http://` nem `https://` no destino gRPC; os clientes configuram a segurança de transporte gRPC separadamente. Para gRPC autenticado entre instâncias da plataforma, exponha o destino pelo mesmo host e porta HTTPS públicos da URL configurada do agente ou do card, para que os cabeçalhos armazenados vinculados à origem continuem válidos para essa interface.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.