El agente que no conoces: principios, arquitectura y prácticas de ingeniería

0. TL;DR

Después de escribir "El Claude Code que no conoces: Arquitectura, Gobernanza y Prácticas de Ingeniería", me di cuenta de que mi comprensión de las capas subyacentes de los Agentes no era lo suficientemente profunda. Combinado con la experiencia significativa de nuestro equipo en la implementación de soluciones empresariales basadas en Agentes, sentí la necesidad de una revisión sistemática. Así que revisé materiales, implementaciones de código abierto y mi propio código para organizar este artículo.

Este artículo se centra en las partes de la arquitectura de Agentes que más impactan los resultados de ingeniería, incluyendo el flujo de control, la ingeniería de contexto, el diseño de herramientas, la memoria, la organización multiagente, la evaluación, el trazado y la seguridad. Finalmente, usaremos la implementación de OpenClaw para unir estos principios de diseño.

Al organizar esto, varias conclusiones difirieron de mis suposiciones iniciales: las mejoras que aportan los modelos más costosos suelen ser menores de lo esperado; en cambio, la calidad del arnés (Harness) y las pruebas de verificación tienen un mayor impacto en las tasas de éxito. Al depurar el comportamiento de un Agente, prioriza la revisión de las definiciones de herramientas, ya que la mayoría de los errores de selección de herramientas provienen de descripciones inexactas. Además, los problemas dentro del propio sistema de evaluación suelen ser más difíciles de detectar que los errores del Agente. Si sigues ajustando el código del Agente sin éxito, la respuesta podría estar en estas áreas.

1. Funcionamiento Básico del Bucle del Agente

La lógica de implementación central de un Bucle de Agente, cuando se abstrae, tiene menos de 20 líneas de código:

1const messages: MessageParam[] = [{ role: "user", content: userInput }];
2
3while (true) {
4  const response = await client.messages.create({
5    model: "claude-opus-4-6",
6    max_tokens: 8096,
7    tools: toolDefinitions,
8    messages,
9  });
10
11  if (response.stop_reason === "tool_use") {
12    const toolResults = await Promise.all(
13      response.content
14        .filter((b) => b.type === "tool_use")
15        .map(async (b) => ({
16          type: "tool_result" as const,
17          tool_use_id: b.id,
18          content: await executeTool(b.name, b.input),
19        }))
20    );
21    messages.push({ role: "assistant", content: response.content });
22    messages.push({ role: "user", content: toolResults });
23  } else {
24    return response.content.find((b) => b.type === "text")?.text ?? "";
25  }
26}

El flujo de control correspondiente es el siguiente: un ciclo continuo de Percepción -> Decisión -> Acción -> Retroalimentación hasta que el modelo devuelve texto plano:

Habiendo visto muchas implementaciones de Agentes y SDKs oficiales, las estructuras son similares. El bucle en sí es bastante estable. Desde una implementación mínima hasta el soporte de subagentes, compresión de contexto y carga de habilidades, el bucle principal rara vez cambia. Las nuevas capacidades generalmente se agregan fuera del bucle, no modificando su interior.

Las nuevas capacidades se integran principalmente de tres maneras: ampliando los conjuntos de herramientas y manejadores, ajustando las estructuras del prompt del sistema y externalizando el estado a archivos o bases de datos. El cuerpo del bucle no debe convertirse en una máquina de estados masiva. El modelo maneja el razonamiento, mientras que los sistemas externos manejan el estado y los límites. Una vez establecida esta división del trabajo, la lógica central del bucle rara vez necesita ajustes frecuentes.

¿Cuál es la diferencia entre Workflow y Agent?

Anthropic hace una distinción directa: un sistema donde la ruta de ejecución está preescrita en código es un Workflow; un sistema donde el LLM decide dinámicamente el siguiente paso es un Agent. La diferencia central es quién tiene el control. En realidad, muchos productos etiquetados como Agents están más cerca de Workflows, pero ninguno es inherentemente superior. Lo importante es encontrar la solución adecuada para la tarea.

