Saltar al contenido principal

Agentes y Aplicaciones Externos

Esta guía está dirigida a equipos que ejecutan una aplicación o agente de IA fuera del Runtime de IA de Beak — una aplicación personalizada en Python o TypeScript, un agente LangChain / LangGraph, un SaaS de terceros, una herramienta interna — y que desean utilizar Beak como su capa de gobernanza, seguridad y observabilidad para el tráfico LLM.

La superficie de integración es intencionalmente reducida. En la ruta predeterminada, una aplicación externa solo necesita apuntar su cliente LLM al Beak Gateway y pasar una clave virtual. La moderación según la política del equipo y el rastreo en Observabilidad ocurren automáticamente como parte del pipeline del Gateway — no se requieren llamadas adicionales.

Arquitectura​

┌──────────────────────┐      Authorization: Bearer sk-...       ┌────────────────────────┐
│  Agente o Aplicación │  ─────────────────────────────────────▶  │  Beak AI Gateway       │
│  Externa             │                                          │  (gobernanza,          │
│                      │  ◀────────────────  respuesta  ────────  │  enrutamiento,         │
└──────────────────────┘                                          │  seguridad)            │
                                                                  └──┬─────────────────────┘
                                                                     │
                                  ┌──────────────────────────────────┤
                                  │  en línea (cuando team.enable_security)
                                  ▼
                           ┌─────────────────────┐
                           │  Beak AI Security   │   POST /aisecurity/inline/scan
                           │  (moderación)       │
                           └─────────────────────┘

                                  ┌──────────────────────────────────┐
                                  │  fire-and-forget (cuando team.enable_observability)
                                  ▼
                           ┌─────────────────────┐
                           │  Beak AI            │   POST /aiobservability/ingest/traces
                           │  Observability      │   POST /aiobservability/ingest/spans
                           └─────────────────────┘

Cada solicitud externa entra a través del Gateway. Cuando se realiza una llamada LLM, el Gateway:

  • Valida la clave virtual, el presupuesto, la lista de modelos permitidos y los límites de tasa.
  • Si el equipo tiene Security habilitado, invoca la política asignada a través de /aisecurity/inline/scan y bloquea la solicitud ante un veredicto deny.
  • Enruta la solicitud al proveedor seleccionado.
  • Emite un trace y un span hacia AI Observability cuando el equipo tiene Observability habilitado.

Las aplicaciones externas nunca necesitan llamar directamente a los servicios de Security u Observability para el flujo estándar de llamadas LLM. Las llamadas directas solo son necesarias para los patrones avanzados descritos en AI Security & Observability — Direct API.

Perfiles​

Seleccione la forma de integración que se ajuste a su aplicación.

