El agente de triaje dice que encontró el problema y pasa el caso a un especialista. El segundo agente recibe una sola frase, abre las mismas herramientas y vuelve a pedir el identificador que el primero ya había confirmado.

Ese es el problema del handoff. El fallo no está solo en el modelo que respondió. Está en la frontera entre dos ejecuciones: qué se completó realmente, qué evidencia lo respalda, qué puede hacer el siguiente agente y cómo debe reaccionar cuando el paquete está incompleto.

Un handoff útil es un contrato pequeño, no una copia de la conversación. Debe llevar el siguiente objetivo, el estado confirmado, referencias de evidencia, autoridad limitada, criterios de aceptación y una forma explícita de fallar. El agente receptor valida ese contrato antes de continuar.

Este artículo presenta un modelo de diseño y un schema ilustrativo en TypeScript. El código no se ejecutó contra un proveedor ni un runtime multiagente. La investigación combina la guía actual de handoffs del OpenAI Agents SDK, la documentación de handoffs de LangChain y discusiones públicas recientes. Para la arquitectura más amplia, consulta la orquestación multiagente para agentes de código con TypeScript.

Respuesta breve

  • Usa un handoff cuando otro agente deba hacerse cargo del siguiente paso, en vez de responder como una herramienta del agente actual.
  • Pasa estado confirmado y referencias de evidencia verificables, no todo el transcript como fuente de verdad.
  • Limita las herramientas y la autoridad del receptor. El segundo agente no debe heredar todos los permisos del primero.
  • Rechaza paquetes ausentes, antiguos o inconsistentes antes de iniciar una acción externa.

¿Cuándo debe un agente ceder el control?

Un handoff encaja cuando un especialista debe hacerse cargo de la conversación o de la siguiente etapa. La documentación de OpenAI Agents SDK, "Handoffs", consultada el 25/09/2026, separa este caso del patrón en que un agente llama a otro como herramienta y sigue siendo responsable de la respuesta.

Esta decisión cambia quién es dueño del siguiente paso. En un patrón de gerente, el agente principal llama a un especialista, recibe un resultado y mantiene el control. En un handoff, el triaje deja de ser responsable de la ejecución siguiente. El receptor interpreta el contexto, llama a sus propias herramientas y cierra la etapa.

No uses un handoff solo porque existan dos prompts. Si la tarea es corta, usa las mismas herramientas y necesita una síntesis central, un agente con herramientas puede ser más fácil de operar. Añade la frontera cuando cambien de verdad la responsabilidad, los datos disponibles, los permisos o los criterios de aceptación.

Antes de transferir el control, responde cuatro preguntas:

  • ¿Qué debe producir el siguiente agente?
  • ¿Qué estado está confirmado y qué evidencia lo confirma?
  • ¿Qué herramientas y efectos quedan fuera de su autoridad?
  • ¿Qué ocurre si no puede continuar?

Si esas respuestas todavía viven solo en el prompt del triaje, el handoff se está tratando como un mensaje. Escribe el contrato antes de elegir el framework.

¿Qué debe incluir un contrato de handoff?

El contrato mínimo que uso como modelo editorial tiene seis bloques: objetivo, estado, evidencia, autoridad, aceptación y recuperación. Estos nombres no son un estándar universal. Son una forma compacta de hacer visibles las decisiones que el receptor tendría que adivinar.

El objetivo dice qué etapa comienza ahora. El estado registra qué ocurrió, además de la solicitud original. La evidencia apunta a artefactos, resultados o identificadores que se pueden comprobar. La autoridad enumera lo que el receptor puede hacer y lo que sigue prohibido. La aceptación dice cuándo la etapa está lista. La recuperación da un destino al estado rechazado, bloqueado o antiguo.

Un schema puede hacer concreta esa frontera:

import { z } from "zod";

const HandoffContract = z.object({
  version: z.literal(1),
  taskId: z.string().min(1),
  nextObjective: z.string().min(1),
  confirmedState: z.enum(["ready", "blocked", "needs-review"]),
  evidence: z.array(z.object({
    kind: z.enum(["artifact", "check", "decision"]),
    reference: z.string().min(1),
  })).min(1),
  authority: z.object({
    allowedTools: z.array(z.string()),
    forbiddenActions: z.array(z.string()),
  }),
  acceptance: z.array(z.string().min(1)).min(1),
  recovery: z.object({
    onReject: z.enum(["repair", "escalate", "stop"]),
    resumeFrom: z.string().nullable(),
  }),
});

type HandoffContract = z.infer<typeof HandoffContract>;