Verlo en un diagrama lo hace más intuitivo:

Cinco Patrones de Control Comunes

La mayoría de los sistemas de IA, al desmontarlos, son combinaciones de estos cinco patrones. Muchos escenarios no necesitan autonomía total del Agente; combinar algunos de estos patrones es suficiente. La clave es qué diseño se adapta a la tarea.

1. Prompt Chaining: Las tareas se dividen en pasos secuenciales donde cada paso del LLM procesa la salida anterior. Se pueden agregar puntos de control de código. Adecuado para procesos lineales como traducción después de generación o escribir el cuerpo del texto después de un esquema.
2. Routing: Clasifica la entrada y la dirige a un proceso especializado. Las preguntas simples van a modelos ligeros, las complejas a modelos fuertes; las consultas de soporte técnico y facturación siguen lógicas diferentes.
3. Parallelization: Dos variantes: Sectioning (dividir tareas en subtareas independientes) y Voting (ejecutar la misma tarea varias veces para consenso). Adecuado para decisiones de alto riesgo o necesidades de múltiples perspectivas.
4. Orchestrator-Workers: Un LLM central descompone dinámicamente las tareas y las delega a LLMs trabajadores, luego sintetiza los resultados. Este es el prototipo para la herramienta spawn de nanobot y el modo subagente de learn-claude-code.
5. Evaluator-Optimizer: Un generador produce una salida, y un evaluador proporciona retroalimentación en un bucle hasta que se cumplen los estándares. Adecuado para tareas como traducción o escritura creativa donde los estándares de calidad son difíciles de definir con precisión en código.

Estos patrones resuelven cómo construir el flujo de control. Ahora veamos una pregunta más centrada en la ingeniería: ¿por qué un sistema funciona de manera estable?

2. Por qué el Harness es más Crítico que el Modelo

Un Harness se refiere a la infraestructura de pruebas, verificación y restricciones construida alrededor de un Agente. Un Harness incluye al menos cuatro partes: líneas base de aceptación, límites de ejecución, señales de retroalimentación y métodos de respaldo.

Si bien el modelo es importante, estas condiciones periféricas de ingeniería a menudo determinan si un sistema funciona de manera estable. Este juicio es más cierto para tareas altamente verificables como la codificación, pero en tareas de verificación débil como investigación abierta o negociación de múltiples rondas, el límite superior del modelo sigue siendo más crítico.

Práctica de Desarrollo Agent-First de OpenAI

Tres ingenieros escribieron un millón de líneas de código en cinco meses con casi 1,500 PRs, 10 veces la velocidad del desarrollo tradicional. Esta velocidad no se debió solo a la fortaleza del modelo, sino a decisiones de ingeniería correctas:

1. El contenido que el Agente no puede ver no existe: El conocimiento debe existir en el propio código base. Los documentos externos son invisibles para un Agente en ejecución. AGENTS.md se mantiene en ~100 líneas como un índice, con detalles divididos en directorios docs para referencia bajo demanda.
2. Restricciones en el código, no las documentes: Las normas en documentos se ignoran fácilmente. Las restricciones codificadas en Linters, sistemas de tipos o reglas de CI son ejecutables. La estratificación arquitectónica se aplica mecánicamente mediante Linters personalizados, no mediante revisión manual.
3. Finalización autónoma de tareas de extremo a extremo: Desde verificar el estado y reproducir errores hasta implementar correcciones y ejecutar la verificación de la aplicación, abrir PRs, manejar revisiones y fusionar, toda la cadena no requiere intervención humana. Los Agentes verifican activamente registros, métricas y trazas.
4. Minimizar la fricción de fusión: Manejar fallos intermitentes de pruebas con reintentos en lugar de bloquear el progreso. En entornos de alto rendimiento, el costo de esperar una revisión manual suele ser mayor que corregir pequeños errores. La disciplina de codificación no ha desaparecido; se ha desplazado de la revisión manual a restricciones ejecutadas por máquina.

