Deja de promptar, comienza la ingeniería: 15 principios para entregar a tu agente de IA a la producción

Introduction

Al principio, simplemente intenta comunicarse con ChatGPT a través de la API, lanza un par de líneas de contexto, y se siente asombrado de que responda en absoluto.

Así nace un agente.

Si también has pasado el último año agrupando agentes de scripts y envases, experimentando y tinkering, y todavía estás buscando una forma más limpia y más sostenible de construirlos, este artículo es para ti. he vagado a través de repos y foros, preguntándome repetidamente, “¿Cómo lo hacen los demás?” > He mantenido lo que estaba pegado - lo que realmente se sintió justo después de algún uso real, y gradualmente destilado un conjunto de principios básicos para convertir una buena idea en una solución lista para la producción.

Piense en ello como una hoja de cheat práctica: una colección de principios de ingeniería que ayudan a guiar a un agente de la caja de arena a la producción: de un simple envuelto de API a un sistema estable, controlable y escalable.

Disclaimer

enEste artículo(Construyendo agentes eficaces), Anthropic define a un agente como un sistema en el que los LLM dirigen dinámicamente sus propios procesos y el uso de herramientas, manteniendo el control sobre cómo cumplen las tareas. Sistemas en los que los LLM y las herramientas se orquestran a través de rutas de código predefinidas que llaman flujos de trabajo.

En este texto, Agente = Sistema de Agentes, donde por el bien de la estabilidad y el control me inclinaré más a menudo hacia los Flujos de Trabajo.Espero que en un futuro cercano haya 1-2 turnos más de la evolución y los verdaderos Agentes serán omnipresentes, pero por el momento esto no es el caso

1. Design the Foundation

Las versiones tempranas de los agentes suelen reunirse rápidamente: unas pocas funciones, un par de prompts - y hey, funciona.

Las versiones tempranas de los agentes suelen reunirse rápidamente: unas pocas funciones, un par de prompts - y hey, funciona.

“If it works, why make it complicated?”

Al principio, todoPareceEstable.El agente responde, ejecuta código, se comporta de manera sensata.Pero una vez que cambie el modelo, reinicie el sistema o conecte una nueva interfaz, de repente se vuelve inestable, impredecible, difícil de borrar.

Y a menudo, la causa raíz no está en la lógica o las indicaciones, sino mucho antes: gestión de la memoria roto, personal de código duro, ninguna manera de retomar las sesiones, o un único punto de entrada rígido.

This section walks through four key principles that will help you build a solid foundation — one that everything else can safely grow on top of.

1. Keep State Outside

Problem:

1. Si el agente se interrumpe (un accidente, un temporal, lo que sea), debe ser capaz de recoger exactamente dónde se detuvo.
2. Necesitas una manera de reproducir con precisión lo que sucedió - para la prueba, el borrado y otros placeres similares.

Este no es estrictamente un problema, pero sin embargo:

3. Paralelización. tarde o temprano usted va a querer paralelizar la lógica del agente. Tal vez necesita para comparar múltiples opciones en medio de diálogo (“¿Cuál de estos es mejor?”).

(La memoria es un tema completamente separado - vamos a llegar a eso pronto)

Solution:Movimiento Estadooutsideel agente - en una base de datos, una caché, una capa de almacenamiento - incluso un archivo JSON lo hará.

Checklist:

• El agente puede ser lanzado desde cualquier paso, teniendo solo un session_id —el identificador de sesión— y estado externo (por ejemplo, pasos guardados en una base de datos o archivo JSON).En cualquier etapa, puede interrumpir el trabajo del agente, reiniciarlo (incluso después de cambiar algo bajo el capó), y funcionará como si nada hubiera pasado
• Caso de prueba: un agente interrumpido no pierde el contexto, después de reiniciar el resultado es el mismo
• Estado es serializable en cualquier momento sin pérdida de funcionalidad
• Puede enviar el estado a varias instancias en paralelo en medio de un diálogo

2. Make Knowledge External

ProblemLos LLMs no recuerdan. Incluso dentro de una sola sesión, el modelo puede olvidar lo que ya has explicado, mezclar etapas, perder el hilo de la conversación, o comenzar a "enchufar" detalles que no estaban allí. Y parece que el tiempo pasa, la ventana de contexto crece más y más grande, encantándonos con nuevas posibilidades. LinkedIn está llena de publicaciones donde la gente compara qué libro o cuántas horas de vídeo de YouTube ahora se ajustan a la nueva versión del modelo.

Especialmente si:

• El diálogo es largo
• Los documentos son amplios
• Las instrucciones son complejas
• y los tokens todavía no son infinitos

Incluso con el aumento de las ventanas de contexto (8k, 16k, 128k...), los problemas permanecen:

• "Lost in the middle" - el modelo presta más atención al comienzo y al final (y puede soltar detalles desde el medio)
• Coste - más tokens = más dinero;
• Y todavía no se ajusta. lo que significa que habrá pérdida, distorsión o alucinaciones. Mientras los transformadores trabajen en la autoatención con complejidad cuadrada (O(n2)), esta limitación estará con nosotros.

