Gobernar un Agente desde Cualquier Plataforma
Un agente no tiene que estar construido en Beak para ser gobernado por Beak. Un agente escrito en LangGraph, CrewAI, LangChain.js, Mastra, o en ningún framework en absoluto puede incorporarse a su inventario gobernado con una sola llamada al iniciarse, y a partir de ese momento aparece en Gobernanza de Agentes junto a los agentes que usted construyó aquí.
Lo que Beak realmente puede hacer por ese agente, sin embargo, depende de algo que un registro no puede cambiar: cuáles de los límites de Beak cruza el tráfico del agente. Un agente que solo le indica a Beak que existe puede ser inventariado e identificado. Un agente cuyas llamadas al modelo se enrutan a través del Beak AI Gateway puede, además, tener sus prompts inspeccionados, sus respuestas analizadas y su gasto atribuido. Esta página trata sobre esa distinción, porque es la diferencia entre un agente que está gobernado y un agente que simplemente está listado.
Qué es un límite y por qué lo decide todo
Un límite es un punto donde el tráfico del agente pasa a través de Beak. Hay cinco, y son los únicos cinco:
gateway.llm— Las llamadas al modelo se enrutan a través de Beak AI Gateway con una clave virtual de Beak.hub.tools— Las llamadas a herramientas y MCP pasan por Beak AI Hub y se autorizan contra los propios ámbitos del agente. Beak actúa como proxy de la llamada y ve su resultado.tool.hook— La plataforma del agente consulta a Beak antes de ejecutar una herramienta, y la ejecuta o no según la respuesta de Beak. La detección de amenazas externas de Microsoft Copilot Studio es este límite hoy en día. Beak ve la definición de la herramienta, sus entradas, el razonamiento del planificador y el mensaje del usuario que desencadenó el turno; nunca ve el resultado de la herramienta, y no ve nada en un turno que no llama a ninguna herramienta.inference.hook— El proveedor del modelo llama al hook de inferencia de Beak antes de completar una solicitud.registry.only— Beak mantiene un registro y nada más.
hub.tools y tool.hook se mantienen separados intencionalmente. Ambos autorizan llamadas a herramientas contra los ámbitos del agente,
pero solo el proxy puede actuar sobre lo que regresó, de modo que reportarlos como un único límite supondría afirmar
la inspección del lado del resultado para un agente cuya plataforma nunca le muestra a Beak un resultado.
La gobernanza se deriva de esos cruces y de nada más. Dos planos se obtienen con el simple registro, porque Beak siempre puede decir que un agente existe y quién es:
| Plano | Qué significa | Concedido por |
|---|---|---|
inventory | El agente está en el registro y se cuenta en las cifras de cobertura | el registro en sí |
identity | El agente tiene una identidad Beak y se le puede otorgar una concesión de autonomía | el registro en sí |
tool_authz | Las llamadas a herramientas y MCP se autorizan contra los ámbitos del agente | hub.tools, tool.hook |
content_runtime | La política del motor de reglas se aplica al tráfico del agente | gateway.llm, hub.tools, tool.hook, inference.hook |
content_prompt | Los prompts se inspeccionan antes de que el modelo los reciba | gateway.llm, inference.hook, tool.hook (solo en turnos con llamada a herramienta) |
content_completion | Las respuestas se analizan después de que el modelo las devuelve | gateway.llm |
cost | El gasto, el presupuesto y los límites de tasa se atribuyen a este agente | gateway.llm |
Lea la tabla en la dirección que importa: content_completion y cost solo están disponibles
a través de gateway.llm. Ninguna cantidad de registros, adopciones o configuraciones los produce,
porque no hay otro punto en el que Beak vea la respuesta o la factura. Si necesita cualquiera de los dos para
un agente, eso implica un cambio en cómo se despliega el agente, no una configuración en esta página.
Nota:
registry.onlyno concede nada más allá deinventoryeidentity. Existe como un valor que puede indicar explícitamente, para que "Beak mantiene un registro y nada más" se interprete como una decisión que alguien tomó en lugar de un campo que alguien olvidó.
Declarar no es conceder
Cuando un agente se registra, puede declarar los límites que pretende cruzar. Una declaración es una solicitud, no un hecho:
- Los límites declarados aparecen como
pending. Nada en la gobernanza del agente ha cambiado. - Los límites concedidos son aquellos para los que Beak ha emitido la credencial — una clave virtual de Gateway, una conexión de Hub. Solo estos elevan lo que se gobierna.
Esta separación es deliberada y es la propiedad de seguridad de todo el modelo. Si declarar fuera
suficiente, un agente podría afirmar su propia gobernanza: nombraría gateway.llm, Beak reportaría sus
prompts como inspeccionados, y nada los estaría inspeccionando. El panel mostraría cobertura mientras
el entorno no la tendría. Por eso el agente declara la intención, y Beak — nunca el agente — decide cuándo esa intención
se volvió real.
Advertencia: Una declaración es visible en la consola como una solicitud pendiente, y un agente con todos los límites declarados y ninguno concedido está gobernado exactamente igual que un agente que no declaró nada. Lea la columna de concedidos, no la de declarados.
Qué significa el nombre del nivel y cuándo ignorarlo
Beak reporta un nivel de gobernanza como abreviatura de un conjunto completo de capacidades:
| Nivel | Planos | Típicamente |
|---|---|---|
managed | los siete | Un agente cuyas llamadas al modelo y a herramientas se enrutan a través de Beak |
brokered | inventory, identity, tool_authz, content_runtime, content_prompt | Un agente de Copilot Studio alcanzado a través del marco de seguridad externa de Beak |
inspected | inventory, identity, content_runtime, content_prompt | Un entorno cubierto por hooks de inferencia de Anthropic |
registered | inventory, identity | Agent 365, Power Platform y otros listados de terceros |
custom | lo que los límites concedan | Una combinación que no coincide con ninguno de los cuatro anteriores |
custom no es un nivel inferior. Es lo que Beak reporta cuando la respuesta honesta es un conjunto que los cuatro
nombres predefinidos no pueden expresar — un agente que mantiene seis de los siete planos, por ejemplo. Beak lo reporta
en lugar de redondear al predefinido más cercano, porque redondear hacia abajo subestima la cobertura que tiene y
redondear hacia arriba afirma cobertura que no tiene.
Por eso la consola muestra una matriz de capacidades en lugar de solo una insignia de nivel, y por eso cualquier integración que lea esto a través de la API debería ramificar sobre los planos individuales:
# Correcto: preguntar qué está gobernado.
if profile.governs("content_prompt"):
...
# Incorrecto: un agente `custom` no está en ninguna tabla de búsqueda por nivel, por lo que esto subreporta
# un agente que mantiene seis planos de siete.
if profile.governance_tier == "managed":
...
registered es también el valor predeterminado para un agente que no declara ninguna fuente. Una fuente que Beak no puede
identificar debe declarar de menos en lugar de declarar de más, por lo que el mínimo — no el máximo — es lo que obtiene
un agente no reconocido.
Registrar un agente
Dos SDKs cubren los frameworks en los que realmente se escriben los agentes. Ambos son idempotentes en
(tenant, source, external_id), por lo que llamar en cada inicio es el uso previsto — así es como un
agente redesplegado se reafirma sin ningún paso del operador.
Python
from beakagentidlib import Declaration, configure, register_agent
configure(
security_url="http://beak-aisecurity:5000",
service_code="orders",
environment="prod",
)
profile = await register_agent(
tenant_id=42,
agent_id="orders-triage",
name="Orders Triage",
source="langgraph",
external_id="svc-orders/triage@v3",
declares=Declaration(boundaries=("gateway.llm",), runtime="customer_hosted"),
)
profile.pending # ("gateway.llm",) — solicitado, aún no emitido
profile.governs("content_prompt") # False, hasta que Beak emita la clave
TypeScript
import { configure, governs, registerAgent } from '@beak/agent-identity';
configure({
securityUrl: 'http://beak-aisecurity:5000',
serviceCode: 'orders',
environment: 'prod',
});
const profile = await registerAgent({
tenantId: 42,
agentId: 'orders-triage',
name: 'Orders Triage',
source: 'langgraph',
externalId: 'svc-orders/triage@v3',
declares: { boundaries: ['gateway.llm'], runtime: 'customer_hosted' },
});
governs(profile, 'cost'); // false
tenant_id, source y external_id son obligatorios sin valores predeterminados. El registro de gobernanza se
clave en los tres, y el id propio de un proveedor solo es único dentro de una conexión — sin el tenant,
dos clientes cuyos conectores descubran el mismo id de agente compartirían un registro.
Adoptar el SDK no cambia nada hasta que usted lo indique
Ambos SDKs tienen como valor predeterminado mode: "log". En ese modo, una interrupción de gobernanza escribe una advertencia clara y
devuelve un perfil degradado; no impide que su agente arranque. Cambie a enforce cuando quiera
que un registro fallido sea fatal.
Dos comportamientos vale la pena conocer antes de integrarlo:
- Un perfil degradado no es una respuesta sobre su entorno. Cada plano muestra
falseen él, porque Beak no pudo ser alcanzado — no porque nada esté gobernado. La advertencia lo indica explícitamente. - Una mala configuración es fatal en ambos modos. Una
security_urlfaltante nunca puede tener éxito en un reintento, por lo que lanza una excepción en lugar de degradarse. Degradarla dejaría al agente permanentemente sin gobernanza detrás de una línea de registro que reporta que todo estaba bien.
Agentes sincronizados a través de un conector
Un agente incorporado por un conector de Runtime — Amazon Bedrock, Salesforce Agentforce, y otros — se registra automáticamente para gobernanza como parte de cada sincronización, con el tipo de proveedor como su fuente. No se requiere nada del autor del agente.
Esto está desactivado hasta que un operador configure AGENT_GOVERNANCE_SECURITY_URL en Beak AI Agent Runtime. Hasta
entonces, las sincronizaciones del conector se comportan exactamente como antes: el agente es invocable y no tiene registro de gobernanza.
Cómo un límite pasa a estar concedido
Solo Beak registra una concesión, y lo hace cuando ha emitido o verificado la credencial que pone el tráfico del agente en el límite. Nada que escriba un agente o un operador eleva un nivel.
| Límite | Registrado cuando |
|---|---|
gateway.llm | Beak AI Gateway vincula una clave virtual a la identidad del agente |
hub.tools | Beak AI Hub crea una conexión MCP propiedad del agente |
tool.hook | La plataforma del agente realiza su primera llamada verificada y dentro del ámbito al hook de herramientas de Beak — para Copilot Studio, la primera llamada analyze-tool-execution desde la aplicación registrada del tenant que Beak inspeccionó realmente |
inference.hook | Beak verifica la primera llamada hook firmada del proveedor para el agente |
registry.only | Nunca se concede; es la declaración de que nada más ocurrirá |
Cada servicio de registro prueba que es un servicio de Beak con una afirmación de carga de trabajo firmada, por lo que "Beak emitió esta credencial" puede ser afirmado por Beak y por nadie más. Una llamada que la plataforma realizó pero Beak no inspeccionó — un entorno fuera del ámbito configurado del tenant, un marco que Beak no pudo analizar — no registra nada, porque conceder un límite sobre ella supondría afirmar una gobernanza que no ocurrió.
Los tres niveles de integración
Los límites anteriores se combinan en tres niveles, que es como el asistente de incorporación y la API describen la profundidad con la que Beak gobierna un agente:
| Nivel | Límites | Nivel que deriva | Qué ve Beak | Qué no puede ver Beak |
|---|---|---|---|---|
| Full Gateway | gateway.llm + hub.tools | managed | Prompts, completions, tokens y costo, cada llamada a herramienta y su resultado | Nada en la ruta del modelo o de las herramientas |
| Inference hook | inference.hook | inspected | El lado del prompt de cada llamada al modelo | Completions y costo — el proveedor mide la llamada |
| Tool hook | tool.hook | brokered | Entradas de herramientas, razonamiento del planificador, las salidas de llamadas a herramientas anteriores que la plataforma lleva en la solicitud, el mensaje del usuario en turnos con llamada a herramienta | Turnos sin llamada a herramienta, completions, costo, el resultado de la llamada que se está autorizando |
No todos los frameworks o plataformas pueden alcanzar todos los niveles, y la razón difiere en naturaleza. GET /aisecurity/agents/onboarding-catalog indica, por fuente, qué niveles son alcanzables y mediante qué
mecanismo, con dos indicadores separados:
reachable: false— El propio protocolo de la fuente no tiene un hook de esa forma. El OpenAI Agents SDK, el Claude Agent SDK, LlamaIndex, AutoGen y los constructores low-code no exponen ningún hook de bloqueo por llamada al modelo, por lo que un inference hook no puede conectarse en proceso para ellos; el Full Gateway o un tool hook es la elección honesta.available: false— La fuente podría alcanzarlo, pero Beak aún no ha enviado la mitad receptora. La nota nombra la brecha, por ejemplo el formato Anthropic Messages que Claude Code necesita del Gateway.
Nota: Un nivel es un conjunto de límites, nada más. Elegir uno declara la intención; las capacidades aparecen solo cuando el límite es concedido como se describe anteriormente.
Tokens de broker para despachadores de herramientas externos
POST /aisecurity/tools/authorize responde "¿puede este agente llamar a esta herramienta?" y está diseñado para ser
llamado por runtimes que Beak no ejecuta. Un llamante fuera del clúster de Beak debe presentar un token de broker
— Authorization: Bearer bkr_... — acuñado por un operador con el permiso agents:keys:
POST /aisecurity/brokers/tokens
{ "name": "orders-runtime" }
El token se muestra una sola vez en la respuesta y se almacena con hash; liste los tokens con GET /aisecurity/brokers/tokens y revoque uno con DELETE /aisecurity/brokers/tokens/{id}.
Un token de broker autentica al llamante y fija el tenant: la decisión se toma igualmente a partir del
perfil propio del agente, y el encabezado tenantid se ignora cuando se presenta un token, por lo que un token
para un tenant no puede apuntarse a otro. Nada se infiere de la red: un llamante que no presenta prueba es rechazado
independientemente de dónde provenga la solicitud. Los propios servicios de Beak — el Agent
Runtime y el Hub — se identifican en cambio con una afirmación de carga de trabajo Ed25519 (la misma
credencial que usan con BEAKIAM) y nombran el tenant en el encabezado; Security mantiene sus claves públicas
como anclas de confianza por entorno.
Nota:
TOOL_AUTHZ_ALLOW_UNAUTHENTICATED_IN_CLUSTERpermite que un clúster cuyo Runtime y Hub aún no firman siga funcionando durante el despliegue. Está desactivado por defecto, y cada respuesta dada bajo él se registra como no autenticada. Despliegue en este orden: implemente Security con el interruptor activado, registre las claves públicas del Runtime y del Hub como anclas de confianza para el tenant de la plataforma, implemente el Runtime y el Hub con sus claves de firma, luego desactive el interruptor. Desactivarlo antes de que ambos servicios firmen rechaza cada llamada a herramienta realizada a través de agentes gestionados por Runtime y conexiones Hub.
El asistente de incorporación
Agent Registry → Onboard agent recorre el mismo contrato en siete pasos. Todo lo que dice el asistente se lee desde el servicio; no predice ninguna capacidad.
- ¿Dónde se ejecuta el agente? — Elija una plataforma, un framework, o Custom framework del catálogo. Cada mosaico indica cuántos de los tres niveles están disponibles hoy. Declare it by hand mantiene el selector de límites sin procesar para una fuente que el catálogo no lista.
- ¿Qué tan profundo debe gobernarlo Beak? — Tres tarjetas de nivel. Cada una lista los planos que el nivel gobernaría, una vez acreditado, con los ausentes indicados en palabras. Una tarjeta que el propio protocolo de la fuente no puede alcanzar está desactivada y lo indica ("No es posible para OpenAI Agents SDK — no hay hook de bloqueo por llamada al modelo"); una tarjeta para la que Beak no ha enviado la mitad receptora está desactivada y nombra la brecha ("Aún no disponible en Beak — …"). Son consejos diferentes, y la tarjeta indica cuál es.
- Registrar — Id del agente, nombre y el propietario (obligatorio — la persona responsable que nombra cada hallazgo sobre este agente). El nivel es la declaración, por lo que los límites se muestran, no se vuelven a marcar.
- Resultado y credencial — Lo que el servicio devolvió realmente: nivel, límites concedidos y pendientes, la lista de capacidades. Luego la credencial que el nivel necesita, mostrada una sola vez: un token de enrolamiento para Full Gateway en un agente que Beak no aloja (la identidad proviene del enrolamiento; la clave de Gateway se vincula a ella después en Claves), un token de broker para un nivel de middleware o webhook, o un enlace a la página de Integraciones para un hook de plataforma.
- Integrar — El fragmento de código verificado para el framework y nivel elegidos, con marcadores de posición para su host de Beak y la credencial, más la llamada de registro. Un nivel sin fragmento verificado aún muestra la nota del catálogo en lugar de código inventado.
- Verificar — Beak consulta el primer evento gobernado de este agente cada cinco segundos mientras el paso está abierto y lo muestra cuando llega. Hasta entonces el agente está pendiente de integración, no protegido. La escalera de cobertura debajo fecha cada peldaño que el agente ha alcanzado y etiqueta cada uno que no ha alcanzado.
- Modo — El agente comienza en modo log. El paso indica dónde se activa la aplicación forzosa para cada nivel y cómo falla ese nivel, porque "protegido" es fácil de leer como fallo cerrado.
Una página de Integraciones para una plataforma que Beak conoce enlaza directamente al paso 2 con esa plataforma elegida (Onboard an agent from this platform), para que un operador que acaba de conectar una plataforma no tenga que buscarla de nuevo.
Nota: El asistente no puede hacer real un nivel. Elegir uno declara la intención y emite la credencial; las capacidades del nivel aparecen solo cuando el tráfico llega sobre esa credencial y Beak registra la concesión, como se describe anteriormente.
Buenas Prácticas
- Registre en cada inicio, no una sola vez en el aprovisionamiento. Es idempotente por diseño, y un redespliegue que lo omite deja un registro obsoleto que nadie nota.
- Declare solo lo que el agente realmente cruza. Una declaración es una solicitud que Beak mostrará como pendiente; declarar todo produce una cola de solicitudes que nunca fueron ciertas y oculta la que sí lo es.
- Lea la matriz de capacidades, no la insignia del nivel. La insignia es un resumen, y para un agente
customes un resumen que ninguna tabla de búsqueda puede expandir. - Trate
registry.onlycomo una respuesta real. Para un agente que desea inventariar y nada más, indicarlo es mejor que dejar el campo vacío y dejar que un lector se pregunte. - Dé al agente su propio
external_id. Es la mitad de la clave de idempotencia; sin él, dos agentes de la misma fuente pueden colapsar en un solo registro.