La aplicación distribuye registros, métricas y trazas a través de Vector a la capa de almacenamiento Victoria, correspondiente a las interfaces LogQL, PromQL y TraceQL. Codex consulta, correlaciona y razona a través de estas interfaces. Después de los cambios, reinicia la aplicación, vuelve a ejecutar cargas de trabajo y retroalimenta los resultados a Codex. Las UI Journeys también son entradas. Esta pila de observabilidad se crea por tarea y se destruye al finalizar. El Agente no espera que le digan los errores; consulta el estado del sistema para verificar las correcciones.

¿Cuál es la Conclusión Clave para el Harness?

El diagrama utiliza la claridad de la tarea y la automatización de la verificación para dividir las tareas en cuatro estados. La esquina superior derecha (objetivos claros, verificación automatizada) es la zona ideal para los Agentes. La esquina superior izquierda (tarea clara pero revisión manual) está limitada por la velocidad de revisión humana. La esquina inferior derecha (retroalimentación automatizada pero objetivos vagos) lleva a un movimiento eficiente en la dirección equivocada. La esquina inferior izquierda (carece de ambas) hace que los Agentes sean inútiles.

El trabajo del Harness es empujar las tareas a la esquina superior derecha, asegurando que lo correcto y lo incorrecto se juzguen mediante estándares ejecutables por máquina, no por ojos humanos.

3. Por qué la Ingeniería de Contexto Determina la Estabilidad

La complejidad de la atención del Transformer es O(n²). Cuanto más largo es el contexto, más fácil es que las señales clave se diluyan con el ruido. Un modo de fallo común es la "Podredumbre del Contexto", donde el contenido irrelevante domina el contexto, haciendo que la calidad de decisión del Agente se degrade. Muchos problemas que parecen de incapacidad del modelo se deben en realidad a una mala organización del contexto.

¿Por qué Estratificar el Contexto?

El problema generalmente no es que la ventana no sea lo suficientemente larga, sino que la densidad de información es incorrecta. Cargar elementos de uso poco frecuente cada vez o mezclar reglas estables con estados dinámicos dificulta que el modelo note lo que es útil.

La solución es estratificar la información por frecuencia y estabilidad:

• Capa Permanente: Identidad, convenciones del proyecto, prohibiciones absolutas. Contenido que debe mantenerse en cada sesión. Mantenlo corto, firme y ejecutable.
• Carga Bajo Demanda: Habilidades y conocimiento del dominio. Mantén los descriptores permanentes, pero inyecta el contenido completo solo cuando se active.
• Inyección en Tiempo de Ejecución: Información dinámica como hora actual, ID del canal, preferencias del usuario. Se inyecta por ronda según sea necesario.
• Capa de Memoria: Experiencia entre sesiones escrita en MEMORY.md. No está directamente en el prompt del sistema; se lee solo cuando es necesario.
• Capa del Sistema: Hooks o reglas de código para lógica determinista. Permanece fuera del contexto por completo.

No pongas lógica determinista en el contexto. Cualquier cosa expresable mediante Hooks, reglas de código o restricciones de herramientas debe ser manejada por sistemas externos.

Tres Estrategias Comunes de Compresión

1. Ventana Deslizante: Descarta mensajes antiguos. Bajo costo, pero pierde contexto temprano. Bueno para chats cortos.
2. Resumen del LLM: El modelo genera un resumen. Costo medio, pierde detalles pero mantiene decisiones. Bueno para tareas largas.
3. Reemplazo de Resultados de Herramientas: Reemplaza la salida sin procesar con marcadores de posición. Bajo costo, bueno para tareas con muchas herramientas.

