El agente de investigación encontró la cuenta del cliente, confirmó el plan y obtuvo las últimas cuatro facturas. Se lo entregó al agente de facturación con un resumen de una línea: "El cliente quiere un reembolso". El agente de facturación, que ahora no sabe nada sobre la cuenta, el plan o las facturas, comienza pidiendo el ID de la cuenta.
Cada dato que el primer agente recopiló fue descartado en el límite. Ese es el problema de la transferencia, y le cuesta el doble: una vez en las llamadas duplicadas a la API, y otra en los errores que provienen de que el segundo agente trabaja con menos información que el primero.
Esta guía cubre lo que debe sobrevivir a una transferencia, las tres formas en que los equipos pasan el estado y cuándo funciona cada una, por qué los resúmenes pierden más de lo que la gente espera, y cómo probar que una transferencia llevó lo que afirmaba. Nuestra publicación sobre por qué los agentes fallan en producción trata el estado perdido como un modo de falla central; esta es la versión multi-agente.
Apidog aparece porque la solución más económica suele ser dejar de pasar datos por completo y pasar identificadores en su lugar, lo que solo funciona si cada agente puede recuperar el mismo registro de la misma manera.
Lo que realmente necesita cruzar el límite
No todo. Una transferencia que copia toda la conversación está tan rota como una que no copia nada, solo que en la otra dirección: el segundo agente hereda una ventana de contexto completa y tiene que averiguar qué partes importan.
Vale la pena separar cuatro categorías.
Identificadores. IDs de cuenta, IDs de pedido, IDs de trabajo, números de ticket. Son pequeños, estables y permiten que el agente receptor obtenga todo lo que necesita. Son lo más valioso que se puede pasar y lo más común que se pierde.
Decisiones ya tomadas. "El cliente es elegible para un reembolso bajo la política 3." El agente receptor no debe volver a discutir esto. Si lo hace, tendrá dos agentes en desacuerdo dentro de una misma tarea.
Restricciones. Límites de presupuesto, aprobaciones concedidas, acciones ya realizadas. Perder esto hace que una tarea termine cobrando dos veces o pidiendo la misma aprobación por segunda vez. Se combina directamente con nuestra publicación sobre idempotencia para agentes de IA.
Preguntas abiertas. Lo que el primer agente no pudo resolver. Pasar esto explícitamente evita que el segundo agente asuma en silencio.
Lo que no necesita cruzar: respuestas de API en bruto, el transcripto de razonamiento y cualquier cosa que el agente receptor pueda obtener por sí mismo en una sola llamada.
Tres formas de pasar el estado
Pasar toda la conversación. Simple, y funciona para dos agentes en una tarea corta. Falla tan pronto como el transcripto es largo, porque el agente receptor gasta la mayor parte de su presupuesto leyendo el historial y los hechos relevantes quedan enterrados en el medio. Nuestra publicación sobre mantener las respuestas de la herramienta fuera de la ventana de contexto explica por qué ese medio es exactamente donde los modelos pierden cosas.
Pasar un resumen. El primer agente escribe un mensaje de transferencia; el segundo comienza a partir de él. Este es el valor predeterminado en la mayoría de los marcos de trabajo y es deficiente de una manera específica: los modelos resumen hacia la narrativa y se alejan de los identificadores. Pida un resumen y obtendrá "el cliente ha sido suscriptor durante dos años y está frustrado" en lugar de "cuenta 8812, plan pro, cuatro facturas, reembolso aprobado para la factura inv_44".
Pasar un objeto de transferencia estructurado. El primer agente llena un esquema. El segundo lee campos, no prosa. Esto requiere más trabajo para configurarlo y es el que se mantiene.
{
"task_id": "task_2026_08_26_0031",
"from_agent": "research",
"to_agent": "billing",
"entities": {
"customer_id": "cus_8812",
"invoice_ids": ["inv_41", "inv_42", "inv_43", "inv_44"],
"subscription_id": "sub_119"
},
"decisions": [
{ "decision": "refund_eligible", "value": true, "basis": "policy 3.2, charged twice in one cycle" }
],
"constraints": {
"max_refund_cents": 4900,
"human_approval_granted": false,
"actions_taken": ["read_invoices"]
},
"open_questions": ["Customer has not confirmed which invoice to refund"],
"summary": "Customer cus_8812 was double-charged in August. Refund of one invoice is approved under policy 3.2, up to 4900 cents. Awaiting the customer's choice of invoice."
}
La prosa sigue apareciendo, en el campo summary, porque contiene matices que el esquema no tiene. Se sitúa junto a los campos estructurados en lugar de reemplazarlos, que es el objetivo principal.
Valide el objeto antes de que se ejecute la transferencia. Si falta el customer_id, falle ruidosamente en el límite en lugar de dejar que el segundo agente lo descubra tres llamadas más tarde.
Pasar referencias, no cargas útiles
La versión más fuerte de una transferencia pasa casi ningún dato. Pasa IDs, y el agente receptor obtiene lo que necesita.
Esto funciona por tres razones. El estado se mantiene fresco, así que si algo cambió entre los dos agentes, el segundo ve el valor actual en lugar de una copia obsoleta. La transferencia se mantiene pequeña, unos pocos cientos de bytes en lugar de decenas de miles de tokens. Y la pista de auditoría mejora, porque cada lectura aparece como una llamada a la API en lugar de texto copiado entre prompts.
Requiere una cosa: que cada agente pueda acceder a la misma API con los permisos correctos. Eso no es gratis. Cada agente necesita sus propias credenciales con alcance a lo que hace, que es el argumento de nuestra publicación sobre claves API de menor privilegio para agentes. Un agente de facturación que tenga un token de investigación de solo lectura no puede emitir el reembolso, y un agente de investigación que tenga el token de facturación es un problema de radio de explosión.
Cuando una nueva recuperación fuera costosa o lenta, almacene en caché el registro en su orquestador y pase una referencia a la entrada de la caché. El agente receptor seguirá solicitando los datos explícitamente, por lo que el patrón sigue siendo el mismo, pero la segunda lectura es económica.
Donde las transferencias realmente fallan
Cuatro fallas cubren la mayoría de los incidentes.
El identificador descartado. El resumen dice "el cliente" y nunca da un ID, por lo que el segundo agente busca por nombre, encuentra dos coincidencias y elige la incorrecta. Evítelo validando que los IDs de entidad requeridos estén presentes antes de que se permita que la transferencia proceda.
La acción repetida. El primer agente ya envió el correo electrónico. La transferencia no lo registra. El segundo agente lo envía de nuevo. Registre actions_taken en el objeto de transferencia y verifíquelo antes de cualquier escritura, respaldado por las claves de idempotencia que hacen que una repetición sea inofensiva.
La aprobación perdida. Un humano aprobó un reembolso mientras el primer agente estaba en funcionamiento. El segundo agente, sin saberlo, pregunta de nuevo. Los usuarios interpretan el segundo prompt como un sistema que no escucha. Lleve las aprobaciones como restricciones explícitas y trátelas como limitadas a la tarea, no al agente.
La invención confiada. El agente receptor necesita un valor que la transferencia no contenía, y en lugar de preguntar, inventa uno que se ajusta a la narrativa. Este es el fallo más peligroso porque parece una tarea completada. La defensa es el campo open_questions más una regla estricta en el prompt del agente receptor: si falta un identificador requerido, detente y pregunta.
Los bucles empeoran las cuatro. Cuando el agente A transfiere al B y el B devuelve al A, el estado se degrada en cada pasada, como una fotocopia de una fotocopia. Limite el número de saltos y lleve el objeto de tarea original a través de cada uno de ellos en lugar de reconstruirlo en cada límite.
Pruebe el límite, no solo los agentes
Las transferencias son puntos de integración, así que pruébelas como puntos de integración.
Asegúrese del objeto de transferencia. Ejecute el primer agente en un escenario fijo y verifique el objeto que produce: identificadores requeridos presentes, decisiones registradas, acciones listadas. Esta es una aserción determinista sobre una carga útil estructurada, aunque el agente que la produjo no sea determinista, lo que la convierte en una prueba utilizable. El enfoque general se encuentra en nuestra guía para probar agentes de IA no deterministas.
Pruebe el receptor de forma aislada. Alimente al agente de facturación con un objeto de transferencia hecho a mano y compruebe lo que hace. Luego, aliméntelo con uno deliberadamente defectuoso, con el ID de cliente eliminado, y confirme que pregunta en lugar de adivinar. Esta segunda prueba es la que detecta la invención.
Ejecute ambos contra simulaciones (mocks). Una prueba de transferencia que emite reembolsos reales es una prueba que solo ejecutará una vez. Apunte ambos agentes a endpoints simulados para que la suite pueda ejecutarse en cada cambio, siguiendo nuestra publicación sobre ejecutar agentes contra simulaciones en lugar de producción. En Apidog, las simulaciones provienen de la misma definición de API que ambos agentes llaman, por lo que los dos nunca se desvían.
Registre cada transferencia. Registre el objeto completo en cada límite con el ID de la tarea. Cuando una ejecución multi-agente sale mal, el registro de transferencia le indica qué agente tenía la información y cuál la perdió, lo que suele ser toda la investigación. Nuestra publicación sobre rastreo de llamadas a herramientas de agentes cubre qué más debe incluirse en ese registro.
Lo que le ofrecen los frameworks
La mayoría de los frameworks de orquestación incluyen una primitiva de transferencia, y es útil saber qué mueve realmente cada uno a través del límite antes de confiar en ello.
La documentación de transferencia del SDK de agentes de OpenAI modela una transferencia como una herramienta que el agente puede llamar, lo que significa que el modelo decide cuándo se transfiere el control. Esto es conveniente, y pone la decisión en la parte menos determinista de su sistema, así que combínelo con validación al salir.
La guía multi-agente de LangGraph adopta un enfoque opuesto: el estado es un objeto gráfico explícito que cada nodo lee y escribe. Esto se asemeja mucho a la transferencia estructurada descrita anteriormente, y el trabajo principal que le queda es decidir qué campos son obligatorios.
El artículo de Anthropic sobre la construcción de un sistema de investigación multi-agente vale la pena leerlo por los detalles operativos, particularmente sobre cuánta instrucción necesita un sub-agente antes de poder trabajar útilmente por sí mismo.
El hilo común: cada framework moverá algo. Ninguno de ellos decide por usted qué hechos son fundamentales. Esa lista es suya para escribir, y es lo que vale la pena revisar cuando una ejecución sale mal.
Mantenga el objeto de tarea fuera de la conversación
Un cambio estructural previene toda una familia de errores. Almacene el estado de la tarea en un lugar duradero, indexado por el ID de la tarea, y haga que cada agente lo lea y lo escriba en lugar de pasarlo a través de mensajes.
La conversación es un contenedor deficiente para el estado. Se compacta, se trunca y se reescribe mediante la sumarización, y ninguna de esas operaciones sabe qué campos no puede permitirse perder. Una fila en una base de datos no tiene ese problema.
El patrón es pequeño. Al comienzo de un turno, el agente carga el objeto de tarea. Cuando realiza una acción, la agrega a actions_taken y la guarda. En la transferencia, pasa el ID de la tarea, y el agente receptor carga el mismo objeto. Nada importante viaja en el prompt, por lo que nada importante puede resumirse.
Esto también le da un punto de reanudación. Si una ejecución falla en el paso cuatro, el objeto de tarea aún contiene todo lo establecido en los primeros tres pasos, y el reintento comienza desde allí en lugar de desde cero.
Donde la plataforma puede mantener el estado
Si sus agentes se ejecutan como entornos de línea de comandos en máquinas de desarrolladores, el objeto de tarea duradero descrito anteriormente es algo que usted construye. Algunas plataformas de gestión de trabajo de agentes ya lo modelan, y vale la pena saber cómo es antes de escribir el suyo propio.
Sharkly es un sistema de gestión de trabajo para personas y agentes construido en torno a esta unidad exacta. Una Tarea lleva el objetivo, el estado, la persona responsable, el Agente o Equipo asignado para ejecutarla, los comentarios y el estado de ejecución y el resultado del agente. Un Equipo empareja un Agente líder con otros Agentes y personas, de modo que una tarea que necesita varios especialistas se asigna a un grupo reutilizable en lugar de pasarse de mano en mano a través de prompts. Debido a que el estado reside en la Tarea en lugar de en una conversación, una transferencia entre dos agentes no depende de que uno de ellos resuma bien.
Los entornos de ejecución siguen siendo los que ya utiliza. Claude Code, Codex y el resto ejecutan el trabajo en una computadora que usted registra; la plataforma proporciona el registro de la tarea, la asignación y el ciclo de revisión en torno a ellos. Si está construyendo usted mismo el patrón de tarea duradera, la documentación de Sharkly es una referencia útil para saber qué campos resultan importantes.
Una lista de verificación para las transferencias
- Existe un esquema definido para la transferencia, y se valida en el límite.
- Los identificadores de entidad son campos obligatorios, no opcionales.
- Las decisiones llevan su base, para que el receptor no rehaga el razonamiento.
- Las acciones ya realizadas se registran y verifican antes de cualquier escritura.
- Las aprobaciones y los presupuestos viajan con la tarea, no con el agente.
- Las preguntas abiertas son explícitas, y el receptor pregunta en lugar de asumir.
- Los datos se pasan por referencia donde una nueva obtención es barata.
- El número de saltos está limitado, y el objeto de tarea original sobrevive a cada salto.
- Cada transferencia se registra con el ID de la tarea.
- Las pruebas de límite se ejecutan en CI contra simulaciones (mocks), incluyendo una transferencia deliberadamente incompleta.
La mayoría de los fallos multi-agente no son fallos de razonamiento. Son un hecho que existía en un agente y no en el siguiente. Diseñe el límite como una interfaz, con un esquema y pruebas, y el segundo agente dejará de hacer preguntas que el primero ya respondió. Descargue Apidog para mantener las simulaciones y las pruebas de límite junto a la API de la que dependen ambos agentes.
Preguntas frecuentes
¿Vale la pena una transferencia estructurada para dos agentes? Para dos agentes en una tarea corta, pasar la conversación suele estar bien. El objeto estructurado se justifica con tres o más agentes, en tareas largas, o donde una transferencia cruza un proceso o un límite de ejecución.
¿Debería el modelo escribir el objeto de transferencia o debería el código construirlo? El código donde sea posible. Los identificadores, las acciones realizadas y las aprobaciones deben ser rellenados por su orquestador a partir de lo que realmente sucedió, no de la memoria del modelo. Deje que el modelo escriba solo el summary y las preguntas abiertas.
¿Cómo evito la degradación del contexto en un bucle? Lleve un objeto de tarea a lo largo de toda la ejecución y actualícelo, en lugar de regenerarlo en cada límite. Luego, limite los saltos. Si una tarea necesita más de unos pocos, la descomposición probablemente sea incorrecta.
¿Qué pasa con los frameworks con soporte de transferencia incorporado? Úselos y verifique qué transfieren realmente. Muchos pasan el historial de mensajes y nada más, lo que significa que los identificadores sobreviven solo si aparecen en el texto. Agregue una carga útil estructurada junto con lo que sea que el framework transporte.
¿Necesitan los subagentes credenciales de API separadas? Sí, con un alcance específico para lo que cada uno hace. Compartir una clave potente entre agentes elimina su capacidad de limitar daños y de saber qué agente realizó una llamada. Nuestra publicación sobre claves API de mínimo privilegio para agentes cubre la configuración.
¿Cuánto debe contener el campo de resumen? Unas pocas oraciones, cubriendo la intención y los matices que los campos estructurados no pueden contener. Si empieza a listar IDs y cantidades, estos deben ir en los campos estructurados donde puedan ser validados.