Solution:Separar la "memoria de trabajo" de la "almacenamiento" - como en los sistemas de computación clásicos. El agente debe ser capaz de trabajar con la memoria externa: almacenar, recuperar, resumir y actualizar el conocimiento fuera del modelo.

Approaches

Memory Buffer

Las tiendas más recienteskEnvío rápido de prototipos.

+sencillo, rápido, suficiente para tareas cortas

-pierde información importante, no escala, no recuerda “ayer”

Summarization Memory

Comprimir la historia para que se ajuste más.

+Ahorro de token, expansión de la memoria

-distorsiones, pérdida de matices, errores en la compresión en múltiples pasos

RAG (Retrieval-Augmented Generation)

Retira conocimientos de bases de datos externas. La mayor parte del tiempo estarás aquí.

+Escalable, fresco y verificable

-configuración compleja, sensible a la calidad de recuperación, latencia

Knowledge Graphs

Relaciones estructuradas entre entidades y hechos.Siempre elegante, sexy y duro, acabarás haciendo RAG de todos modos.

+Lógica, explicabilidad y estabilidad

-alta barrera a la entrada, la complejidad de la integración LLM

Checklist:

• Todo el historial de conversaciones es accesible en un solo lugar (fuera del prompt)
• Las fuentes de conocimiento se registran y se pueden reutilizar
• Escalas de historia sin riesgo de exceder la ventana de contexto

3. Model as a Config

Problem:Los LLM están evolucionando rápidamente; Google, Anthropic, OpenAI, etc. constantemente lanzan actualizaciones, compitiendo entre sí a través de diferentes índices de referencia. Esta es una fiesta para nosotros como ingenieros, y queremos aprovechar al máximo.

Solution:

1. Implementar la configuración model_id: Utilice un parámetro model_id en los archivos de configuración o en las variables de entorno para especificar el modelo que se utiliza.
2. Uso de interfaces abstractas: Crea interfaces o clases de envoltorios que interactúan con modelos a través de una API unificada.
3. Aplicar soluciones de middleware (cuidado - hablaremos de frameworks un poco más tarde)

Checklist:

• La sustitución del modelo no afecta al resto del código y no afecta a la funcionalidad del agente, la orquestación, la memoria o las herramientas.
• La adición de un nuevo modelo sólo requiere configuración y, opcionalmente, un adaptador (una capa simple que lleva el nuevo modelo a la interfaz requerida)
• You can easily and quickly switch models. Ideally—any models, at minimum—switching within a model family

4. One Agent, Many Interfaces: Be Where the Users Are

Problem:Incluso si inicialmente el agente está destinado a tener solo una interfaz de comunicación (por ejemplo, UI), eventualmente querrá dar a los usuarios más flexibilidad y conveniencia añadiendo interacción a través de Slack, WhatsApp, o, me atrevo a decirlo, SMS - lo que sea. Una API puede convertirse en un CLI (o lo querrás para el desgaste). Construye esto en su diseño desde el principio; haz que sea posible usar su agente donde sea conveniente.

Solution: Creating a unified input contractDesarrollar una API u otro mecanismo que sirva como una interfaz universal para todos los canales.

Checklist:

• Agent is callable from CLI, API, UI

• All input goes through a single endpoint/parser/schema

• All interfaces use the same input format

• No channel contains business logic

• Adding a new channel = only an adapter, no changes to core

  
  

  

  
  

Definición del comportamiento del agente

Aunque sólo hay una tarea, todo es simple, como en los mensajes de los evangelistas de la IA. Pero tan pronto como añadas herramientas, lógica de toma de decisiones y múltiples etapas, el agente se convierte en un desorden.

Aunque sólo hay una tarea, todo es simple, como en los mensajes de los evangelistas de la IA. Pero tan pronto como añadas herramientas, lógica de toma de decisiones y múltiples etapas, el agente se convierte en un desorden.

Se pierde la pista, no sabe qué hacer con los errores, se olvida de llamar la herramienta correcta, y usted se queda solo de nuevo con los registros donde "bien, todo parece estar escrito allí".

Para evitar esto, el agente necesita un clarobehavioral model¿Qué hace, qué herramientas tiene, quién toma decisiones, cómo intervienen los humanos y qué hacer cuando algo va mal?

Esta sección cubre los principios que le ayudarán a dar a su agente una estrategia de acción coherente en lugar de esperar que "el modelo lo descubra de alguna manera".

5. Design for Tool Use

Problem:Este punto puede parecer obvio, pero todavía se encuentran con agentes construidos sobre "Plain Prompting + Raw LLM output parsing." Es como tratar de controlar un mecanismo complejo tirando cuerdas aleatorias y esperando lo mejor.