Las ventanas deslizantes son las más fáciles pero pierden antecedentes tempranos. Los resúmenes avanzados del LLM usan "resumen por ramas", preservando explícitamente decisiones arquitectónicas, tareas incompletas y restricciones clave. En el reemplazo de herramientas, micro_compact reemplaza las salidas antiguas de herramientas cada ronda, mientras que auto_compact se activa cuando el contexto supera un umbral.

Caching de Prompts para Reducir la Sobrecarga Redundante

La inferencia del LLM calcula pares Clave-Valor para cada token. Si un prefijo coincide exactamente con una solicitud anterior, se lee de la caché. El almacenamiento en caché requiere una coincidencia exacta del prefijo. El diseño amigable con la caché se centra en la estabilidad: los prompts del sistema, las definiciones de herramientas y los documentos largos son estables y adecuados para el almacenamiento en caché. La información dinámica (hora, entrada, resultados de herramientas) debe colocarse al final.

Esto se relaciona con la estratificación del contexto. Cuanto más estable sea la capa permanente, mayor será la tasa de aciertos de caché y menor el costo marginal. "Corto y estable" no es solo para ahorrar tokens; protege la caché. La carga retrasada de habilidades también ayuda al agregar contenido después del prefijo estable. Un punto contraintuitivo: un prompt de sistema grande y estable puede ser más barato que uno pequeño que cambia con frecuencia porque el descuento del 90% en lecturas posteriores supera el costo inicial de escritura.

¿Por qué Cargar Habilidades Bajo Demanda?

Las habilidades son un patrón efectivo: mantén solo el índice en el prompt del sistema, carga el conocimiento completo según sea necesario.

1const systemPrompt = `
2Habilidades Disponibles:
3- deploy: Proceso completo de despliegue en producción
4- code-review: Lista de verificación de revisión de código
5- git-workflow: Estrategia de ramas y normas de PR
6`;
7
8async function executeLoadSkill(name: string): Promise<string> {
9  return fs.readFile(`./skills/${name}.md`, "utf-8");
10}

Las descripciones de habilidades deben ser cortas para evitar la hinchazón de tokens y deben actuar como condiciones de enrutamiento. Explica cuándo usarla, cuándo NO usarla y cuál es la salida. Usa "Usar cuando / No usar cuando" con ejemplos negativos. Muchos fallos de enrutamiento se deben a límites poco claros, no a la capacidad del modelo. El prompt del sistema debe aclarar las reglas: escanear available_skills antes de cada respuesta, cargar el SKILL.md específico si coincide, y cargar solo uno a la vez.

Los datos son claros: sin ejemplos negativos, la precisión cae del 73% al 53%; agregarlos la eleva al 85% y reduce el tiempo de respuesta en un 18.1%. Los ejemplos negativos son clave.

Los descriptores de habilidades tienen dos trampas. Primero, el recuento de palabras: las descripciones largas para cada habilidad se acumulan. Segundo, la precisión: "ayudar con el backend" es demasiado vago. Los descriptores efectivos son condiciones de enrutamiento, no introducciones de funciones. "Cuándo usarme" es más importante que "Qué puedo hacer".

Controla la cantidad: mantén solo las habilidades de alta frecuencia en el prompt permanente. Las de baja frecuencia se pueden introducir manualmente o mantener como documentos. Los antipatrones típicos incluyen meter cientos de líneas de manuales en una habilidad o que una habilidad cubra demasiadas tareas distintas (revisión, despliegue, depuración).

¿Qué se Pierde Más Fácilmente con la Compresión?

El problema más común no es que el resumen sea demasiado largo, sino que la prioridad de retención es incorrecta. Los LLMs a menudo eliminan información que parece reobtenible. Las salidas de herramientas van primero, pero las decisiones arquitectónicas relacionadas y las rutas de fallo a menudo también desaparecen. Define explícitamente las prioridades de retención en CLAUDE.md:

