Agentes de IA¶

Cómo gestionan los administradores los agentes de IA en kubelatch: un bot para un agente, el interruptor de aprobación, las sesiones y solicitudes de «Agentes», y cómo cortarle el acceso a un agente. Agentes de IA en Conceptos explica el modelo y sus límites; las personas que conectan su propio agente siguen Agentes de IA.

El servidor MCP¶

kubelatch sirve el servidor MCP en <KUBELATCH_BASE_URL>/mcp y, junto a él, los endpoints con los que inician sesión los agentes delegados. Viene activado; KUBELATCH_MCP_ENABLED=false desactiva ambos (config.mcpEnabled en el chart).

Todas están en Configuración. La página de consentimiento que responde una persona para autorizar a un agente («¿Dejar que Claude Code actúe como tú?») dice quién pide, a dónde va la respuesta, qué recibe el agente y hasta cuándo, y avisa siempre que la respuesta fuera a salir de ese ordenador; Agentes de IA la recorre.

Además de lo que ya envía, el despliegue debe enviar a kubelatch /mcp, /oauth/ y /.well-known/. Los clientes de los agentes buscan /.well-known/oauth-protected-resource/mcp y /.well-known/oauth-authorization-server en la raíz del host de KUBELATCH_BASE_URL, aunque la URL base tenga ruta. El Ingress del chart ya envía a kubelatch todas las rutas de su host.

/mcp rechaza una petición cuya cabecera Origin no sea el origen de KUBELATCH_BASE_URL: los clientes MCP que se ejecutan dentro de una página web no están soportados. El cuerpo de una petición puede tener como mucho 1 MiB.

Un bot para un agente¶

Para un agente que no es de una persona (uno de guardia, un paso de un pipeline):

1. Crea un bot en «Usuarios» y concédele el rol más pequeño que sirva, en un namespace mejor que en todo el cluster (Bots, Conceder permisos). Un agente que diagnostica solo necesita viewer.
2. Abre la página de la cuenta del bot desde «Usuarios». Su tarjeta «Agente de IA» tiene:
   • «Las escrituras piden aprobación»: desactivado por defecto, así que decide solo el rol del bot. Activado, cada escritura de los agentes del bot espera a que un administrador la apruebe, salvo que la cubra una solicitud de acceso aprobada. Activarlo o desactivarlo pide confirmación («Pedir aprobación», «Dejar de pedirla») y vale desde la siguiente escritura del agente.
   • «Conectar un agente»: el endpoint MCP y los comandos para Claude Code y Cursor. Un bot deshabilitado no lo ofrece.
   • «Sesiones de este bot»: abre «Agentes» acotado a las sesiones de ese bot.

3. Emite una credencial para el bot (Bots), tan corta como la tarea. Donde se ejecuta el agente, guarda su token en la variable KUBELATCH_TOKEN y añade kubelatch al agente con los comandos de «Conectar un agente»:

   claude mcp add --transport http kubelatch https://kubelatch.example.com/mcp --header "Authorization: Bearer $KUBELATCH_TOKEN"
   

   {
     "mcpServers": {
       "kubelatch": {
         "url": "https://kubelatch.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:KUBELATCH_TOKEN}" }
       }
     }
   }
   

   El diálogo nunca muestra un token. En /mcp solo valen las credenciales propias de un bot: la credencial de una persona, una sesión de kubelatch login o una credencial de CI reciben 401.

La sesión de agente del bot empieza la primera vez que su credencial se usa en /mcp, una sesión por credencial. Dale también al agente las reglas, para que use las herramientas en lugar de kubectl.

Sesiones y solicitudes¶

«Agentes», en la barra lateral, es para todos. Un administrador ve las sesiones y solicitudes de todas las cuentas; los demás, solo las suyas. Tres cifras encabezan la página: «Esperan tu decisión», «Sesiones activas» y «Última llamada». Las dos primeras son interruptores que aplican el segmento «Pendientes» o «Activas» de la tarjeta de debajo. Después vienen dos tarjetas, «Solicitudes» y «Sesiones»; «Solicitudes» va primero mientras alguna espera una decisión, y «Sesiones» en los demás casos.

Sesiones¶

