Seguridad e Observabilidad de IA — API Directa

Para la mayoría de las integraciones externas, las llamadas a /chat/completions son suficientes: la moderación conforme a la política del equipo y el registro de trazas en Observabilidad ocurren automáticamente dentro del pipeline del Gateway. Consulte Integración con AI Gateway.

Esta página cubre la ruta avanzada: agentes externos que gestionan una traza de varios pasos, aplicaciones que moderan contenido que no es LLM y plataformas que necesitan registrar agentes o enviar sus propios spans a Observabilidad.

---

Cuándo es suficiente la ruta predeterminada

El Gateway ya gestiona tanto Security como Observabilidad de forma integrada cuando:

• El equipo tiene Enable Security activado y una política asignada en la interfaz del Gateway bajo Teams.
• El equipo tiene Enable Observability activado en la misma vista.

Si su aplicación solo realiza llamadas a LLMs y ambos controles están activados, no necesita nada de esta página. Envíe x-beak-agent-id (y opcionalmente x-beak-user-id, x-beak-session-id) en cada solicitud a /chat/completions y las trazas aparecerán bajo ese agente en Observabilidad.

Recurra a las API directas descritas a continuación solo para los patrones indicados a continuación.

---

Patrón 1 — Gestionar la traza

Utilice este patrón cuando su agente ejecuta un bucle de varios pasos (planificador → herramientas → reflexión → llamada LLM → ...) y desea ver la secuencia completa en una única traza, con las llamadas LLM como spans anidados en lugar de trazas independientes de un solo span.

Generar un id de traza y un span raíz

Al inicio de la ejecución del agente, genere un trace_id. Trate la propia ejecución del agente como el span raíz y asígnele un span_id.

Vincular las llamadas LLM

En cada solicitud al Gateway /chat/completions, envíe:

x-beak-trace-id: <su trace_id>
x-beak-span-id: <id que elija para este span LLM>
x-beak-parent-span-id: <id del paso que desencadenó la llamada LLM>

Cuando el Gateway detecta x-beak-trace-id, omite la inserción de la fila de traza (su aplicación es la propietaria de la traza) y emite solo el span con los ids que usted proporcionó. El span LLM aparecerá como hijo de parent_span_id en el árbol de trazas.

Emitir la fila de traza manualmente

Una vez que su aplicación es propietaria de la traza, debe emitir la fila de traza. Realice una solicitud POST a:

POST {base_url}/aiobservability/ingest/traces

Cuerpo:

{
  "traces": [
    {
      "trace_id": "trace-abc123",
      "agent_id": "support-agent-v2",
      "agent_name": "Support Triage",
      "user_id": "user-42",
      "session_id": "session-xyz",
      "start_time": "2026-05-06T14:00:00Z",
      "end_time": "2026-05-06T14:00:05Z",
      "status": "ok",
      "total_tokens": 1240,
      "prompt_tokens": 800,
      "completion_tokens": 440,
      "total_cost": 0.0042,
      "model": "gpt-4o-mini",
      "metadata": {"team_id": "support", "version": "v2.3.1"}
    }
  ]
}

Encabezados requeridos:

Authorization: Bearer <jwt>      # or API-Key: <token>
tenantid: <tenant-id>
Content-Type: application/json

Emitir spans que no son LLM

Para llamadas a herramientas, recuperaciones y cualquier otro paso que desee visualizar en el árbol de trazas, envíe spans a:

POST {base_url}/aiobservability/ingest/spans

Cuerpo:

{
  "spans": [
    {
      "span_id": "span-tool-1",
      "trace_id": "trace-abc123",
      "parent_span_id": "span-root",
      "name": "tool.search_kb",
      "service_name": "support-agent",
      "kind": "internal",
      "start_time": "2026-05-06T14:00:01Z",
      "end_time": "2026-05-06T14:00:02Z",
      "status": "ok",
      "input_value": "{\"query\": \"refund policy\"}",
      "output_value": "[3 documents]",
      "attributes": {"tool": "search_kb", "result_count": 3},
      "events": []
    }
  ]
}

Campos de span