• Fragilidad: El menor cambio en la formulación de la respuesta de LLM (una palabra añadida, el orden de la frase cambiada) puede romper todo el análisis.
• Ambigüedad: El lenguaje natural es inherentemente ambiguo.Lo que parece obvio a un ser humano puede ser un rompecabezas para un analista. "Call John Smith" —¿cuál de los tres John Smith en su base de datos? ¿Cuál es su número?
• Complejidad de mantenimiento: El código de análisis crece, se vuelve confuso y difícil de debutar.Cada nuevo agente "habilidad" requiere la escritura de nuevas reglas de análisis.
• Capacidades limitadas: es difícil hacer que el modelo llame de forma confiable a varias herramientas o pase estructuras de datos complejas a través de la salida de texto simple.

Solution:El modelo devuelve JSON (o otro formato estructurado) — el sistema ejecuta.

The key idea here is to leave the responsibility for Interpretación user intent and Elegirinstrumentos para el LLM, mientras que aún asignando elejecuciónDe esa intención a laEl sistemaa través de una interfaz definida.

Afortunadamente, prácticamente todos los proveedores (OpenAI, Google, Anthropic, o cualquiera que usted prefiere) soportan los llamados"function calling"o la capacidad de generar la salida en un formato JSON estrictamente definido.

Sólo para refrescar cómo funciona:

1. Descripción de la herramienta: Define funciones (herramienta) como JSON Schema con nombre, descripción, parámetros.
2. Pasar a LLM: En cada llamada, el modelo recibe esquemas de herramientas junto con el prompt.
3. Model output: Instead of text, the model returns JSON with:
   • name of the function to call
   • arguments—parameters according to schema
4. Ejecución: El código valida JSON y llama la función apropiada con parámetros.
5. Respuesta Modelo (opcional): El resultado de ejecución se transmite de vuelta a LLM para la generación de respuesta final.

Important:Las descripciones de herramientas también son prompts. Descripción inequívoca = elección incorrecta de la función.

What to do without function calling?

Si el modelo no soporta las llamadas de herramientas o desea evitarlas por alguna razón:

• Ask the model to return JSON in the prompt. Be sure to specify the format; you can add examples.
• Analizar la respuesta y validarlo con algo como Pydantic.

Checklist:

• La respuesta está estrictamente formalizada (por ejemplo, JSON)
• Se utilizan esquemas (JSON Schema o Pydantic)
• Validation is applied before function calls
• Errores de generación no causan interrupción (el manejo de errores de formato existe)
• LLM = elección de la función, ejecución = código

6. Own the Control Flow

Problem:Usualmente los agentes funcionan como "diálogos" - primero el usuario habla, luego el agente responde.Es como jugar a ping-pong: respuesta a golpes.

Such an agent cannot:

• Hacer algo por sí mismo sin una solicitud
• Realizar acciones en paralelo
• Planificar los pasos con antelación
• Hacer varios pasos en secuencia
• Comprobar el progreso y volver a los pasos fallidos

En su lugar, el agente debe gestionar su propio "flujo de ejecución" - decidir qué hacer a continuación y cómo hacerlo.

This means the agent:

• Decide cuándo hacer algo por sí mismo
• Puede dar pasos uno tras otro
• Puede retrasar los pasos fallidos
• Puede cambiar entre tareas
• Puede trabajar incluso sin solicitudes directas

Solution:En lugar de dejar que el LLM controle toda la lógica, extraemos lacontrol flowEl modelo solo ayuda dentro de los pasos o sugiere el siguiente.engineering a systemCon un comportamiento controlado.

Veamos tres enfoques populares:

1. FSM (Finite State Machines)

• Qué es: Tareas divididas en estados y transiciones claras.
• LLM: Determina el siguiente paso o actúa dentro de un estado.
• Pros: Simplicidad, predictibilidad, bueno para escenarios lineales.
• Herramientas: StateFlow, configuraciones YAML, patrón de estado.

2. DAG (Directed Graphs)

• Tareas no lineales o paralelas como gráfico: los nodos son acciones, los bordes son dependencias.
• LLM: Puede ser un nodo o ayuda con la construcción de planes.
• Pros: Flexibilidad, paralelismo y visualizabilidad.
• Herramientas: LangGraph, Trellis, LLMCompiler, diagramas DAG personalizados.

3. Planner + Executor

• Qué es: LLM construye un plan, código u otros agentes lo ejecutan.
• LLM: "Big" uno planes, "pequeños" los ejecutan.
• Pros: Separación de preocupaciones, control de costes, escalabilidad.
• Herramientas: Plan y ejecución de cadena larga.

Why this matters:

• Aumenta la controlabilidad, la fiabilidad y la escalabilidad.
• Permite combinar diferentes modelos y acelerar la ejecución.
• El flujo de tareas se vuelve visualizable y probable.

Checklist:

• Utiliza FSM, DAG o escenario con transiciones explícitas
• Model decides what to do but doesn't control the flow
• El comportamiento puede ser visualizado y probado
• El manejo de errores está construido en el flujo

