Autorregistro de agentes

Autorregistro de agentes

Incorpore un agente mediante autorregistro, pruebe su identidad y obtenga aprobación cuando el modo lo requiera.

Agent Trust permite que los agentes de IA se incorporen y obtengan certificados PKI mediante el protocolo A2A basado en tareas. Este tutorial cubre descubrimiento, registro, solicitud de certificado con CSR, extracción del certificado y autenticación mTLS.

1. Descubrir la API#

Cada despliegue de AI-FW publica una agent card con sus capacidades y esquemas de autenticación:

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

La tarjeta anuncia endpoints A2A, esquemas admitidos (bearer y/o mTLS) y skills. Léala antes de crear el cliente, es la referencia del despliegue.

2. Registrarse#

Registre un agentId único y una prueba de identidad (clave 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"]
}

La identidad se vincula al primer llamador autenticado (o IP de origen), que posee ese agentId. Use un ID único por agente; compartir IP sin agentId combina identidades, y el mismo agentId desde dos hosts se rechaza. La prueba de identidad no se puede editar por administración; rótela registrando de nuevo desde el mismo emisor.

3. Solicitar certificado con CSR#

Genere localmente el par de claves y la CSR. La clave privada nunca sale del agente:

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

Envíe la CSR como tarea 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 la tarea#

El servicio procesa la solicitud de forma asíncrona. Consulte el estado hasta que termine:

GET /a2a/v1/tasks/{taskId}

Se espera completed con la cadena de certificados emitida como artefacto.

5. Extraer el certificado#

Descargue el artefacto. La cadena contiene certificado leaf e intermedios, sin raíz; los SAN del leaf deben incluir el host gateway:

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

6. Autenticarse con mTLS#

Conserve la clave privada junto al certificado y configure el cliente para presentar ambos al gateway. Use el host que aparece en el SAN del certificado y valide la cadena de CA. No exporte la clave privada ni la comparta con otros agentes.

Proteja la clave privada

La clave privada se genera y permanece en el agente. Si se pierde o queda expuesta, siga el proceso de revocación y vuelva a registrar el agente con nuevas credenciales.

Dónde continuar#

Dónde continuar