Campo	Requerido	Notas
span_id	Sí	Globalmente único dentro de su traza.
trace_id	Sí	Coincide con la traza que emitió (o proporcionó mediante x-beak-trace-id).
parent_span_id	Cuando está anidado	Cadena vacía para el span raíz.
name	Sí	Convención: llm.<model> para LLM, tool.<name> para herramientas, retrieval.<source> para RAG.
service_name	Sí	Identificador de su servicio / agente.
kind	Sí	Uno de internal, server, client, producer, consumer.
start_time / end_time	Sí	ISO-8601 con zona horaria.
status	Sí	Uno de ok, error, unset.
gen_ai_*	Solo LLM	Conteo de tokens y coste. Deje el valor predeterminado 0 para spans que no son LLM.
input_value / output_value	No	Entradas y salidas en formato de cadena. Codifique en JSON los valores complejos.
attributes	No	Metadatos de clave-valor de formato libre.
events	No	Reservado para eventos de span (errores, reintentos).

Procesamiento por lotes

Ambos endpoints aceptan lotes. Límites: hasta 1000 trazas por solicitud y hasta 5000 spans por solicitud. El procesamiento por lotes es de tipo fire-and-forget desde el propio callback del Gateway actualmente; replique ese patrón en su código — las llamadas de observabilidad nunca deben bloquear la ruta orientada al usuario.

---

Patrón 2 — Moderar contenido que no es LLM

Utilice este patrón cuando el contenido necesite análisis de política incluso sin que haya una llamada LLM en curso: argumentos de herramientas, recuperaciones RAG, cargas de archivos o contenido de sistemas externos.

Endpoint

POST {base_url}/aisecurity/inline/scan

Encabezados

Authorization: Bearer <jwt>      # or API-Key: <token>
Content-Type: application/json

tenantid, userid y roleid son inyectados por el Gateway a partir del JWT. No los configure manualmente.

Solicitud

{
  "messages": [
    {"role": "user", "content": "<text to scan>"}
  ],
  "agent_id": "support-agent-v2",
  "security_policy": "Healthcare Compliance",
  "project_id": null,
  "guardrail_ids": null,
  "rag_context": ["snippet 1", "snippet 2"],
  "response": "<optional LLM response to also scan>"
}

Selección de validadores

Exactamente uno de los siguientes determina qué validadores se ejecutan:

• guardrail_ids — Una lista de ids de guardrails. Solo se evalúan los validadores de esos guardrails.
• security_policy — Un nombre de política. Los guardrails de la política se resuelven en un conjunto de validadores.
• project_id — Un id de proyecto. Los validadores provienen de los guardrails del proyecto.
• Ninguno — Se ejecutan todos los validadores (ruta más costosa; resérvela para análisis ad hoc).

Nota: Pase agent_id para atribuir el análisis a un agente registrado en Patrón 3 — Registrar un Agente. La acción queda registrada en el perfil del agente y aparece en su historial de acciones.

Respuesta

{
  "status": "success",
  "message": "Moderation complete",
  "data": {
    "compliant": false,
    "action": "block",
    "legacy_action": "deny",
    "risk_score": 80.0,
    "results": [
      {"validator": "pii_email", "compliant": false, "reason": "Email detected", "details": {}}
    ],
    "findings": [...],
    "redacted_text": "<text with matches redacted>",
    "policy_id": 7,
    "fired_rules": ["block_pii"],
    "reason": "PII detected in input",
    "event_id": "evt-...",
    "timestamp": "2026-05-06T14:00:00Z"
  }
}

Veredictos

• action — Vocabulario de cinco valores del motor de reglas: allow, log, warn, redact, block.
• legacy_action — Mapeo de tres valores para los llamadores que operan con un único booleano: allow, review, deny. Corresponde: log → allow, warn y redact → review, block → deny.
• risk_score — 0.0–80.0. Sintetizado a partir de la acción para que los dashboards existentes continúen funcionando.
• redacted_text — Solo se rellena cuando action es redact. Utilícelo en lugar del texto original en los pasos posteriores.
• event_id — Identificador del Registro de Auditoria. Muéstrelo en su interfaz de error para que el equipo de seguridad pueda navegar directamente a la entrada del Explorador Forense.

Aplicar el veredicto en su código

import httpx

resp = httpx.post(
    f"{BASE_URL}/aisecurity/inline/scan",
    headers={"Authorization": f"Bearer {JWT}"},
    json={
        "messages": [{"role": "user", "content": user_text}],
        "agent_id": "support-agent-v2",
        "security_policy": "Healthcare Compliance",
    },
    timeout=10,
)
data = resp.json()["data"]

if data["legacy_action"] == "deny":
    raise PolicyBlocked(reason=data["reason"], event_id=data["event_id"])
if data["action"] == "redact":
    user_text = data["redacted_text"]
if data["legacy_action"] == "review":
    flag_for_human_review(event_id=data["event_id"])
# allow → continue

Atestación del agente (opcional)