1### Instrucciones de Compresión: Cómo retener información clave
2Prioridad:
31. Decisiones arquitectónicas (no resumir)
42. Archivos modificados y cambios clave
53. Estado de verificación (éxito/fallo)
64. TODOs sin resolver y notas de reversión
75. Salida de herramientas (se puede eliminar, mantener solo conclusión de éxito/fallo)

Otra trampa: no cambiar los identificadores. Los UUIDs, hashes, IPs y nombres de archivo deben preservarse exactamente. Un carácter incorrecto en un hash de commit rompe las llamadas posteriores a herramientas.

Por qué los Sistemas de Archivos son Grandes Interfaces de Contexto

Cursor llama a esto "Descubrimiento Dinámico de Contexto": da menos por defecto, lee cuando sea necesario. Los sistemas de archivos son interfaces naturales. Las llamadas a herramientas a menudo devuelven JSON masivo; en lugar de meterlo en el contexto, escríbelo en un archivo. El Agente puede usar grep o rg para leer según sea necesario. Esto mantiene el contexto limpio y es legible para el desarrollador.

Cursor verificó esto con herramientas MCP: sincronizan descripciones de herramientas en carpetas. Los Agentes ven solo los nombres de las herramientas por defecto y consultan las definiciones según sea necesario. En pruebas A/B, esto redujo el consumo total de tokens en un 46.9%.

Esto también funciona para la compresión de tareas largas. En lugar de descartar el historial, guarda el registro completo del chat en un archivo y referencia la ruta en el resumen. Si el Agente necesita detalles, puede recuperarlos del archivo, haciendo que la compresión sea una operación con pérdida pero trazable.

4. El Diseño de Herramientas Determina lo que un Agente Puede Hacer

El contexto determina lo que el modelo ve; las herramientas determinan lo que puede hacer. La calidad supera a la cantidad. Solo 5 servidores MCP pueden costar ~55,000 tokens en definiciones, casi el 30% de un contexto de 200K antes de que comience el chat. Demasiadas herramientas diluyen la atención del modelo.

La mayoría de los problemas con las herramientas no son por tener muy pocas, sino por elegir la incorrecta, descripciones incomprensibles o devolver datos inútiles.

Cómo Evoluciona el Diseño de Herramientas

El diseño de herramientas ha pasado por tres etapas. Al principio, las API existentes simplemente se envolvían como herramientas. Más tarde, se descubrió que los errores de selección a menudo se debían a que las herramientas estaban diseñadas para ingenieros, no para Agentes.

1ra Gen: Envoltura de API: Cada endpoint es una herramienta. Demasiado granular; los Agentes deben coordinar múltiples herramientas para un solo objetivo.

2da Gen: ACI (Interfaz Agente-Computadora): Las herramientas corresponden a los objetivos del Agente, no a las API de bajo nivel. En lugar de create_file y set_permissions, proporciona create_script(path, content, executable).

3ra Gen: Uso Avanzado de Herramientas: Optimizando el descubrimiento y la llamada:

• Búsqueda de Herramientas: No metas todas las definiciones a la vez. Los Agentes encuentran definiciones mediante search_tools. La retención de contexto alcanza el 95%.
• Llamada Programática de Herramientas: Deja que el modelo use código para orquestar múltiples llamadas. Los resultados intermedios permanecen en el entorno de ejecución, no en el contexto del LLM. Los tokens pueden bajar de 150,000 a 2,000.
• Ejemplos de Uso de Herramientas: Cada herramienta obtiene de 1 a 5 ejemplos reales. JSON Schema describe los tipos, pero los ejemplos muestran el uso. La precisión puede subir del 72% al 90%.

Principios de Diseño de Herramientas ACI

El diseño de herramientas afecta directamente a los Agentes. No se trata solo de "se puede llamar", sino de "puede autocorregirse si se llama mal?"

Los diseños malos tienen parámetros vagos y errores no corregibles. Los buenos diseños usan betaZodTool para vincular definición e implementación, usando Zod para restricciones de formato y sugerencias de error estructuradas:

