Generar subagentes usando la API de Respuestas

Utiliza este patrón cuando quieras que una respuesta divida el trabajo en tareas más pequeñas. Este patrón implementa un bucle síncrono de delegación de respuestas hijas. Una respuesta padre llama a una herramienta de función que tu aplicación resuelve ejecutando otra solicitud de Responses. Uno o varios resultados hijos se devuelven al padre como function_call_output, y el padre continúa la generación. Una respuesta hija a veces se llama subagente. En esta guía, es simplemente otra solicitud de Responses que realiza una tarea enfocada. Respuesta padre -> function_call spawn_subagent -> tu aplicación ejecuta una o más respuestas hijas -> los resultados hijos se devuelven como function_call_output -> la respuesta padre reanuda la generación

Cómo funciona el bucle

En este patrón, la respuesta padre se pausa cada vez que llama a spawn_subagent. Tu aplicación ejecuta las tareas delegadas y luego reanuda el padre con los resultados.

Crea una respuesta padre con una herramienta de función spawn_subagent.
Cuando el modelo llama a la herramienta, analiza los argumentos de cada llamada a la herramienta.
Ejecuta una o más solicitudes de Responses hijas para realizar las tareas delegadas.
Espera a que todas las respuestas hijas finalicen.
Devuelve cada resultado hijo como function_call_output usando el call_id correspondiente.
Reanuda la respuesta padre con previous_response_id.
Repite hasta que el padre produzca un message normal de asistente.

Define una herramienta para delegación

Mantén la herramienta enfocada. Pasa solo los campos que la respuesta hija necesita.

{
  "type": "function",
  "name": "spawn_subagent",
  "description": "Delegar una tarea enfocada a una respuesta hija y devolver el resultado.",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "La tarea para la respuesta hija."
      },
      "instructions": {
        "type": "string",
        "description": "Instrucciones opcionales para la respuesta hija."
      },
      "model": {
        "type": "string",
        "description": "Modelo opcional para la respuesta hija."
      }
    },
    "required": ["task"],
    "additionalProperties": false
  }
}

Usa tool_choice: "auto" cuando el modelo deba decidir cuándo delegar. Usa tool_choice: "required" cuando cada turno deba pasar por una herramienta.

Receta SDK TypeScript

Este ejemplo utiliza sdk.llm.responses.create tanto para las respuestas padre como para las hijas. Permite que el padre emita múltiples llamadas a spawn_subagent en un solo turno. Tu aplicación ejecuta esas respuestas hijas en paralelo, espera a que todas finalicen y luego reanuda el padre una sola vez con todos los resultados de las herramientas. Mantén cada resultado hijo pequeño para que el padre pueda usarlo en el siguiente turno sin consumir demasiado contexto.

import { SDK } from "@meetkai/mka1";

const sdk = new SDK({
  bearerAuth: process.env.MKA1_API_KEY!,
});

const spawnSubagentTool = {
  type: "function" as const,
  name: "spawn_subagent",
  description: "Delegate a focused task to a child response and return the result.",
  strict: true,
  parameters: {
    type: "object",
    properties: {
      task: { type: "string" },
      instructions: { type: "string" },
      model: { type: "string" },
    },
    required: ["task"],
    additionalProperties: false,
  },
};

type SpawnSubagentArgs = {
  task: string;
  instructions?: string;
  model?: string;
};

async function runChildResponse(args: SpawnSubagentArgs) {
  const child = await sdk.llm.responses.create({
    model: args.model ?? "meetkai:functionary-es-mini",
    instructions:
      args.instructions ??
      "Eres un asistente especialista. Completa la tarea y devuelve solo el resultado.",
    input: args.task,
    store: true,
  });

  return {
    response_id: child.id,
    output_text: child.outputText,
  };
}