7. Include the Human in the Loop

Problem:Incluso si un agente utiliza herramientas estructuradas y tiene un flujo de control claro, la plena autonomía de los agentes de LLM en el mundo real es todavía más de un sueño (o pesadilla, dependiendo del contexto). LLMs no poseen una verdadera comprensión y no son responsables de nada.

Main risks of full autonomy:

• Permanent mistakes: The agent might perform actions with serious consequences (delete data, send an incorrect message to an important client, start a robot uprising).
• Violaciones de conformidad: El agente podría violar accidentalmente las regulaciones internas, los requisitos legales o lesionar los sentimientos del usuario (si ese no era el plan, ignore este punto).
• Falta de sentido común y ética: LLMs pueden perder los matices sociales o actuar en contra del "sentido común".
• Pérdida de la confianza del usuario: Si el agente comete errores frecuentes, los usuarios dejarán de confiar en él.
• Complejidad de la auditoría y de la responsabilidad: ¿Quién es el culpable cuando un agente autónomo "cruza"?

Solution: Convocatoria estratégica de formas de vida basadas en carbonoIntegración de las personas en el proceso de toma de decisiones en las etapas clave.

HITL Implementation Options

1. Approval Flow

• Cuando: la acción es crítica, costosa, irreversible
• Cómo: el agente formula una propuesta y espera la confirmación

2. Confidence-aware Routing

• Cuando: El modelo es incierto
• How:
  • self-assessment (logits, LLM-as-a-judge, P(IK))
  • escalation when confidence falls below threshold

3. Human-as-a-Tool

• Cuando: datos insuficientes o formulario de solicitud inexplicable
• Cómo: el agente pide aclaraciones (por ejemplo, HumanTool en CrewAI)

4. Fallback Escalation

• Cuando: error repetido o situación irresoluble
• Cómo: la tarea se pasa a un operador con contexto

5. RLHF (Human Feedback)

• Cuándo: para la mejora del modelo
• Cómo: los humanos evalúan las respuestas, se entrenan

Checklist:

• Acciones que requieren aprobación se definen
• Existe un mecanismo de evaluación de la confianza
• El agente puede hacer preguntas humanas
• Las acciones críticas requieren confirmación
• Existe una interfaz para introducir respuestas

8. Compact Errors into Context

Problem:El comportamiento estándar de muchos sistemas cuando se produce un error es "crasar" o simplemente informar del error y detener. Para un agente que debería resolver tareas de forma autónoma, este no es exactamente el mejor modelo de comportamiento.

Lo que vamos a enfrentar:

• Fragilidad: Cualquier fallo en una herramienta externa o respuesta inesperada de LLM puede detener todo el proceso o llevarlo a la confusión.
• Ineficiencia: los reinicios constantes y la intervención manual consumen tiempo y recursos.
• Incapacidad de aprender (en el sentido amplio): Si el agente no "ve" sus errores en el contexto, no puede tratar de corregirlos o adaptar su comportamiento.
• Las alucinaciones, de nuevo

Solution:Los errores están incluidos en la prompt o la memoria.La idea es intentar implementar algún tipo de "auto-curación".El agente debe al menos tratar de corregir su comportamiento y adaptarse.

El Rough Flow:

• Comprender el error
• Self-correction:
  • Self-correction mechanisms: Error Detection, Reflection, Retry Logic, Retry with changes (Agent can modify request parameters, rephrase the task, or try a different tool)
  • Impact of reflection type: More detailed error information (instructions, explanations) usually leads to better self-correction results. Even simple knowledge of previous errors improves performance.
  • Internal Self-Correction: Training LLMs for self-correction by introducing errors and their fixes into training data.
• Solicitar ayuda humana: Si la auto-corrección falla, el agente escala el problema a un humano (ver Principio 7).

Checklist:

• El error del paso anterior se guarda en el contexto
• Retry logic exists
• Fallback/escalada humana se utiliza para fracasos repetidos

9. Break Complexity into Agents

Problem: Let's back to the key LLM limitation (that context window thing), but look at this problem from another angle. The bigger and more complex the task, the more steps it will take, which means a longer context window. As context grows, LLMs are more likely to get lost or lose focus. By focusing agents on specific domains with 3-10, maybe maximum 20 steps, we maintain manageable context windows and high LLM performance.

Solution:Usar agentes más pequeños dirigidos a tareas específicas.Un agente = una tarea; orquestación desde arriba.

Beneficios de los agentes pequeños y enfocados:

• Contexto gestionable: ventanas de contexto más pequeñas significan un mejor rendimiento del LLM
• Responsabilidades claras: Cada agente tiene un alcance y propósito bien definidos
• Mejora de la fiabilidad: menor probabilidad de perderse en flujos de trabajo complejos
• Pruebas más sencillas: es más fácil probar y validar la funcionalidad específica
• Improved debugging: Easier to identify and fix problems when they arise