Cuando a un agente se le ha emitido una clave criptográfica (consulte el Patrón 3), firme cada solicitud de moderación e incluya:

x-agent-signature: <firma ed25519 del cuerpo sin procesar>
x-agent-timestamp: <marca de tiempo firmada>
x-agent-nonce: <nonce aleatorio>

El servicio de Security verifica la firma utilizando la clave pública almacenada del agente. Una verificación fallida devuelve 403 Agent attestation failed. Omita estos encabezados si el agente no está configurado para requerir atestación.

---

Patrón 3 — Registrar un Agente

Registre cada agente externo en el Registro de Agentes para que sus acciones aparezcan en los registros de auditoría y se apliquen sus alcances permitidos y su umbral de riesgo.

Crear

POST {base_url}/aisecurity/agents

{
  "agent_id": "support-agent-v2",
  "name": "Support Triage Agent",
  "description": "Triages incoming support tickets",
  "permissions": {},
  "risk_threshold": 50,
  "allowed_scopes": ["read"],
  "status": "active",
  "generate_keypair": false,
  "require_attestation": false
}

risk_threshold va de 0 a 100. Un valor más bajo es más estricto. Establezca generate_keypair: true para crear un par de claves Ed25519 al registrar el agente — la clave privada se devuelve una sola vez en la respuesta.

Generar, rotar o revocar una clave

POST {base_url}/aisecurity/agents/{id}/generate-key
POST {base_url}/aisecurity/agents/{id}/rotate-key   { "reason": "<text>" }
POST {base_url}/aisecurity/agents/{id}/revoke-key   { "reason": "<text>" }

El valor de la clave privada se devuelve exactamente una vez en generate-key y rotate-key. El servidor almacena únicamente la clave pública; no puede recuperar una clave privada perdida — genere una nueva y rótela.

Listar las acciones del agente

GET {base_url}/aisecurity/agents/{id}/actions

Devuelve todas las acciones auditadas atribuidas al agente — solicitudes de moderación, bloqueos, fallos de atestación — para la elaboración de informes de cumplimiento.

---

Patrón 4 — Consultar el Registro de Auditoria

El Registro de Auditoria está encadenado por hash — cada entrada incluye un content_hash y un previous_hash para que cualquier manipulación sea detectable. Consúltelo mediante:

GET {base_url}/aisecurity/audits

Utilícelo como evidencia de cumplimiento y para revisión forense. Los mismos datos sustentan las interfaces del Registro de Auditoria y del Explorador Forense.

---

Buenas Prácticas

• Envíe las llamadas de observabilidad de forma fire-and-forget. La ruta orientada al usuario nunca debe bloquearse esperando la ingesta de una traza. Replique lo que hace el Gateway: publique en una tarea en segundo plano y descarte los errores al nivel de log de depuración.
• Reutilice un único httpx.AsyncClient (o equivalente) en todas las llamadas. Ambos endpoints de ingesta admiten procesamiento por lotes — almacene spans y trazas en memoria y vacíelos cada pocos segundos en lugar de publicar uno a uno.
• Mantenga los valores de name de los spans estables. Observabilidad agrupa por nombre al clasificar los spans más frecuentes; cambiar tool.search_kb por tool.searchKB a mitad de una versión fragmenta los dashboards.
• Para la moderación de contenido que no es LLM, prefiera security_policy en lugar de pasar guardrail_ids directamente. La política es un contrato estable; los ids de guardrails pueden cambiar a medida que el equipo de seguridad reorganiza la jerarquía de validadores.
• No llame a /aisecurity/inline/scan desde dentro de un bucle de agente que ya enruta a través del Gateway. El Gateway ya moderó los mensajes LLM — llamar de nuevo duplica las entradas de auditoría y aplica el motor de reglas dos veces.
• Trate el event_id devuelto por cada llamada de moderación como un campo de primera clase. Regístrelo, muéstrelo en las interfaces de error y reenvíelo en los tickets de soporte para que el equipo de seguridad pueda navegar directamente a la entrada de auditoría.
• Registre todos los agentes en el Registro de Agentes, incluso los internos de bajo riesgo. El registro es la clave de unión entre trazas, eventos de moderación y sesiones forenses — los agentes no registrados aparecen como anónimos en las vistas de cumplimiento.

---

Páginas Relacionadas

• Agentes Externos — Descripción General
• Integración con AI Gateway
• AI Security — Políticas
• AI Security — Guardrails
• AI Security — Validadores
• AI Security — Registro de Agentes
• AI Security — Registro de Auditoria
• AI Observability — Comprender una Traza
• AI Observability — Agentes