taskId evita que el receptor trate un paquete de otra ejecución como si fuera el actual. version permite cambiar el contrato sin leer una forma antigua como si fuera nueva. confirmedState separa listo de bloqueado. La lista de evidencias no necesita logs enormes. Puede apuntar a un artefacto versionado, una prueba, una decisión persistida o un resultado redactado.

El schema anterior es ilustrativo y no se ejecutó. En un sistema real, la validación también debe comprobar que cada referencia pertenece a la tarea, que la versión sigue siendo válida y que la autoridad solicitada no supera la política del receptor.

¿Cómo pasar contexto sin copiar toda la conversación?

Empieza por el contrato y después filtra el historial. OpenAI Agents SDK, "Handoffs" explica que el receptor recibe todo el historial por defecto y que inputFilter puede cambiar lo que cruza la frontera. La misma documentación separa inputType, que describe los argumentos del handoff, de RunContext, que lleva el estado y las dependencias existentes.

Esta diferencia evita un error común. Un resumen generado por el modelo puede explicar por qué el triaje eligió a un especialista. No prueba que una herramienta se ejecutó, que un archivo está en una versión concreta ni que una aprobación sigue vigente. El contrato debe apuntar al estado verificable. El historial puede explicar el razonamiento, pero no debe ser la única fuente de verdad.

En handoffs entre subgrafos, la documentación de LangChain, "Handoffs", consultada el 25/09/2026, llama la atención sobre la validez de la secuencia de mensajes. Una llamada de herramienta y su respuesta deben seguir emparejadas cuando ese historial pasa al siguiente agente. Filtrar contexto exige conservar las unidades que espera el runtime en vez de cortar mensajes por la mitad.

Una política de filtro puede seguir este orden:

  1. Elimina credenciales, prompts internos y datos que el receptor no necesita.
  2. Elimina llamadas antiguas a herramientas cuando no pertenecen a la tarea actual.
  3. Conserva los mensajes que exige el protocolo del proveedor.
  4. Añade el contrato validado como un objeto separado del texto narrativo.
  5. Registra qué filtro se aplicó para que la transferencia pueda auditarse.

No conviertas inputType en un depósito de estado. La documentación del SDK dice que ese campo sirve para metadatos que el modelo decide en el momento del handoff, como motivo, idioma o prioridad. El estado de la aplicación, las dependencias y los permisos deben venir de una fuente controlada por el runtime.

¿Cómo valida el paquete el agente receptor?

El receptor debe validar antes de elegir su primera herramienta. Esa validación debe tratar los campos ausentes, la versión, la identidad de la tarea, el estado, la autoridad y la evidencia como condiciones de entrada. Si una falla, el resultado debe ser un rechazo explicable, no una suposición sobre lo que quiso decir el triaje.

Una función de validación puede devolver un resultado discriminado:

type HandoffResult =
  | { ok: true; contract: HandoffContract }
  | { ok: false; reason: "invalid" | "stale" | "unauthorized" };

function acceptHandoff(
  value: unknown,
  expectedTaskId: string,
  allowedTools: ReadonlySet<string>,
): HandoffResult {
  const parsed = HandoffContract.safeParse(value);

  if (!parsed.success || parsed.data.taskId !== expectedTaskId) {
    return { ok: false, reason: "invalid" };
  }

  const hasUnknownTool = parsed.data.authority.allowedTools.some(
    (tool) => !allowedTools.has(tool),
  );

  if (hasUnknownTool) {
    return { ok: false, reason: "unauthorized" };
  }

  return { ok: true, contract: parsed.data };
}

Este ejemplo hace solo tres comprobaciones. Valida la forma, comprueba la tarea e impide que el paquete solicite una herramienta fuera de la allowlist del receptor. Un runtime también puede comparar la versión del estado, exigir que existan las referencias y rechazar confirmedState: "ready" cuando la evidencia registrada está incompleta.

La autorización no puede depender de la prosa del handoff. Si el agente de triaje escribe "puedes publicar" dentro de nextObjective, eso sigue siendo una intención. La política del receptor debe leer la autoridad estructurada y aplicar sus propios límites antes de llamar a una herramienta. La documentación de OpenAI Agents SDK, "Handoffs" también advierte que isEnabled no autoriza valores dentro de argumentos generados por el modelo. Cuando la autorización depende de campos recibidos, compruébalos al inicio de onHandoff, antes de los efectos secundarios.

¿Qué ocurre cuando se rechaza un handoff?

Un rechazo debe ser un estado operativo. invalid significa que la estructura no pasa el schema. stale significa que la tarea cambió después de crear el paquete. unauthorized significa que la transferencia solicita una capacidad que el receptor no puede usar. Cada caso debe tener un siguiente paso diferente.