export async function runDelegatingAgent(input: string) {
  let response = await sdk.llm.responses.create({
    model: "meetkai:functionary-es-mini",
    instructions:
      "Eres un orquestador. Usa spawn_subagent para tareas laterales enfocadas. Puedes llamarlo varias veces en un turno cuando las tareas puedan paralelizarse. Después de que todos los resultados de las herramientas regresen, responde directamente al usuario.",
    input,
    tools: [spawnSubagentTool],
    tool_choice: "auto",
    parallel_tool_calls: true,
    max_tool_calls: 8,
    store: true,
  });

  while (true) {
    const toolCalls = response.output.filter(
      (item): item is {
        type: "function_call";
        name: string;
        call_id: string;
        arguments: string;
      } => item.type === "function_call" && item.name === "spawn_subagent",
    );

    if (toolCalls.length === 0) {
      return response.outputText;
    }

    const toolOutputs = await Promise.all(
      toolCalls.map(async (toolCall) => {
        const args = JSON.parse(toolCall.arguments) as SpawnSubagentArgs;
        const childResult = await runChildResponse(args);

        return {
          type: "function_call_output" as const,
          call_id: toolCall.call_id,
          output: JSON.stringify(childResult),
        };
      }),
    );

    response = await sdk.llm.responses.create({
      model: response.model,
      previous_response_id: response.id,
      input: toolOutputs,
      tools: [spawnSubagentTool],
      parallel_tool_calls: true,
      max_tool_calls: 8,
      store: true,
    });
  }
}

Ramifica y espera a todas las respuestas hijas

Cuando parallel_tool_calls es true, el padre puede emitir varios elementos function_call en un turno. Trata ese conjunto de llamadas a herramientas como un lote. Inicia todas las respuestas hijas, espera a que todas finalicen y solo entonces reanuda el padre. Esto crea una barrera:

La respuesta padre emite muchos elementos function_call.
Tu aplicación inicia muchas respuestas hijas.
Tu aplicación espera a que todas las respuestas hijas finalicen.
Tu aplicación envía todos los elementos function_call_output en una sola solicitud de seguimiento.
La respuesta padre continúa con el conjunto completo de resultados delegados.

Si reanudas el padre antes con solo parte del lote, el modelo continúa sin los resultados faltantes. Eso generalmente hace que la orquestación sea menos predecible. El paso clave de fan-in se ve así:

const toolOutputs = await Promise.all(
  toolCalls.map(async (toolCall) => {
    const args = JSON.parse(toolCall.arguments) as SpawnSubagentArgs;
    const childResult = await runChildResponse(args);

    return {
        type: "function_call_output" as const,
        call_id: toolCall.call_id,
        output: JSON.stringify(childResult),
    };
  }),
);

Si tu aplicación actúa en nombre de un usuario final, envía el mismo valor de X-On-Behalf-Of en las solicitudes padre e hijas. Si una respuesta hija puede tardar más, puedes establecer background: true en la solicitud hija y hacer polling con sdk.llm.responses.get hasta que finalice. Cuando ramifiques a múltiples respuestas hijas, espera hasta que todos los resultados hijos estén disponibles antes de reanudar la respuesta padre.

Solicitud Responses sin procesar para el paso de reanudación

La transferencia crítica es la solicitud de seguimiento. Debes pasar cada resultado de herramienta en input y apuntar al turno anterior del padre con previous_response_id.

bash

curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-es-mini",
    "previous_response_id": "resp_parent123",
    "input": [
      {
        "type": "function_call_output",
        "call_id": "call_abc123",
        "output": "{\"response_id\":\"resp_child456\",\"output_text\":\"Investigación completa. Recomiendo un despliegue escalonado.\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_def456",
        "output": "{\"response_id\":\"resp_child789\",\"output_text\":\"Borrador completo. Titular: Despliegue más rápido con menor riesgo.\"}"
      }
    ]
  }'

Si no actúas en nombre de un usuario final, omite X-On-Behalf-Of.

Manejo básico de errores y recuperación

En sistemas reales, este bucle fallará a veces. Los fallos comunes incluyen argumentos de herramienta mal formados, tiempos de espera en solicitudes hijas, errores 5xx aguas arriba, límites de tasa y salidas hijas demasiado débiles para ser útiles. El patrón más seguro es:

Analiza los argumentos de la herramienta de forma defensiva.
Reintenta fallos transitorios de solicitudes hijas un pequeño número de veces con retroceso.
Devuelve una carga útil de fallo estructurada al padre en vez de fallar todo el lote cuando una hija falla.
Mantén los resultados hijos pequeños y explícitos para que el padre pueda decidir si continuar, reintentar o responder con resultados parciales.