• «Sesiones» lista cada agente conectado en una fila con el nombre de la cuenta en cuyo nombre actúa y el del propio agente, como deploy-bot · node. Bajo el nombre van su modo («Bot» o «Delegado»), el rol con el que trabaja (en una sesión delegada, lo que le dio la persona; en la de un bot, los permisos propios del bot) y sus solicitudes pendientes, si las hay. Las columnas son «Sesión», «Caduca», «Último uso» y «Estado» («Activa», «Cortada» o «Caducada»), y el menú de la fila tiene «Abrir» y «Cortar». Los segmentos «Activas» y «Terminadas» las separan.
• La página de una sesión lleva ese nombre, con su modo y su estado como píldoras. Empieza por «Esperan una decisión» cuando hay solicitudes pendientes de esa sesión, cada una como su frase con un enlace a su página. Después muestra «Sesión» («En nombre de», «Agente», «Empezó», «Último uso», «Caduca», la «Credencial» o el «Cliente OAuth», «Las escrituras piden aprobación» y, una vez cortada, «Cortada por»), «Permisos en vigor» (lo que cuenta ahora) y, en una sesión delegada, su «Techo»: «Permisos posteriores» (lo que toma de los permisos que la persona reciba después: «No incluir», «Solo lectura» o «Mismo rol»), y luego cada permiso que tiene, de cuál viene y si sigue contando.
• «Línea de tiempo» lista las llamadas a herramientas del agente, la más reciente primero, una línea cada una: la hora, la herramienta, qué hizo (patch deployments web, y +1 escritura más cuando la llamada hizo otras escrituras), el resultado y la duración. El botón 3 peticiones despliega las peticiones que la llamada envió al cluster, de la más antigua a la más reciente, y cada una abre el mismo panel que en «Auditoría». Una llamada recibe el nombre de su última escritura o, si no la hay, de su última petición real, nunca de un dry run: una escritura retenida para aprobar se llama como lo que leyó, y su dry run queda marcado con «prueba» entre las peticiones. Las peticiones de descubrimiento (/api, /apis, /version) quedan fuera hasta que marcas «Incluir peticiones de descubrimiento». Para los administradores, «Ver en Auditoría» abre esas mismas filas en «Auditoría».

La sesión de un bot no tiene caducidad propia: dura lo que su credencial. Una sesión delegada dura lo que eligió la persona.

Solicitudes¶

«Solicitudes» lista lo que los agentes piden decidir a una persona. Sus segmentos, «Pendientes», «Resueltas» y «Caducadas», dicen cuántas tiene cada uno. Cada fila es la frase de la solicitud, que enlaza a su página, con cuándo se pidió, su «Tipo» y su «Estado»:

• «Escritura»: un cambio retenido para aprobar. Su página muestra «Cambios»: el objeto actual frente a lo que el dry run del cluster dice que será, con los valores de los Secrets ocultos. Una escritura espera 15 minutos una decisión; aprobada, otros 15 para ejecutarse, una vez.
• «Acceso»: un rol en un namespace (o en todo el cluster) durante unos minutos, con el motivo del agente. Espera una hora.

El cliente del agente suele abrirle la página de decisión a la persona (Claude Code, que pregunta antes, sin plugin), y la llamada del agente espera la decisión hasta KUBELATCH_AGENT_APPROVAL_WAIT y vuelve a preguntar mientras la solicitud dure. Si el cliente no puede abrirla, o la persona lo rechaza, el agente entrega el enlace en texto. Repetir la llamada de una escritura que ya espera no crea otra solicitud.

Una solicitud pendiente que puedes decidir tiene además «Aprobar» en su fila. Primero carga la solicitud y luego pide la misma confirmación que su página: la frase, lo que hace el cambio (en un Secret, que sus valores ocultos pueden cambiar), lo que significa aprobarla y el tiempo que queda. Solo aprueba «Aprobar» en esa confirmación. Una solicitud que otra persona decidió o que caducó entretanto no se aprueba, y la lista dice por qué. Para leer el diff entero, abre su página.

Quién decide:

