Adición de middleware

En la página anterior se mostró cómo los conocimientos empaquetan conocimientos sobre dominios reutilizables (instrucciones, material de referencia y scripts) en unidades independientes que cualquier agente puede cargar a petición. Pero a medida que se implementan agentes en producción, surge una nueva categoría de problemas: problemas que afectan a todas las interacciones, sin importar lo que haga el agente.

Debe registrar todas las solicitudes y respuestas. Necesita límites de protección que bloqueen el contenido dañino antes de que el modelo lo vea. Debe aplicar límites de velocidad, detectar excepciones correctamente e insertar telemetría, todo ello sin tocar la lógica principal del agente. Copiar y pegar estas inquietudes en cada agente (o cada herramienta, o cada aptitud) no es una solución escalable y crea problemas de mantenimiento difíciles de gestionar.

El middleware resuelve esto. El middleware permite encapsular la canalización de ejecución del agente con comportamientos reutilizables que interceptan, inspeccionan y modifican solicitudes y respuestas en puntos bien definidos. Piense en el middleware como una serie de capas concéntricas alrededor del agente: cada capa tiene la oportunidad de actuar sobre la entrada antes de llegar al agente y en la salida antes de que llegue al autor de la llamada.

Cuándo utilizar esto

Agregue middleware al agente cuando:

  • Necesita límites de protección para bloquear contenido perjudicial, fuera de tema o infracción de directivas antes o después de que el modelo lo procese.
  • Quiere el registro centralizado o la telemetría de todas las interacciones de los agentes sin modificar a cada agente por separado.
  • Debe modificar solicitudes o respuestas (enriquecer las solicitudes, transformar las salidas o reemplazar los resultados por completo) sin cambiar la lógica del agente.
  • Quiere aplicar directivas como la limitación de velocidad, el filtrado de contenido o las comprobaciones de autenticación que se aplican a cada ejecución.
  • Debe controlar las excepciones de forma coherente: reintentar en errores transitorios, devolver respuestas alternativas adecuadas o registrar errores para diagnósticos.
  • Quiere compartir el estado en toda la canalización, por ejemplo, para rastrear el tiempo de las solicitudes o acumular métricas que necesitan varios componentes de middleware.

Sugerencia

Agent Framework incluye instrumentación integrada para el seguimiento y las métricas. Consulte Observabilidad para obtener más información.

Funcionamiento de la canalización de middleware

Al invocar el método run de tu agente, la solicitud no va al modelo directamente. En su lugar, fluye a través de una canalización de capas de middleware, cada una de las cuales puede inspeccionar o modificar la solicitud, delegar en la capa siguiente y, a continuación, inspeccionar o modificar la respuesta en el camino de vuelta.

┌─────────────────────────────────────────────────────────┐
│  Caller: agent.run("What's the weather?")               │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 1 (Logging)                                  │
│  • Logs the incoming request                            │
│  • Calls next middleware                                │
│  • Logs the outgoing response                           │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Middleware 2 (Guardrails)                               │
│  • Checks input against content policy                  │
│  • If blocked → returns early with rejection message    │
│  • If allowed → calls next middleware                   │
│  • Checks output against content policy                 │
└──────────────┬──────────────────────────────────────────┘
               ▼
┌─────────────────────────────────────────────────────────┐
│  Agent core (model invocation, tool calls, etc.)        │
└─────────────────────────────────────────────────────────┘

Puntos clave:

  1. Cada middleware decide si desea continuar. Un middleware puede llamar a la siguiente capa de la cadena para continuar normalmente o puede cortocircuitar la canalización devolviendo una respuesta directamente, por ejemplo, cuando un límite de protección bloquea una solicitud.
  2. El middleware ve ambas direcciones. Un middleware ejecuta código antes de delegar (para inspeccionar o modificar la entrada) y después de que la respuesta vuelva (para inspeccionar o modificar la salida). Este es el clásico patrón "cebolla".
  3. Varias cadenas de middleware juntas. Al registrar varios componentes de middleware, anidan: el primer middleware registrado es la capa más externa y el último registrado es la capa más interna más cercana al agente.

Sugerencia

Para obtener una vista detallada de cómo encaja el middleware en la canalización de ejecución completa del agente , incluidos los proveedores de contexto y las capas de cliente de chat, consulte La arquitectura de canalización del agente.

Qué puede hacer el middleware

Agent Framework admite middleware en tres capas de la canalización (ejecución del agente, llamada a funciones y cliente de chat), lo que proporciona un control detallado sobre dónde intercepta la ejecución. Entre los patrones comunes se incluyen:

Modelo Ejemplo Referencia
Límites de protección y terminación Bloquear contenido dañino, limitar la longitud de la conversación Terminación y barandillas de seguridad
Control de excepciones Reintentar en errores transitorios, devolver respuestas alternativas Control de excepciones
Invalidaciones de resultados Ocultar datos sensibles, enriquecer o reemplazar la salida del agente Invalidaciones de resultados
Estado compartido Pasar identificadores de solicitud o datos de tiempo entre middleware Estado compartido
Contexto en tiempo de ejecución Variar el comportamiento en función de la configuración de sesión, usuario o por ejecución Contexto en tiempo de ejecución
Ámbito Aplicar middleware a todas las ejecuciones o solo una sola ejecución Agente frente a ámbito de ejecución

Para obtener un tutorial completo sobre cómo definir y registrar middleware, consulte Definición del middleware. Para obtener información general completa sobre la arquitectura, consulte Información general sobre middleware.

Consideraciones

Consideración Detalles
Separación de responsabilidades El middleware mantiene la lógica transversal fuera del código del agente, de las herramientas y de sus habilidades. Cada componente de middleware tiene una única responsabilidad ( registro, límites de protección, control de errores) que puede agregar, quitar o reordenar de forma independiente.
Dependencia del orden El middleware forma una cadena. El orden en que registra el middleware es importante: un middleware de registro que se ejecuta primero verá la entrada sin procesar, mientras que una que se ejecuta por última vez verá la entrada ya modificada por el middleware anterior. Planifique el orden del flujo de trabajo deliberadamente.
Complejidad de la depuración Cuando el middleware modifica entradas o salidas, la depuración requiere comprender la canalización completa. Una respuesta podría parecer incorrecta no debido al agente, sino porque un middleware lo transformó. Un buen middleware de registro (colocado al principio de la cadena) ayuda a diagnosticar estos casos.
Sobrecarga de rendimiento Cada capa de middleware agrega tiempo de procesamiento a cada solicitud. En el caso de operaciones ligeras como el registro, esto es insignificante. Para operaciones costosas como llamar a una API de moderación de contenido externo, la latencia se suma, especialmente cuando se encadenan varios middleware.

Pasos siguientes

Ahora que el agente tiene herramientas, aptitudes y middleware, el siguiente paso es proveedores de contexto : componentes que insertan memoria, perfiles de usuario y conocimientos dinámicos en la ventana de contexto del agente antes de cada ejecución.

Proveedores de contexto

Vaya más profundamente:

  • Last updated on