Un enfoque simple es envolver la ejecución hija y devolver siempre un objeto de éxito o de error:

type ChildSuccess = {
  ok: true;
  response_id: string;
  output_text: string;
};

type ChildFailure = {
  ok: false;
  error_code: "invalid_arguments" | "child_request_failed";
  message: string;
};

type ChildResult = ChildSuccess | ChildFailure;

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function runChildResponseWithRecovery(rawArgs: string): Promise<ChildResult> {
  let args: SpawnSubagentArgs;

  try {
    args = JSON.parse(rawArgs) as SpawnSubagentArgs;
    if (!args.task || typeof args.task !== "string") {
      return {
        ok: false,
        error_code: "invalid_arguments",
        message: "spawn_subagent requiere una tarea tipo string",
      };
    }
  } catch {
    return {
      ok: false,
      error_code: "invalid_arguments",
      message: "No se pudieron analizar los argumentos de spawn_subagent como JSON",
    };
  }

  for (let attempt = 0; attempt < 3; attempt += 1) {
    try {
      const child = await sdk.llm.responses.create({
        model: args.model ?? "meetkai:functionary-es-mini",
        instructions:
          args.instructions ??
          "Eres un asistente especialista. Completa la tarea y devuelve solo el resultado.",
        input: args.task,
        store: true,
      });

      return {
        ok: true,
        response_id: child.id,
        output_text: child.outputText,
      };
    } catch (error) {
      const isLastAttempt = attempt === 2;
      if (isLastAttempt) {
        return {
          ok: false,
          error_code: "child_request_failed",
          message:
            error instanceof Error ? error.message : "La respuesta hija falló",
        };
      }

      await sleep(500 * (attempt + 1));
    }
  }

  return {
    ok: false,
    error_code: "child_request_failed",
    message: "La respuesta hija falló",
  };
}

Luego, reenvía los resultados al padre incluso si algunas hijas fallan:

const toolOutputs = await Promise.all(
  toolCalls.map(async (toolCall) => {
    const childResult = await runChildResponseWithRecovery(toolCall.arguments);

    return {
      type: "function_call_output" as const,
      call_id: toolCall.call_id,
      output: JSON.stringify(childResult),
    };
  }),
);

Esto permite que el padre vea fallos parciales y continúe razonando. Por ejemplo, el padre puede decidir reintentar con una tarea más acotada, lanzar un subagente de reemplazo o responder con los resultados hijos exitosos disponibles mientras señala la ausencia. Para hijas de larga duración, también puedes combinar esto con background: true más polling. La lógica de recuperación permanece igual: espera a que la hija alcance un estado terminal, luego devuelve al padre una carga útil de éxito o de fallo estructurado.

Límites prácticos

Mantén parallel_tool_calls en true cuando el padre deba poder delegar varias respuestas hijas en un turno.
Establece parallel_tool_calls en false solo cuando las respuestas hijas compartan estado o deban ejecutarse en orden.
Configura max_tool_calls para que una respuesta padre no pueda buclear indefinidamente.
Mantén las salidas hijas compactas para que el padre pueda incorporar el resultado sin consumir demasiado contexto.
Mantén store: true mientras construyes el flujo de trabajo para poder inspeccionar respuestas padre e hijas después.
Usa la página de elementos de entrada de Responses en la Referencia de API cuando necesites depurar los elementos exactos enviados de vuelta al modelo.

Ver también

Revisa realizar investigación profunda con subagentes para una implementación concreta orientada a investigación de este patrón. Revisa generar una respuesta para el patrón base de solicitud de Responses. Utiliza gestionar conversaciones cuando quieras que el flujo de trabajo padre o hijo mantenga estado duradero fuera de una sola cadena de respuestas.

​Cómo funciona el bucle

​Define una herramienta para delegación

​Receta SDK TypeScript

​Ramifica y espera a todas las respuestas hijas

​Solicitud Responses sin procesar para el paso de reanudación

​Manejo básico de errores y recuperación

​Límites prácticos

​Ver también