1const updateTool = betaZodTool({
2  name: "update_yuque_post",
3  description: "Actualiza el contenido de una publicación de Yuque; no para crear nuevas publicaciones",
4  inputSchema: z.object({
5    post_id: z.string().describe("ID de la publicación de Yuque, cadena numérica como '12345678'"),
6    title: z.string().optional().describe("Título de la publicación, omitir si no cambia"),
7    content_markdown: z.string().describe("Cuerpo en Markdown"),
8  }),
9  run: async (input) => {
10    const post = await getPost(input.post_id);
11    if (!post) throw new ToolError("El ID de la publicación no existe", {
12      error_code: "POST_NOT_FOUND",
13      suggestion: "Llama a list_yuque_posts primero para obtener un post_id válido",
14    });
15    return await updatePost(input.post_id, input.title, input.content_markdown);
16  },
17});

El mal diseño solo dice lo que hace, no cuándo usarlo. El buen diseño ACI tiene límites claros y errores estructurados, ayudando a los Agentes a elegir correctamente y solucionar fallos rápidamente. Depura las herramientas primero; la mayoría de los errores están en las descripciones, no en la capacidad del modelo.

¿Por qué Aislar los Mensajes de Herramientas?

Los frameworks generan eventos internos (compresión, notificaciones). Estos deben estar en el historial de la sesión pero no enviarse al LLM, ya que desperdician tokens y confunden al modelo. La solución son dos tipos de mensajes: AgentMessage para la capa de la aplicación (con campos personalizados) y Message estándar (user, assistant, tool_result) para el LLM.

5. Diseñando el Sistema de Memoria

Los Agentes carecen de continuidad temporal nativa. El contexto se borra después de una sesión. Para lograr consistencia entre sesiones, se debe diseñar una capa de memoria como infraestructura, no como una ocurrencia tardía.

¿Dónde Viven los Cuatro Tipos de Memoria?

Categorizados por el problema que resuelven:

• Ventana de Contexto (Memoria de Trabajo): Información mínima para la tarea actual. Tokens limitados; debe gestionarse.
• Habilidades (Memoria Procedimental): Cómo hacer las cosas (flujos de trabajo, normas). Se cargan bajo demanda.
• Historial de Sesión JSONL (Memoria Episódica): Lo que sucedió. Persistido en disco; se puede buscar.
• MEMORY.md (Memoria Semántica): Hechos estables escritos por el Agente. Se inyecta en los prompts del sistema.

Cómo Colaboran MEMORY.md y las Habilidades

El núcleo es mantener hechos importantes mientras se controla el volumen de contenido.

Memoria de 4 Capas de ChatGPT: Estructura simple. Metadatos de Sesión (no persistidos), Memoria del Usuario (~33 hechos, persistidos/inyectados), Resumen de Conversación (~15 resúmenes recientes, persistidos), Sesión Actual (ventana deslizante).

Recuperación Híbrida de OpenClaw: Registros diarios (memory/YYYY-MM-DD.md), MEMORY.md para hechos seleccionados, y memory_search usando recuperación híbrida (70% similitud vectorial + 30% palabras clave). Para la mayoría de los Agentes, Markdown estructurado + búsqueda de palabras clave es suficiente para la depurabilidad y el costo.

Desencadenar y Revertir la Consolidación de Memoria

Cuando tokenUsage / maxTokens >= 0.5, desencadena la consolidación. Resume los mensajes, añádelos a MEMORY.md y actualiza el índice. Si falla, escribe los mensajes sin procesar en un archivo. El proceso debe ser reversible; mueve punteros, no elimines datos sin procesar.

6. Aumento Gradual de la Autonomía del Agente

La autonomía requiere tres piezas de infraestructura: reanudación entre sesiones, restricciones de progreso dentro de la sesión y E/S en segundo plano para tareas lentas.

Cómo Continuar Tareas Largas Entre Sesiones