• Las solicitudes de un bot: cualquier administrador. Aprobar el acceso de un bot concede un permiso normal con esa caducidad, con las reglas de siempre (aparece en «Permisos»), durante 8 horas como mucho.
• Las solicitudes de una sesión delegada: solo la persona en cuyo nombre actúa el agente. Un administrador las ve, pero no las puede decidir.

Mientras hay solicitudes esperando a alguien, «Agentes» en la barra lateral lleva su número y la campana muestra un aviso, a quien puede decidirlas: una sola solicitud enlaza a su página, varias a la tarjeta «Solicitudes». Una cuenta puede tener como mucho 20 solicitudes esperando.

La página de decisión¶

La página de una solicitud, el enlace que el agente le da a la persona, lleva por título lo que se pide: «deploy-bot quiere cambiar configmaps/feature-flags en apps (kind-local)», o «deploy-bot pide el rol developer en apps (kind-local) durante 2 h». Bajo el título van su píldora de estado, quién la pidió y cuándo («Pedida hace 3 min por el agente node») y, mientras espera, una cuenta atrás («caduca en 11:42»). Abrir la página no decide nada: solo lo hace pulsar «Aprobar» o «Denegar».

En una escritura, «Cambios» empieza por una línea de lo que hace («Crea el objeto (12 líneas)», «Cambia 2 líneas de data», «Elimina el objeto») y sigue con el diff: las líneas que se van empiezan por −, las que llegan por +. Los metadatos que gestiona el API server (creationTimestamp, uid, resourceVersion, managedFields, generation, selfLink) quedan plegados tras «Mostrar las 7 líneas de metadatos», y en un móvil las líneas largas se parten en lugar de desplazarse. En un Secret, la línea nunca dice que no cambia nada: sus valores no se muestran, y un valor que la escritura cambia se lee <redacted, N bytes, changed> en lo que será, así que sale como una línea cambiada aunque su tamaño sea el mismo. Un cambio demasiado grande para compararlo línea a línea se muestra entero, con un aviso para que lo compares tú. Si el agente dio un motivo, la página lo cita.

«Denegar» y «Aprobar» van después del diff, y en un móvil quedan fijos al pie de la pantalla. Cada uno pide confirmación con la frase del cambio. «Aprobar la escritura» añade que se ejecuta una vez, cuando vuelva la llamada del agente que la espera; «Denegar la solicitud» añade que el agente recibe una negativa y no se ejecuta nada. La página de una solicitud de acceso avisa de lo que significa aprobarla, y «Aprobar el acceso» lo repite: mientras dure, las escrituras del agente allí se ejecutan sin aprobación, con todo lo que sus otros permisos allí le permitan.

Una vez decidida o caducada, la página dice qué fue de ella («Aprobada por alex a las 17:21 · se ejecutó una vez, el cluster respondió 201.», «Caducó a las 17:34 sin ejecutarse; el agente tiene que pedirla de nuevo.») y los botones desaparecen. En «Detalles», plegados, están la sesión, el agente, la herramienta, el id, la petición y las horas exactas en que se pidió, caduca, se decidió y se ejecutó.

Cortar el acceso a un agente¶

En «Agentes», abre la sesión (o el menú de su fila) y pulsa «Cortar»:

• La sesión de un bot: se revoca la credencial del bot, se cierran sus solicitudes pendientes y se revocan los permisos que se le concedieron por solicitud. Para volver a conectar el agente hace falta otra credencial.
• Una sesión delegada: se revocan sus tokens, se cierran sus solicitudes pendientes y terminan los permisos que le dio la persona.

La siguiente llamada del agente falla. Deshabilitar el bot o la persona también termina todo lo que tenían sus agentes. Revocar un permiso de una persona quita al momento a sus agentes lo que venía de él.

Auditoría¶

Cada petición que un agente envía a un cluster es una fila de auditoría con su sesión de agente y su herramienta. En «Auditoría», «Más filtros» tiene «Herramienta» y «Sesión de agente», «Qué» termina con la herramienta, y el detalle de una petición muestra «Herramienta MCP» y «Sesión de agente» (Auditoría y retención). Las filas de un agente delegado tienen a la persona como sujeto. whoami y request_access no llegan a ningún cluster y no dejan fila de auditoría; su sesión y sus solicitudes están en el plano de control.

Solución de problemas¶

Todos los mensajes están en Errores.