Desafortunadamente, no hay una heurística clara para comprender cuando una pieza de lógica ya es lo suficientemente grande como para dividirse en múltiples agentes. Estoy bastante seguro de que mientras estás leyendo este texto, los LLM se han vuelto más inteligentes en algún lugar en los laboratorios. Y siguen mejorando y mejorando, por lo que cualquier intento de formalizar este límite está condenado desde el principio. Sí, cuanto más pequeña sea la tarea, más simple sea, pero cuanto más grande sea, mejor se realiza el potencial. La intuición correcta solo vendrá con experiencia. Pero eso no está seguro.

Checklist:

• Scenario is built from microservice calls

• Agents can be restarted and tested separately

• Agent = minimal autonomous logic. You can explain what it does in 1-2 sentences.

  
  

  

  
  

Modelo de interacción de control

El modelo maneja la generación.Todo lo demás depende de ti.

The model handles generation. Everything else is on you.

Cómo formulaste la solicitud, qué pasaste en el contexto, qué instrucciones dichas, todo esto determina si el resultado será coherente o "creativo".

Los LLM no leen las mentes, leen los tokens.

Lo que significa que cualquier error de entrada se convierte en un error de salida, simplemente no inmediatamente notable.

Esta sección trata de no dejar que todo fluya: prompts = código, gestión explícita del contexto, restringir el modelo dentro de los límites.

10. Treat Prompts as Code

Problem:Un patrón muy común, especialmente entre las personas sin antecedentes ML o SE, es el almacenamiento de prompts directamente en el código o, en el mejor de los casos, almacenamiento no sistemático en archivos externos.

Este enfoque lleva a varias dificultades de mantenimiento y escalación:

• La navegación, la comprensión y la modificación se vuelven complicadas a medida que crece la complejidad del proyecto y el número de solicitudes.
• Sin versiones explícitas, es muy difícil rastrear la evolución inmediata, las razones de los cambios y volver a las versiones estables anteriores en caso de degradación del rendimiento.
• Proceso ineficiente de mejora y depuración: La optimización rápida sin métricas y pruebas objetivas se convierte en un proceso subjetivo e intensivo de trabajo con resultados inestables.
• La percepción por otros miembros del equipo se vuelve complicada, incluyendo (y especialmente) el futuro de usted.

Solution:Prompts en este contexto no son muy diferentes del código y las mismas prácticas de ingeniería básica deben aplicarse a ellos.

This implies:

• Almacenar separadamente y sistemáticamente, utilizando archivos especializados (como .txt, .md, .yaml, .json) o incluso sistemas de gestión de plantillas (por ejemplo, Jinja2, Handlebars, o herramientas especializadas como BAML).
• Puede incluso hacer pruebas A/B con diferentes versiones después de esto.
• Testing. You heard that right.
  • This could be something like unit tests, where you compare LLM responses to specific inputs against reference answers or expected characteristics depending on the prompt
  • Evaluation datasets
  • Format compliance checks and presence/absence of key elements - For example, if a prompt should return JSON, the test can validate its structure
  • Even LLM-as-a-judge if your project and design justify it.

Hablaremos de las pruebas con más detalle en el principio 14.

Checklist:

• Los prompt se almacenan en archivos separados, separados de la lógica de negocio
• Hay difusión y cambio de historia
• Las pruebas se utilizan (si es necesario)
• (Opcional) ¿Qué pasa con la revisión rápida como parte de la revisión de código?

11.Ingeniería de Contexto

Problem:Ya hemos discutido la "olvidabilidad" de los LLMs, solucionando parcialmente esto descargando el historial a la memoria externa y utilizando diferentes agentes para diferentes tareas. pero eso no es todo.

Standard formats aren't always optimal:Una simple lista de mensajes en el "contenido de rol" (system/user/assistantEl formato es la línea de partida, pero puede ser token-pesado, no suficientemente informativo, o pobre en transmitir el estado complejo de su agente.

La mayoría de los clientes de LLM utilizan el formato de mensaje estándar (una lista de objetos conrole: “sistema”, “usuario”, “asistente”,content, and sometimes tool_callslos campos).

Si bien esto "funciona bien para la mayoría de los casos", paramaximum efficiency(en términos de los tokens y la atención del modelo), podemos abordar la formación de contexto de manera más creativa.

Solution:Para tratar la creación de todo el paquete de información pasado al LLM como"Context Engineering."Esto significa:

1. Control total: Tomar la propiedad total de qué información entra en la ventana de contexto del LLM, en qué forma, volumen y secuencia.
2. Crear formatos personalizados: No limitarnos a listas de mensajes estándar. Desarrollar nuestras propias formas optimizadas para la tarea de representar el contexto. Por ejemplo, podrías considerar usar una estructura similar a XML para empacar densamente varios tipos de información (mensajes, llamadas a herramientas, sus resultados, errores, etc.) en uno o varios mensajes.
3. Enfoque holístico: Ver el contexto no sólo como un historial de diálogo, sino como la suma total de todo lo que el modelo podría necesitar: la solicitud inmediata, instrucciones, datos de los sistemas RAG, el historial de las llamadas de herramientas, el estado del agente, la memoria de otras interacciones e incluso instrucciones sobre el formato de salida deseado.