PerfilDescripciónLo que necesita
Solo cliente LLMSu código llama a un LLM. Desea gobernanza (presupuesto, límite de tasa, lista de modelos permitidos), moderación automática y rastreo automático.Clave virtual. Apunte cualquier cliente compatible con OpenAI (OpenAI SDK, LangChain, código personalizado) al Beak AI Gateway. Listo.
Agente con bucle propioUsted orquesta razonamiento de múltiples pasos, llamadas a herramientas y sub-agentes en su propio código. Desea que cada paso esté en un único trace propiedad de su aplicación.Clave virtual + IDs de trace propios. Envíe encabezados x-beak-trace-id en las llamadas LLM para que el Gateway integre sus spans en su trace. Emita sus propios spans que no sean LLM directamente a /aiobservability/ingest/spans.
Moderación sin LLMNecesita analizar contenido (entradas de herramientas, documentos RAG, cargas de archivos) para verificar el cumplimiento de políticas incluso cuando no se realiza ninguna llamada LLM.Clave virtual o JWT de servicio + llamadas directas a /aisecurity/inline/scan.
Administración de autoservicioSu plataforma gestiona equipos, claves virtuales, modelos o presupuestos en nombre de los usuarios.JWT de servicio + endpoints de administración bajo /aigateway/*.

URL Base y Autenticación​

Beak expone un único ingress por entorno. Las sub-rutas dirigen al servicio backend correspondiente.

CapacidadPrefijo de rutaAutenticación
Llamadas LLM (compatibles con OpenAI)/chat/completionsClave virtual — Authorization: Bearer sk-<vkey>
Administración del Gateway (equipos, claves, modelos, gasto, alertas)/aigateway/*JWT o API-Key
AI Security (moderación, agentes, políticas, auditoría)/aisecurity/*JWT o API-Key
AI Observability (ingesta de traces, traces, evaluaciones)/aiobservability/*JWT o API-Key

Nota: Las claves virtuales (sk-...) autentican únicamente el endpoint LLM. Las API de administración, Security y Observability requieren un JWT o API-Key emitido a través de Beak IAM. Los dos tipos de credenciales no son intercambiables.

Claves virtuales​

Se emiten en la interfaz del Gateway en AI Gateway > Virtual Keys (consulte Virtual Keys). Cada clave hereda el presupuesto, los límites de tasa, la lista de modelos permitidos y los interruptores de Security/Observability de su equipo. El valor de la clave se muestra una sola vez en el momento de la creación — guárdelo en un administrador de secretos.

JWT / API-Key​

Emitido a través de Beak IAM. El middleware de autenticación del Gateway acepta el token en cualquiera de los siguientes encabezados:

API-Key: <token>
Authorization: Bearer <token>

Tras la validación, el Gateway inyecta los encabezados tenantid, userid y roleid en las solicitudes descendentes — su código nunca los establece.

Endpoints de entorno​

EntornoURL Base
Desarrollo localhttp://localhost:5001 (API Gateway), http://localhost:5060 (Gateway Manager directo)
Devhttps://<tenant>-dev.beakops.com/api
QAhttps://<tenant>-qa.beakops.com/api
Producciónhttps://<tenant>.beakops.com/api

Reemplace <tenant> con el slug de su tenant. El nombre de host exacto de producción se aprovisiona por tenant — confirme con su equipo de cuenta de Beak.

Cuándo utilizar llamadas directas a Security / Observability​

La ruta predeterminada /chat/completions cubre la mayoría de los casos de uso. Recurra a llamadas directas solo cuando:

  • Usted es propietario del trace. Su aplicación es el padre de una ejecución de agente de múltiples pasos y desea que los spans LLM estén anidados bajo su trace, no el del Gateway. Utilice el patrón de encabezado x-beak-trace-id.
  • Necesita moderar contenido que no es LLM. Argumentos de herramientas, fragmentos RAG, contenidos de archivos o cargas de usuarios requieren análisis de políticas incluso cuando no se involucra ninguna llamada LLM.
  • Ingesta spans de trabajo que no es LLM. Llamadas a herramientas, recuperaciones, evaluaciones personalizadas — cualquier cosa que desee visualizar en Observability pero que no sea una llamada LLM.

Los procedimientos detallados para cada caso se encuentran en AI Security & Observability — Direct API.

Buenas Prácticas​

  • Emita una clave virtual por entorno por consumidor. Una sola clave compartida entre staging y producción colapsa los registros de auditoría y hace que la rotación sea riesgosa.
  • Configure los interruptores Security y Observability del equipo en la interfaz del Gateway antes de dirigir tráfico de producción hacia la clave. Los interruptores son por equipo, no por clave, por lo que los cambios se aplican inmediatamente a todas las claves del equipo.
  • Trate el valor de la clave virtual como un secreto. Solo aparece una vez en el momento de la creación; rótela emitiendo una nueva clave, desplegándola y luego desactivando la antigua.
  • Evite la tentación de llamar directamente a /aisecurity/inline/scan cuando una llamada LLM ya pasa por el Gateway — la moderación ya ocurre en línea y una segunda llamada genera un doble cargo en el registro de auditoría.
  • Para aplicaciones SaaS multitenant que integran Beak en nombre de sus propios clientes, asigne cada tenant descendente a un equipo Beak separado para que el gasto, los límites de tasa y el aislamiento de políticas se apliquen por cliente.

Páginas Relacionadas​