Orquestación y transferencias de control

Los flujos de trabajo con varios agentes son útiles cuando distintos especialistas deben encargarse de diferentes partes de una tarea. La primera decisión de diseño es definir quién dará la respuesta final al usuario en cada rama del flujo de trabajo.

Elige el patrón de orquestación

Usa transferencias de control para delegar la respuesta

Las transferencias de control son la opción más adecuada cuando el especialista debe responder directamente en el siguiente turno en vez de limitarse a ayudar en segundo plano.

1
2
3
4
5
6
7
8
9import { Agent, handoff } from "@openai/agents";

const billingAgent = new Agent({ name: "Billing agent" });
const refundAgent = new Agent({ name: "Refund agent" });

const triageAgent = Agent.create({
  name: "Triage agent",
  handoffs: [billingAgent, handoff(refundAgent)],
});

1
2
3
4
5
6
7
8
9from agents import Agent, handoff

billing_agent = Agent(name="Billing agent")
refund_agent = Agent(name="Refund agent")

triage_agent = Agent(
    name="Triage agent",
    handoffs=[billing_agent, handoff(refund_agent)],
)

Deja claro cuándo debe intervenir cada especialista:

• Asigna a cada especialista una tarea bien delimitada.
• Escribe una descripción breve y concreta en handoffDescription.
• Crea una rama solo si realmente requiere instrucciones, herramientas o políticas diferentes.

En casos más avanzados, las transferencias de control también pueden incluir metadatos estructurados o un historial filtrado. Consulta las API específicas en la documentación del SDK, ya que la forma de integrarlas varía según el lenguaje.

Usa agentes como herramientas en flujos de trabajo con un coordinador

Usa agent.asTool() cuando el agente principal deba seguir a cargo de la respuesta final y recurrir a especialistas como apoyo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { Agent } from "@openai/agents";

const summarizer = new Agent({
  name: "Summarizer",
  instructions: "Generate a concise summary of the supplied text.",
});

const mainAgent = new Agent({
  name: "Research assistant",
  tools: [
    summarizer.asTool({
      toolName: "summarize_text",
      toolDescription: "Generate a concise summary of the supplied text.",
    }),
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from agents import Agent

summarizer = Agent(
    name="Summarizer",
    instructions="Generate a concise summary of the supplied text.",
)

main_agent = Agent(
    name="Research assistant",
    tools=[
        summarizer.as_tool(
            tool_name="summarize_text",
            tool_description="Generate a concise summary of the supplied text.",
        )
    ],
)

Esta suele ser la mejor opción cuando:

• el coordinador debe integrar los aportes en la respuesta final
• el especialista realiza una tarea acotada, como resumir o clasificar información
• quieres mantener un único flujo de trabajo principal estable con llamadas anidadas a especialistas, sin transferirles el control

Agrega especialistas solo cuando cambie el contrato

Empieza con un solo agente siempre que puedas. Agrega especialistas solo si hacerlo te permite aislar mejor las capacidades o las políticas, redactar prompts más claros o facilitar la lectura de las trazas. La mejora debe ser significativa.

Dividir el trabajo demasiado pronto genera más prompts, más trazas y más puntos que requieren aprobación, sin que el flujo de trabajo necesariamente mejore.

Próximos pasos

Una vez que hayas definido quién se encarga de la respuesta, continúa con la guía que aborde tu siguiente duda sobre la ejecución o el estado.