Para invalid, devuelve el error al triaje con los campos ausentes o inconsistentes. Para stale, carga el estado actual y crea un paquete nuevo. Para unauthorized, detén la ejecución y escala o reduce la autoridad. No hagas retry a ciegas. Repetir la misma transferencia solo crea otra oportunidad de esconder la causa.

Si el handoff cruza un proceso, una cola o una aprobación humana, persiste el contrato y su versión. La ejecución durable para agentes de IA cubre el estado que debe sobrevivir a los fallos. Un handoff dentro de una misma ejecución puede usar la memoria del runtime, pero también debe tener un rechazo observable.

Separa también handoff y compactación. La compactación de contexto en agentes reduce el historial que un agente envía al modelo. Un handoff cambia quién es responsable de una etapa. Ambos pueden usar filtros y resúmenes, pero resuelven fronteras diferentes.

¿Cómo probar una frontera de handoff?

Prueba el contrato como una interfaz, incluyendo el camino correcto y los rechazos del workflow. La guía para evaluar la trayectoria de un agente de IA cubre herramientas, argumentos, orden, estado y decisiones de parada. El handoff añade una unidad más pequeña: el paquete que debe llegar al siguiente agente.

Una matriz inicial puede incluir estos casos:

  • un paquete válido con todas las referencias disponibles;
  • un campo obligatorio ausente;
  • un taskId de otra ejecución;
  • una versión de estado anterior a la actual;
  • una herramienta solicitada fuera de la autoridad del receptor;
  • evidencia que apunta a un artefacto eliminado o sustituido;
  • una transferencia repetida después de una confirmación;
  • un rechazo que produce reparación, escalamiento o parada según la política.

Para cada caso, comprueba algo más que la respuesta final. Confirma qué agente recibió el control, qué herramientas se expusieron, qué estado se persistió y si el rechazo impidió efectos externos. Si la prueba solo examina la frase final, no puede saber si el receptor recibió un permiso que no debía tener.

Una traza también ayuda a depurar la frontera, pero no sustituye el contrato. Registra el identificador de la tarea, la versión del paquete, el agente de origen, el agente de destino, el resultado de la validación y el motivo del rechazo. Evita registrar todo el historial por defecto.

¿Cuáles son los límites de este patrón?

Un handoff no vuelve confiable a un grupo de agentes por sí solo. Hace explícito el cambio de responsabilidad. Todavía necesitas estado persistente, política de herramientas, límites de coste, timeouts, observabilidad y una forma de reparar datos antiguos.

También existe un coste de coordinación. Un agente con herramientas puede resolver una tarea corta con menos contratos, puntos de fallo y contexto duplicado. La guía de orquestación de OpenAI Agents SDK, consultada el 25/09/2026, presenta handoffs y agentes como herramientas como elecciones complementarias, no como una escalera automática de madurez.

Los nombres y formatos cambian entre SDKs. inputType e inputFilter son mecanismos de OpenAI Agents SDK. La idea duradera es la frontera: un paquete versionado, validable, con autoridad limitada y una ruta de recuperación. Si cambia el proveedor, puedes cambiar el adaptador sin esconder la responsabilidad en el prompt.

Conclusión

Un handoff confiable permite que el segundo agente empiece sin repetir la investigación ni heredar permisos por accidente. Trata la transferencia como una interfaz: escribe el siguiente objetivo, el estado confirmado, la evidencia, la autoridad, la aceptación y la recuperación.

Valida el paquete en el receptor. Filtra el historial respetando el protocolo del runtime. Persiste la transferencia cuando cruce procesos. Prueba estado antiguo, herramientas prohibidas, evidencia ausente y repetición. El modelo puede elegir cuándo pedir un handoff, pero el código debe decidir si la transferencia es válida.

Cómo se hizo este análisis

Samuel Fajreldines es el autor responsable de este artículo. La investigación comparó la documentación actual de OpenAI Agents SDK y LangChain, los owners existentes de orquestación, contexto, ejecución durable y trayectoria, y discusiones públicas recientes. El contrato de seis partes, el schema y la matriz de rechazos son síntesis editorial original. El código es ilustrativo y no se ejecutó contra un proveedor ni un runtime multiagente. La asistencia de IA apoyó el descubrimiento, la redacción, la generación de la imagen, la localización y la revisión de consistencia; no aportó experiencia de producción ni sustituyó la verificación de fuentes. El autor también mantiene RemoteCode como herramienta de trabajo.

Fuentes consultadas