Control y funcionamiento de agentes: observabilidad, herramientas, MCP, secretos, enlaces y confiabilidad

  • 5 minutos

En esta unidad, aprenderá lo siguiente:

  • Detección de la evidencia y los artefactos necesarios para el trabajo del agente

  • Control de herramientas, integraciones de MCP y secretos de forma segura

  • Cómo los hooks aplican barreras de protección y realizan registros de auditoría

  • Cómo diseñar sistemas fiables mediante reintentos, escalados y privilegios mínimos

Evidencia y artefactos necesarios para agentes

Un sistema de agente debe generar artefactos visibles para cada acción significativa. Sin artefactos, no se puede revisar de forma confiable el comportamiento, depurar fallos, ni realizar análisis posteriores.

En GitHub, la observabilidad se logra mediante artefactos como:

  • solicitudes de incorporación de cambios y plazos,

  • cambios confirmados e historial de ramas,

  • ejecuciones del flujo de trabajo y registros de trabajos,

  • comprobaciones necesarias y resultados de análisis, y

  • Elementos de flujo de trabajo cargados (por ejemplo, informes de prueba).

Conjunto mínimo de observabilidad

Una tarea de agente bien diseñada debe producir evidencia visible y revisable mediante artefactos nativos de GitHub:

  • un plan estructurado, que normalmente viene incluido en la descripción o el hilo de conversión sobre una solicitud de incorporación de cambios

  • una solicitud de incorporación de cambios acotada y el historial de cambios confirmados

  • vínculos de ejecución del flujo de trabajo para las comprobaciones necesarias

  • artefactos subidos (por ejemplo, registros o informes)

  • revisar los resultados (aprobaciones o cambios solicitados)

Cargar artefactos del flujo de trabajo para revisar y depurar

Subir los elementos generados hace que la evidencia sea duradera y revisable, incluso cuando los registros desaparecen de la vista.

Le recomendamos que incluya vínculos a ejecuciones del flujo de trabajo y los artefactos correspondientes en la solicitud de incorporación de cambios en una sección llamada "Evidencia" para que los revisores puedan validar rápidamente los resultados.

- name: Upload test results
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: results/

La confiabilidad supone un error

Los sistemas confiables asumen que se producirá un error. Los agentes interpretarán mal las tareas, las pruebas producirán errores y los cambios entrarán en conflicto con el comportamiento existente. La arquitectura debe detectar errores al principio y proporcionar rutas de recuperación seguras.

Un patrón práctico de confiabilidad incluye:

  • Reintentos: el agente puede ajustar la rama cuando se produce un error en las comprobaciones.

  • Escalado: se hace un resumen de los errores persistentes y se entrega a un usuario humano.

  • Preparación para el retroceso: los cambios con alto riesgo incluyen notas de retroceso y límites de ámbito.

Directiva de iteración segura

Use una directiva de predicción para la iteración:

  • Si se produce un error en una comprobación necesaria, el agente puede revisar la rama de la solicitud de incorporación de cambios y volver a ejecutar las comprobaciones.

  • Si se produce un error en la misma comprobación necesaria dos veces, escale a un revisor humano con:

    • qué ha fallado,

    • lo que se intentó,

    • qué evidencia existe y

    • cuál es el siguiente paso sugerido.

Esta directiva ayuda a evitar bucles infinitos y hace que los errores puedan ser accionables.

Observabilidad como característica de arquitectura necesaria

Un conjunto mínimo de observabilidad para el trabajo autónomo debe incluir:

  • un artefacto de plan visible,

  • un solicitud de incorporación de cambios y el historial de cambios confirmados,

  • vínculos de ejecución del flujo de trabajo para las comprobaciones necesarias,

  • artefactos duraderos (registros/informes/rastros)

  • revisar los resultados y aprobaciones.

Hacer que la evidencia sea rastreable hasta la ejecución y el estado del código

Enseñe un principio de nomenclatura y metadatos:

  • Se debe poder hacer un seguimiento de la evidencia a una ejecución del flujo de trabajo específica y un cambio confirmado específico.

Esto permite que se realicen tareas de auditoría y depuración; podrá responder a la pregunta: "¿qué ejecución ha generado este artefacto y con qué código de estado?"

Aplicar la evidencia en varios trabajos mediante artefactos

Enseñe el patrón:

  • Carga los artefactos donde se producen

  • Descárguelos donde se revisan o se despliegan

Esto hace que los resultados se puedan inspeccionar y utilizar sin confirmar los archivos generados de nuevo en el repositorio.

Control de herramientas, integraciones de MCP y secretos de forma segura