(Instead of a checklist) How do you know when this makes sense?

Si te interesa alguno de los siguientes:

• Densidad de información: máximo significado con mínimo ruido.
• Reducción del número de tokens donde podemos obtener calidad comparable por un precio más bajo.
• Improved Error Handling.
• Gestionar la inclusión de información sensible, controlarla, filtrarla, y terminar todo con la respuesta clásica "disculpa, soy sólo un modelo de lenguaje pequeño y grande".

12. Constrain the Chaos: Secure Inputs, Guarded Actions, and Grounded Outputs

Problem:Ya hemos hecho mucho en nombre de la estabilidad, pero nada es una bala de plata. Esto significa que vale la pena mirar los problemas potenciales más críticos por separado y tomar explícitamente algún "seguro".

En este principio, pensamos en:

• Posible inyección de prompt. Si su agente va a comunicarse directamente con un usuario, debe controlar lo que se alimenta como entrada. Dependiendo del tipo de usuario, puede obtener uno que quiere romper su flujo y forzar al agente a ignorar sus objetivos iniciales, proporcionar la información incorrecta, realizar acciones dañinas o generar contenido malicioso.
• Por la razón anterior, o guiado por "voz en la cabeza", el agente puede revelar información importante, como datos personales de los usuarios, secretos corporativos, etc.
• Generación de contenido tóxico o malicioso.Si esto es por diseño, ignore este punto.
• Hacer las cosas cuando la información está ausente. el dolor eterno.
• Pero en serio, en su proceso de razonamiento, el agente podría llegar a soluciones muy no triviales, no todas de las cuales estarán dentro del alcance del comportamiento normal.

La seguridad y el aterrizaje de un agente LLM no es una medida única, sino un sistema de protección de múltiples capas ("defence-in-depth") que cubre todo el ciclo de vida de la interacción. Las amenazas son diversas, y ningún único método de protección es una panacea.

Solution:Debemos comprometernos a un sistema de defensa de múltiples capas, pensando y tratando explícitamente todos los casos de esquina y posibles escenarios, y teniendo una respuesta clara preparada para lo que pueda suceder.

En una configuración básica, debes considerar:

1. Secure Inputs.

   1. Check for known attack-indicator phrases (e.g., "ignore all previous instructions"). It sometimes makes sense to combat potential obfuscation.
   2. Try to determine the user's intent separately. You can use another LLM for this, to analyze the input for the current one.
   3. Control input from external sources, even if they are your own tools.

2. Guarded Actions. Control the privileges of both the agent and its tools (granting the minimum necessary), clearly define and limit the list of available tools, validate parameters at the input to tools, and enable Principle #7 (Human in the Loop).

3. Output Moderation. Design a system of checks for what the model outputs, especially if it goes directly to the user. These can be checks for relevance (ensuring the model uses what's in the RAG and doesn't just make things up) as well as checks for general appropriateness. There are also ready-made solutions (e.g., the OpenAI Moderation API).

El sistema final, sin embargo, depende de sus tareas y su evaluación de riesgos. En la lista de verificación, intentaremos esbozar algunas opciones.

Checklist:

• User input validation is in place.

• For tasks requiring factual information, the data within the RAG is used.

• The prompt for the LLM in a RAG system explicitly instructs the model to base its answer on the retrieved context.

• LLM output filtering is implemented to prevent PII (Personally Identifiable Information) leakage.

• The response includes a link or reference to the source.

• LLM output moderation for undesirable content is implemented.

• The agent and its tools operate following the principle of least privilege.

• The agent's actions are monitored, with HITL (Human-in-the-Loop) for critical operations.

  
  

  

  
  

IV. Keep It Alive

Un agente que "kinda funciona" es un error con un efecto retrasado.

Un agente que "kinda funciona" es un error con un efecto retrasado.

En prod, no todo se rompe de una vez. Y no se entera de ello de inmediato. A veces, no se entera del todo.

Este artículo trata sobre el hábito deseeing what's happeningychecking that everything is still workingLogs, rastreo, pruebas: todo lo que hace que el comportamiento de un agente sea transparente y fiable, incluso cuando usted está durmiendo o desarrollando su siguiente agente.

13. Trace Everything

Problem:De una manera u otra, usted se enfrentará constantemente a situaciones en las que el agente no funciona como se esperaba. Durante el desarrollo, la prueba, hacer cambios, o durante el funcionamiento normal. Esto es inevitable, y en este momento, es normal en cierta medida. Esto significa que está condenado a pasar horas y días debugando, tratando de entender lo que está mal, reproducir el problema, y arreglarlo. Me gustaría pensar que en este punto ya ha implementado el Principio #1 (Keep State Outside) y #8 (Compact Errors into Context). En la mayoría de los casos, eso será suficiente para hacer que su vida sea mucho más simple.

