Cadastro próprio de agentes

Cadastro próprio de agentes

Cadastre um agente no Agent Trust, verifique identidade e obtenha aprovação quando o modo de integração exigir.

Agent Trust permite que agentes se cadastrem e obtenham certificados PKI pelo protocolo A2A baseado em tarefas. Este tutorial cobre descoberta, cadastro, solicitação CSR, extração do certificado e autenticação mTLS.

1. Descobrir a API#

Cada implantação publica uma agent card com capacidades e esquemas de autenticação:

curl http://<gateway-host>/.well-known/agent-card.json

A card anuncia endpoints A2A, esquemas aceitos (bearer e/ou mTLS) e skills. Leia antes de criar o cliente; é a referência da implantação.

2. Registrar#

Registre agentId único e prova de identidade (chave pública):

POST /a2a/v1/register
{
  "agentId": "my-agent@corp.example",
  "displayName": "My Agent",
  "publicKeyPem": "-----BEGIN PUBLIC KEY----- …",
  "usage": "Document Q&A assistant for legal",
  "dataClassification": "Internal",
  "tags": ["legal", "qa"]
}

A identidade fica vinculada ao primeiro chamador autenticado (ou IP de origem), que passa a possuir agentId. Use ID exclusivo por agente. Sem agentId, agentes no mesmo IP são agrupados; o mesmo agentId vindo de dois hosts é rejeitado. Administradores não podem editar a prova; faça rotação registrando novamente pelo mesmo emissor.

3. Solicitar certificado CSR#

Gere localmente o par de chaves e a CSR. A chave privada nunca sai do agente:

openssl req -new -newkey rsa:2048 -nodes   -keyout agent.key -out agent.csr   -subj "/CN=my-agent@corp.example"

Envie CSR como tarefa A2A:

POST /a2a/v1/tasks/send
{
  "contextId": "enrollment-001",
  "message": {
    "role": "user",
    "parts": [{
      "kind": "file",
      "mimeType": "application/x-pem-file",
      "name": "agent.csr",
      "bytes": "<base64 of agent.csr>"
    }]
  }
}

4. Consultar tarefa#

O serviço processa a solicitação de forma assíncrona. Consulte até concluir:

GET /a2a/v1/tasks/{taskId}

O resultado esperado é completed, com a cadeia de certificados como artefato.

5. Extrair certificado#

Baixe o artefato. A cadeia contém certificado leaf e intermediários, sem raiz. Os SAN do leaf devem incluir host do gateway:

curl -o cert.pem http://<gateway-host>/a2a/v1/tasks/{taskId}/artifacts/{artifactId}

6. Autenticar com mTLS#

Configure o cliente para apresentar certificado e chave privada. Conecte-se a host listado nos SAN e valide a cadeia CA. Não compartilhe a chave privada entre agentes.

Proteja a chave privada

A chave privada permanece no agente. Se for perdida ou exposta, siga o processo de revogação e cadastre o agente novamente com novas credenciais.

Próximas leituras#

Próximas leituras