Conectar agentes pelo AI Gateway

Use o Agents Gateway para conectar agentes do A2A Protocol nas duas direções:

Chamar um agente externo

Registre um endpoint A2A remoto e invoque-o pela Responses API do AI Gateway com model: "agent/<key>".

Expor um Agent interno

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

Abra o criador de Agents

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

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.

Adicione cabeçalhos de autenticação

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

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:

cURL

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.

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:

cURL

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:

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 '{}'

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/:

cURL

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:

cURL

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:

cURL

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.

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:

cURL

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.

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."}]
      }
    }
  }'

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.

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Chamar um agente externo

Expor um Agent interno

Conectar um agente A2A externo

Registrar pelo AI Studio

Registrar pela API

Invocar um Agent externo

Saída em streaming

Continuar uma tarefa interrompida

Limites de Agents externos na v1

Expor um Agent interno por A2A

Descobrir o Agent Card

Enviar uma mensagem JSON-RPC

Usar outro transporte A2A

Limites de entrada na v1

Controles de segurança

Configuração auto-hospedada

Chamar um agente externo

Expor um Agent interno

​Conectar um agente A2A externo

​Registrar pelo AI Studio

​Registrar pela API

​Invocar um Agent externo

​Saída em streaming

​Continuar uma tarefa interrompida

​Limites de Agents externos na v1

​Expor um Agent interno por A2A

​Descobrir o Agent Card

​Enviar uma mensagem JSON-RPC

​Usar outro transporte A2A

​Limites de entrada na v1

​Controles de segurança

​Configuração auto-hospedada

Conectar um agente A2A externo

Registrar pelo AI Studio

Registrar pela API

Invocar um Agent externo

Saída em streaming

Continuar uma tarefa interrompida

Limites de Agents externos na v1

Expor um Agent interno por A2A

Descobrir o Agent Card

Enviar uma mensagem JSON-RPC

Usar outro transporte A2A

Limites de entrada na v1

Controles de segurança

Configuração auto-hospedada