Aun así (y especialmente si ha decidido no molestar con ellos por ahora), tiene mucho sentido pensar en el desmantelamiento de antemano y ahorrarse tiempo y nervios en el futuro al adherirse a este principio.

Solution:Regístrate todo el camino de la solicitud a la acción. Incluso si ya tienes registros para componentes individuales, rastrear la cadena entera puede ser un problema. Incluso si eres un gran fan de rompecabezas o Lego, en algún momento, dejará de ser divertido. Por lo tanto, los registros deben existir, deben ser de fin a fin, y deben cubrir todo.

Why it's needed:

• Debugging – Descubra rápidamente dónde las cosas se han equivocado.
• Análisis — Ver dónde están las barreras y cómo mejorar.
• Evaluación de la calidad: ver cómo los cambios afectan al comportamiento.
• Reproducibilidad: Puede reconstruir con precisión los pasos.
• Auditoría: un registro de todas las decisiones y acciones de los agentes.

El "set de gentleman" básico se ve así:

• Entrada: La solicitud de usuario inicial, los parámetros recibidos del paso anterior.
• Estado del agente: Variables clave del estado del agente antes de ejecutar el paso.
• Prompt: El texto completo del prompt enviado al LLM, incluyendo instrucciones del sistema, historial de diálogo, contexto RAG recuperado, descripciones de herramientas, etc.
• LLM Output: La respuesta completa y cruda del LLM, antes de cualquier análisis o procesamiento.
• Call de herramientas: Si el LLM decidió llamar a una herramienta – el nombre de la herramienta y los parámetros exactos con los que se llamó (de acuerdo con la salida estructurada).
• Resultado de la herramienta: La respuesta que la herramienta devuelve, incluyendo tanto resultados exitosos como mensajes de error.
• Decisión del agente: qué decisión tomó el agente basándose en la respuesta del LLM o el resultado de la herramienta (por ejemplo, qué paso siguiente realizar, qué respuesta dar al usuario).
• Metadatos: el tiempo de ejecución de los pasos, el modelo de LLM utilizado, el coste de la llamada (si está disponible), la versión de código / prompt.

Note:Eche un vistazo a las herramientas de seguimiento existentes; bajo ciertas condiciones, te harán la vida mucho más fácil. LangSmith, por ejemplo, proporciona una visualización detallada de las cadenas de llamadas, llamadas, respuestas y uso de herramientas. También puedes adaptar herramientas como Arize, Weights & Biases, OpenTelemetry, etc. a tus necesidades.

Checklist:

• Todos los pasos del agente se registran (su versión del "set de gentleman").
• Los pasos están vinculados por un session_id y un step_id.
• Hay una interfaz para ver toda la cadena.
• La solicitud enviada al LLM puede reproducirse en cualquier etapa.

14. Test Before You Ship

Problem:Por este punto, es probable que tengas algún tipo de solución prácticamente acabada. Funciona, tal vez incluso de la manera que deseabas. ¿Lo envías a la producción? Pero cómo lo aseguramos?Mantenimiento¿Funciona? Incluso después de la próxima actualización menor? Sí, nos estoy llevando al tema de las pruebas.

Obviamente, las actualizaciones en los sistemas LLM, al igual que en cualquier otro, ya sea cambios en el código de la aplicación, actualizaciones a los conjuntos de datos para ajustes finos o RAG, una nueva versión del LLM básico, o incluso pequeños ajustes de instrucciones, a menudo conducen a interrupciones involuntarias en la lógica existente y comportamiento inesperado, a veces degradante, de los agentes.

• Model Drift. Usted no ha hecho nada, pero el rendimiento ha disminuido con el tiempo. Tal vez el proveedor ha actualizado su modelo, tal vez la naturaleza de los datos de entrada ha cambiado (drift de datos) - lo que funcionó ayer podría dejar de funcionar hoy.
• Incluso un pequeño cambio en un prompt puede romper la lógica establecida y distorsionar la salida.
• No-determinismo de los LLM: Como sabes, muchos LLM son no-deterministas (especialmente con temperatura > 0), lo que significa que generarán respuestas diferentes a la misma entrada en cada llamada.
• Será más fácil para usted si ha implementado el primer principio, pero reproducir un error específico para el borrado puede ser difícil incluso con datos y estados fijos.
• En sistemas complejos, la actualización de un único elemento (como un modelo o un prompt) puede cascarse a través de una cadena de APIs, bases de datos, herramientas, etc., y conducir a un cambio en el comportamiento en otros lugares.
• Las alucinaciones.

Pero ya entendemos que las pruebas tradicionales, centradas en verificar la lógica del código explícito, no son plenamente capaces de cubrir estos problemas.

Solution:Tendremos que diseñar un enfoque complejo y integral que cubra muchas cosas, combinando soluciones clásicas y específicas de dominio.