Las tareas largas fallan cuando las sesiones terminan antes de completarse. Un enfoque estable utiliza un Agente Inicializador y un Agente de Codificación. El Inicializador se ejecuta una vez para crear feature-list.json, init.sh y claude-progress.txt. Luego, el Agente de Codificación se ejecuta en múltiples sesiones, reanudando desde estos archivos, implementando una característica, ejecutando pruebas y actualizando el archivo de progreso. Esto convierte la tarea en un estado externo.

Mantén el progreso en archivos, no en el contexto. Usa JSON para la estructura. La tarea está completa solo cuando todas las características en feature-list.json tienen passes: true.

¿Por qué Escribir Explícitamente el Estado de la Tarea?

Sin anclajes externos, los Agentes se desvían o terminan prematuramente. Registra el estado como un objeto de control externo:

1{
2  "tasks": [
3    {"id": "1", "desc": "Leer configuración", "status": "completed"},
4    {"id": "2", "desc": "Modificar esquema", "status": "in_progress"}
5  ]
6}

Restricción: solo un in_progress a la vez. Actualiza el estado después de cada paso.

Integración de E/S en Segundo Plano

La E/S lenta (operaciones de archivos, red) no debe bloquear el bucle principal. Coloca los subprocesos lentos en hilos de fondo e inyecta los resultados a través de una cola de notificaciones antes de la siguiente llamada al LLM. Esto es más mantenible que un runtime asíncrono complejo.

7. Organización de Sistemas Multiagente

La ingeniería de sistemas multiagente se trata de aislamiento y colaboración.

Modo Director: Síncrono. El humano interactúa estrechamente con un Agente. El contexto se pierde cuando termina la sesión.

Modo Coordinador: Delegación asíncrona. El humano establece objetivos, los Agentes trabajan en paralelo, el humano revisa la salida. La salida se convierte en artefactos persistentes (PRs, ramas).

Un Orquestador gestiona subagentes que trabajan en paralelo, comunicándose mediante protocolos de bandeja de entrada JSONL y usando Worktrees para el aislamiento.

¿Para qué Sirven los Subagentes?

La búsqueda y el ensayo y error no deben contaminar el contexto del Agente principal. El Agente principal solo necesita la conclusión.

1const result = await runAgentLoop(task, { messages: [] });
2return summarize(result); // El contexto principal solo ve esta línea

¿Por qué Escribir la Colaboración como un Protocolo?

La colaboración en lenguaje natural falla cuando los Agentes olvidan las promesas. Usa un protocolo estructurado:

1{ request_id, from_agent, to_agent, content, status: 'pending', timestamp }

Usa una bandeja de entrada JSONL de solo añadir para la recuperación ante fallos. Primero el aislamiento, luego la colaboración.

Las Alucinaciones se Amplifican en Sistemas Multiagente

Los errores se propagan en cascada entre Agentes. La validación cruzada rompe esta cadena al tener un Agente independiente o retroalimentación externa (pruebas, compiladores) que juzgue la conclusión.

8. Cómo Evaluar Agentes

La evaluación requiere casos de prueba, estándares de puntuación y verificación automatizada.

La evaluación tradicional de una sola vuelta (Prompt -> Respuesta) es insuficiente. La evaluación de Agentes requiere herramientas y entornos. La puntuación se basa en lo que sucedió en el entorno, no solo en lo que dijo el Agente.

Conceptos clave: Tarea, Prueba, Calificador. Transcripción (registro de ejecución) vs Resultado (estado final). Necesitas ambos. Un Agente podría decir "boleto reservado" (transcripción) pero no crear el registro en la base de datos (resultado).

Estado y métricas de evaluación

Muchos equipos aún dependen de la revisión manual o de evaluadores LLM. Métricas comunes: Pass@k (¿puede hacerlo teóricamente?) y Pass^k (¿es estable para producción?). No las mezcles.

Tres tipos de evaluadores