La configuración del perfil del agente proporciona tres tipos de control:

  • Límite de funcionalidades: qué herramientas se permiten (listas de permitidos preferidos)
  • Límite de visibilidad: si el agente es seleccionable por el usuario en la interfaz de usuario interactiva
  • Límite de delegación: qué subagentes se pueden invocar y cómo se producen las transferencias. Guía de diseño:
  • Utilice conjuntos de herramientas de solo lectura para planificar y realizar la revisión de agentes.
  • Restrinja las herramientas de implementación a los agentes de ejecución.
  • Considera los cambios en las listas de herramientas permitidas como un cambio significativo en términos de gobernanza.

Servidores MCP: ampliar herramientas de forma segura

Los servidores MCP amplían la funcionalidad de la herramienta. Enseñe estos patrones:

  • Forma de transporte: algunos servidores MCP son puntos de conexión remotos; otros son procesos locales.
  • Autenticación: los tokens se deben insertar en tiempo de ejecución a través de límites secretos protegidos.
  • Control de espacio de nombres: es preferible habilitar un subconjunto de herramientas limitadas en lugar de caracteres comodín más genéricos.

Guía operativa:

  • Si se añaden o expanden herramientas de MCP, es mayor el radio de impacto y debe revisarse como una dependencia de alto riesgo.

Restricciones de entorno y secretos (mantener los secretos fuera del contenido del repositorio)

No coloque secretos en:

  • archivos de instrucciones,
  • archivos de configuración comprometidos,
  • o el flujo de trabajo YAML con texto sin formato.

En lugar de:

  • Usar límites de secretos protegidos destinados a la inserción de código en el entorno de ejecución
  • Pasar secretos solo a los componentes que los necesitan,
  • Restringir el acceso a secretos (por ejemplo, en el entorno) para reducir la exposición.

Enseñe el principio:

  • "El entorno en tiempo de ejecución del agente tiene su propio límite secreto; no suponga que hereda automáticamente los secretos de CI del repositorio".

Cómo los hooks aplican barreras de protección y realizan registros de auditoría

En los agentes de GitHub Copilot, los hooks son definidos como archivos de configuración almacenados en el repositorio (por ejemplo, en .github/hooks/). Cada gancho especifica cuándo se ejecuta y qué acción realiza.

Los enlaces ejecutan comandos personalizados en puntos específicos durante la ejecución del agente. Esto permite a los equipos aplicar directivas, validar acciones y capturar datos de auditoría automáticamente.

Un ejemplo simplificado:

{
  "name": "block-high-risk-command",
  "trigger": "pre-tool-use",
  "run": "if [[ \"$TOOL\" == \"delete\" ]]; then echo 'Blocked unsafe command'; exit 1; fi"
}

Como funciona esto

  • El hook se activa antes de utilizar una herramienta (pre-tool-use)

  • Inspecciona la acción solicitada.

  • Si la acción coincide con un patrón bloqueado, se detiene la ejecución.

Patrones de gancho comunes

  • Enlaces previos a la acción Validar o bloquear acciones no seguras antes de la ejecución

  • Hooks posteriores a la acción se registran el uso de herramientas, los resultados o las decisiones para la auditoría

  • Hooks de errores detectan fallos y activan el escalado o las alertas

Qué hooks activar

  • Aplicación de directivas de seguridad (por ejemplo, bloqueo de comandos no seguros)

  • Añadir registros de auditoría para el cumplimiento y la depuración

  • Integración con sistemas externos (alertas, supervisión, aprobaciones)

  • Los ganchos proporcionan puntos de control aplicables que funcionan independientemente del razonamiento del modelo. En lugar de confiar en instrucciones, garantizan que ciertas reglas siempre se aplican durante la ejecución.

Cómo diseñar sistemas fiables mediante reintentos, escalados y privilegios mínimos

Como hemos hablado anteriormente, los agentes finalmente producirán un error, pero podemos crear sistemas que puedan detectar estos errores y garantizar que la intervención humana lo detecte, por ejemplo, aquí hay un par de maneras de garantizar que se detectan errores:

  • Reintentos limitados para errores transitorios

  • Rutas de escalación para errores repetidos

  • Preparación para la reversión de cambios de alto riesgo

  • Permisos con privilegios mínimos para reducir el radio de impacto

Patrón seguro de reversión recomendado:

  • Opere con identificadores explícitos (commit/tag) al implementar configuraciones críticas, en lugar de descargar "lo último de una rama".

Recordatorio de privilegios mínimos:

  • Restrinja los permisos de flujo de trabajo de forma predeterminada y eleve solo cuando sea necesario.

Permisos de flujo de trabajo con privilegios mínimos

El privilegio mínimo reduce el riesgo cuando algo va mal. También impide que la automatización con permisos excesivos se convierta en una vulnerabilidad arquitectónica.

permissions:
  contents: read
  pull-requests: write

Esta configuración permite que la automatización lea el contenido del repositorio y ajuste el contexto de la solicitud de incorporación de cambios (comentarios, estados) al tiempo que impide el acceso general de escritura de forma predeterminada.