• Pruebas de varios niveles: Una combinación de diferentes tipos de pruebas que se dirigen a diversos aspectos del sistema: desde pruebas de unidades de bajo nivel para funciones individuales y prompts a escenarios complejos que verifican el flujo de trabajo de fin a fin del agente y la interacción del usuario.
• Concentrarse en el comportamiento y la calidad del LLM: La prueba debe evaluar no solo la corrección funcional, sino también las características cualitativas de las respuestas del LLM, como la relevancia, la exactitud, la coherencia, la ausencia de contenido perjudicial o vicioso, y la adhesión a las instrucciones y un estilo dado.
• Pruebas de regresión y calidad que incluyen "conjuntos de datos de oro" que contienen ejemplos de entrada diversos y referencias (o intervalos aceptables de) resultados.
• Automatización e integración en CI/CD.
• Evaluación humana: Las etapas específicas de LLM-eval deben involucrar a un humano para calibrar las métricas y revisar casos complejos o críticos.
• Un enfoque iterativo para el desarrollo y las pruebas rápidas: La ingeniería de prompt debe ser tratada como un proceso iterativo en el que cada versión de un prompt es minuciosamente probada y evaluada antes de la implementación.
• Testing at different levels of abstraction:
  • Component testing: Individual modules (parsers, validators, API calls) and their integration.
  • Prompt testing: Isolated testing of prompts on various inputs.
  • Chain/Agent testing: Verifying the logic and interaction of components within an agent.
  • End-to-end system testing: Evaluating the completion of full user tasks.

Checklist:

• Logic is broken down into modules: functions, prompts, APIs—everything is tested separately and in combination.

• Response quality is checked against benchmark data, evaluating meaning, style, and correctness.

• Scenarios cover typical and edge cases: from normal dialogues to failures and provocative inputs.

• The agent must not fail due to noise, erroneous input, or prompt injections—all of this is tested.

• Any updates are run through CI and monitored in prod—the agent's behavior must not change unnoticed.

  

Principle 15: Own the Execution Path

Este es un meta-principio; se ejecuta a través de todos los mencionados anteriormente.

Afortunadamente, hoy tenemos docenas de herramientas y marcos para cualquier tarea. Esto es genial, es conveniente, y es una trampa.

Casi siempre, elegir una solución preparada significa unatrade-off: obtiene la velocidad y un comienzo fácil, pero pierdeflexibility, control, and, potentially, security.

Esto es especialmente crítico en el desarrollo de agentes, donde es importante gestionar:

• la impredecibilidad de los LLM,
• lógica compleja para las transiciones y la auto-corrección,
• estar preparado para la adaptación y evolución del sistema, incluso si sus tareas centrales permanecen sin cambios.

El marco traeinversion of controlEsto puede simplificar un prototipo pero complicar su desarrollo a largo plazo.

Muchos de los principios descritos anteriormente se pueden implementar utilizando soluciones fuera de la estantería, y esto a menudo es justificado.explicit implementation of the core logic takes a comparable amount of timeOfrece incomparablemente mástransparency, manageability, and adaptability.

El extremo opuesto también existe -over-engineering, el deseo de escribir todo desde cero. Esto también es un error.

This is why the key is balance.El ingeniero elige por sí mismo: donde es razonable confiar en un marco, y donde es importante mantener el control.

Tienes que recordar: la industria todavía está tomando forma.Muchas herramientas se crearon antes de que surgieran los estándares actuales.Mañana, podrían convertirse en obsoletas, pero las limitaciones que se encuentran en tu arquitectura hoy permanecerán.

Conclusion

Bueno, hemos pasado por encima de 15 principios que, según la experiencia, ayudan a convertir la emoción inicial de "¡es vivo!" en la confianza de que su agente LLM trabajará de una manera estable, predecible y útil bajo condiciones del mundo real.

Debe considerar cada uno de ellos para ver si tiene sentido aplicarlo a su proyecto.Al final, es su proyecto, su tarea y su creación.

Key takeaways to carry with you:

1. Un enfoque de ingeniería es clave: No confíe en la "magia" de los LLM. Estructura, predictibilidad, gestionabilidad y probabilidad son sus mejores amigos.
2. El LLM es un componente poderoso, pero todavía sólo un componente: Tratar el LLM como un componente muy inteligente, pero sin embargo, único de su sistema.
3. La iteración y el feedback son las claves del éxito: es raro crear el agente perfecto en el primer intento. Estar preparado para experimentos, mediciones, análisis de errores y mejora continua, tanto del agente mismo como de sus procesos de desarrollo.
4. Comunidad y apertura: El campo de los agentes de LLM está evolucionando rápidamente. Mantenga un ojo en la nueva investigación, herramientas y mejores prácticas, y compartir sus propias experiencias.

Espero que hayas encontrado algo nuevo y útil aquí, y tal vez incluso quieras volver a esto mientras diseñas tu próximo agente.