1. Evaluadores de código: Coincidencia de cadenas, pruebas unitarias. Mayor certeza.
2. Evaluadores de modelo: Jueces LLM basados en criterios. Buenos para calidad semántica.
3. Evaluadores humanos: Revisión de expertos. Lento pero establece la línea base.

Construir un sistema de evaluación desde cero

Comienza con 20-50 casos de fallos reales. Asegura el aislamiento del entorno para que las pruebas no se contaminen entre sí. Incluye tanto casos positivos como negativos. Si dos expertos no están de acuerdo en un caso, los criterios aún no están claros.

Arregla la evaluación antes de arreglar el agente

Si las puntuaciones bajan, revisa primero el sistema de evaluación. Los problemas del entorno (límites de memoria, errores en los evaluadores) parecen degradación del modelo.

9. Trazado del proceso de ejecución

Sin trazas, los fallos no se pueden reproducir. Las métricas APM (latencia, tasa de error) no son suficientes; necesitas la cadena de razonamiento.

¿Qué registrar en una traza?

Prompt completo, mensajes de múltiples rondas, llamadas/argumentos/retornos de herramientas, cadena de pensamiento, salida final, tokens y latencia.

Observabilidad de dos capas

1. Muestreo manual: Muestreo basado en reglas de errores o retroalimentación negativa para encontrar patrones de fallo.
2. Auto-evaluación LLM: Cobertura completa de trazas usando la capa manual como línea base de calibración.

Flujos de eventos como base

Emite eventos en tool_start, tool_end y turn_end. Los sistemas posteriores (logs, UI, evaluación) consumen estos eventos sin cambiar el código del bucle principal.

10. Implementar agentes con OpenClaw

OpenClaw usa cinco capas desacopladas: Gateway, Channel Adapters, Pi Agent (bucle principal), Toolsets (diseño ACI) y Context/Memory.

Desacoplamiento del bus de mensajes

Un bus de mensajes separa los canales del agente. Los canales solo manejan E/S; el agente solo maneja el procesamiento.

Prompts del sistema en capas

SOUL.md define la identidad y los estándares de finalización. Los prompts se organizan en capas: Información de ejecución -> Identidad -> Memoria -> Habilidades -> Inyección dinámica.

Límites de seguridad primero

Antes de agregar funciones, establece: Listas blancas de usuarios, Aislamiento del espacio de trabajo (verificaciones de rutas) y Registros de auditoría.

Protección contra inyección de prompts: Trata el contenido externo como no confiable. Usa separación fuente-sumidero. No le des a los agentes herramientas que no necesiten. Exige confirmación humana explícita para acciones sensibles.

Proveedor de respaldo: Cambia automáticamente de proveedor (Anthropic -> OpenAI) si uno falla.

11. Antipatrones comunes

1. Prompt del sistema como base de conocimiento (demasiado largo).
2. Expansión de herramientas (el agente elige herramientas incorrectas).
3. Falta de bucles de verificación.
4. Sistemas multiagente sin límites.
5. Sin consolidación de memoria (la calidad baja después de 20 rondas).
6. Sin sistema de evaluación.
7. Complejidad multiagente prematura.
8. Confiar en expectativas en lugar de restricciones mecánicas.

12. Conclusión

1. El núcleo del agente es un bucle estable; las nuevas funciones deben externalizarse.
2. El arnés determina la convergencia más que el modelo.
3. La ingeniería de contexto previene la "podredumbre del contexto".
4. El diseño de herramientas ACI se centra en objetivos y corrección de errores.
5. La memoria está en capas (de trabajo, procedimental, episódica, semántica).
6. Las tareas largas dependen del estado y archivos externalizados.
7. Los sistemas multiagente necesitan protocolos y aislamiento.
8. Evaluación Pass@k para capacidad, Pass^k para calidad.
9. El trazado es el requisito previo para la depuración.
10. Los agentes estables dependen de detalles de ingeniería como el desacoplamiento y los límites de seguridad.