Agentes

An Agente es un sistema de IA que ejecutas, un bot de apoyo, un asistente de codificación, un flujo de trabajo autónomo. Task Guard, Govern y Secure aceptan una identidad de agente para que las tareas, decisiones e incidentes puedan atribuirse al agente adecuado.

Es bueno saberlo. Los agentes registrados son opcionales. Puedes llamar a cada punto final con solo un texto libre agent_name. Registrar un agente le da un establo agent_id y informes más ricos — pero nunca es un requisito previo para usar la API.

Registrado vs. no registrado#

La tarea de Task Guard comienza y cada llamada de Govern y Secure acepta dos campos de identidad opcionales:

Usted puede enviar, ambos, o ninguno. Pasando agent_id vincula la actividad con el agente registrado; agent_name es una etiqueta legible por humanos. Empieza con agent_name, y cambiar a agent_id una vez que te registres.

Cómo Govern resuelve el alcance de la política#

Para una evaluación normal de políticas activas, agent_id es opcional. Govern todavía evalúa la acción cuando una solicitud de REST o MCP envía sólo agent_name.

Paso agent_id cuando se puede; utilizar agent_name cuando un agente no está registrado todavía o cuando un cliente de MCP no tiene una identificación registrada. Si pasas policy_ids o policy_group_ids en un puesto de control, Maetra evalúa las políticas que seleccionó explícitamente.

Cuándo registrarse

• Quieres tableros de control, hallazgos y pistas de auditoría.
• Quieres incluir reglas o políticas a agentes específicos.
• Estás a bordo de un agente para la gobernanza formal.

Cuando no necesitas

• Estás integrándote rápidamente o prototipando.
• El callador es un script one-off o una superficie de producto, no un agente rastreado.

Registrar un agente#

Agentes registrados en el panel bajo Discover → Registro de agentes → Agente de registro. Sólo un nombre es necesario; todo lo demás (propietario, medio ambiente, marco, nivel de autonomía, herramientas) es contexto opcional. A salvo, Maetra asigna el agent_id pasa a la API.

Agentes de lista#

GET /v1/agents — devuelve a los agentes en su espacio de trabajo, el más nuevo primero, con una proyección pública mínima. Requiere el discover:agents:read alcance.

Parámetros de consulta

curl "https://api.maetra.io/v1/agents?limit=20" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Respuesta

{
  "agents": [
    {
      "id": "agt_5Ab2",
      "name": "billing-bot",
      "description": "Handles customer refunds.",
      "status": "registered",
      "autonomy_level": "L3",
      "risk_level": "medium",
      "environment": "production",
      "created_at": "2026-07-01T09:12:00.000Z",
      "updated_at": "2026-07-06T22:04:00.000Z"
    }
  ]
}