Gerar subagentes usando a API Responses

Use este padrão quando quiser que uma resposta divida o trabalho em tarefas menores. Este padrão implementa um loop síncrono de delegação para respostas filhas. Uma resposta pai chama uma ferramenta de função que seu aplicativo resolve executando outra solicitação Responses. Um resultado filho ou vários resultados filhos são retornados ao pai como function_call_output, e o pai continua a geração. Uma resposta filha às vezes é chamada de subagente. Neste guia, ela é apenas outra solicitação Responses que executa uma tarefa focada. Resposta pai -> function_call spawn_subagent -> seu aplicativo executa uma ou mais respostas filhas -> resultados filhos retornados como function_call_output -> resposta pai retoma a geração

Como o loop funciona

Neste padrão, a resposta pai pausa sempre que chama spawn_subagent. Seu aplicativo executa as tarefas delegadas e então retoma o pai com os resultados.

Crie uma resposta pai com uma ferramenta de função spawn_subagent.
Quando o modelo chamar a ferramenta, analise os argumentos de cada chamada de ferramenta.
Execute uma ou mais solicitações Responses filhas para realizar as tarefas delegadas.
Aguarde a conclusão de todas as respostas filhas.
Retorne cada resultado filho como function_call_output usando o call_id correspondente.
Retome a resposta pai com previous_response_id.
Repita até que o pai produza uma message normal do assistente.

Definir uma ferramenta para delegação

Mantenha a ferramenta focada. Passe apenas os campos de que a resposta filha precisa.

{
  "type": "function",
  "name": "spawn_subagent",
  "description": "Delegue uma tarefa focada a uma resposta filha e retorne o resultado.",
  "strict": true,
  "parameters": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "A tarefa para a resposta filha."
      },
      "instructions": {
        "type": "string",
        "description": "Instruções opcionais para a resposta filha."
      },
      "model": {
        "type": "string",
        "description": "Substituição opcional de modelo para a resposta filha."
      }
    },
    "required": ["task"],
    "additionalProperties": false
  }
}

Use tool_choice: "auto" quando o modelo deve decidir quando delegar. Use tool_choice: "required" quando cada turno deve passar por uma ferramenta.

Receita do SDK TypeScript

Este exemplo usa sdk.llm.responses.create tanto para as respostas pai quanto para as filhas. Ele permite que o pai emita várias chamadas spawn_subagent em um único turno. Seu aplicativo executa essas respostas filhas simultaneamente, aguarda a conclusão de todas elas e então retoma o pai uma vez com cada resultado de ferramenta. Mantenha cada resultado filho pequeno para que o pai possa usá-lo no próximo turno sem consumir muito contexto.

import { SDK } from "@meetkai/mka1";
import type { ResponseObject } from "@meetkai/mka1/models/components";

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

const spawnSubagentTool = {
  type: "function" as const,
  name: "spawn_subagent",
  description: "Delegue uma tarefa focada a uma resposta filha e retorne o resultado.",
  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({
    responsesCreateRequest: {
      model: args.model ?? "meetkai:functionary-pt",
      instructions:
        args.instructions ??
        "Você é um assistente especialista. Conclua a tarefa e retorne apenas o resultado.",
      input: args.task,
      store: true,
    },
  }) as ResponseObject;

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

export async function runDelegatingAgent(input: string) {
  let response = await sdk.llm.responses.create({
    responsesCreateRequest: {
      model: "meetkai:functionary-pt",
      instructions:
        "Você é um orquestrador. Use spawn_subagent para tarefas paralelas focadas. Você pode chamá-lo várias vezes em um turno quando as tarefas puderem ser paralelizadas. Após o retorno de todos os resultados das ferramentas, responda diretamente ao usuário.",
      input,
      tools: [spawnSubagentTool],
      toolChoice: "auto",
      parallelToolCalls: true,
      maxToolCalls: 8,
      store: true,
    },
  }) as ResponseObject;

  while (true) {
    const toolCalls = response.output.filter(
      (item): item is {
        type: "function_call";
        name: string;
        callId: 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,
          callId: toolCall.callId,
          output: JSON.stringify(childResult),
        };
      }),
    );

    response = await sdk.llm.responses.create({
      responsesCreateRequest: {
        model: response.model,
        previousResponseId: response.id,
        input: toolOutputs,
        tools: [spawnSubagentTool],
        parallelToolCalls: true,
        maxToolCalls: 8,
        store: true,
      },
    }) as ResponseObject;
  }
}

Distribuir e aguardar todas as respostas filhas

Quando parallel_tool_calls é true, o pai pode emitir vários itens function_call em um único turno. Trate esse conjunto de chamadas de ferramenta como um lote. Inicie todas as respostas filhas, aguarde a conclusão de todas e só então retome o pai. Isso cria uma barreira:

A resposta pai emite muitos itens function_call.
Seu aplicativo inicia muitas respostas filhas.
Seu aplicativo aguarda a conclusão de todas as respostas filhas.
Seu aplicativo envia todos os itens function_call_output de volta em uma solicitação de acompanhamento.
A resposta pai continua com o conjunto completo de resultados delegados.

Se você retomar o pai antecipadamente apenas com parte do lote, o modelo continuará sem os resultados ausentes. Isso geralmente torna a orquestração menos previsível. A etapa principal de convergência é semelhante a esta:

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,
        callId: toolCall.callId,
        output: JSON.stringify(childResult),
    };
  }),
);

Se seu aplicativo atuar em nome de um usuário final, envie o mesmo valor de X-On-Behalf-Of nas solicitações pai e filha. Se uma resposta filha puder demorar mais, você poderá definir background: true na solicitação filha e consultar com sdk.llm.responses.get até que ela seja concluída. Quando distribuir para várias respostas filhas, aguarde até que todos os resultados filhos estejam disponíveis antes de retomar a resposta pai.

Solicitação Responses bruta para a etapa de retomada

A transferência crítica é a solicitação de acompanhamento. Você passa cada resultado de ferramenta de volta em input e aponta para o turno pai anterior com 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-pt",
    "previous_response_id": "resp_parent123",
    "input": [
      {
        "type": "function_call_output",
        "call_id": "call_abc123",
        "output": "{\"response_id\":\"resp_child456\",\"output_text\":\"Pesquisa concluída. Recomenda-se uma implantação em etapas.\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_def456",
        "output": "{\"response_id\":\"resp_child789\",\"output_text\":\"Rascunho concluído. Título: Implantação mais rápida com menor risco.\"}"
      }
    ]
  }'

Se você não estiver atuando em nome de um usuário final, omita X-On-Behalf-Of.

Tratamento básico de erros e recuperação

Em sistemas reais, este loop às vezes falhará. Falhas comuns incluem argumentos de ferramenta malformados, tempos limite de solicitação filha, erros upstream 5xx, limites de taxa e saídas filhas fracas demais para serem úteis. O padrão mais seguro é:

Analise os argumentos da ferramenta de forma defensiva.
Tente novamente falhas transitórias de solicitações filhas um pequeno número de vezes com recuo.
Retorne uma carga estruturada de falha ao pai em vez de interromper todo o lote quando um filho falhar.
Mantenha os resultados filhos pequenos e explícitos para que o pai possa decidir se deve continuar, tentar novamente ou responder com resultados parciais.

Uma abordagem simples é encapsular a execução filha e sempre retornar um objeto de sucesso ou um objeto de erro:

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 requer uma tarefa de texto",
      };
    }
  } catch {
    return {
      ok: false,
      error_code: "invalid_arguments",
      message: "Não foi possível analisar os argumentos de spawn_subagent como JSON",
    };
  }

  for (let attempt = 0; attempt < 3; attempt += 1) {
    try {
      const child = await sdk.llm.responses.create({
        responsesCreateRequest: {
          model: args.model ?? "meetkai:functionary-pt",
          instructions:
            args.instructions ??
            "Você é um assistente especialista. Conclua a tarefa e retorne apenas o resultado.",
          input: args.task,
          store: true,
        },
      }) as ResponseObject;

      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 : "A resposta filha falhou",
        };
      }

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

  return {
    ok: false,
    error_code: "child_request_failed",
    message: "A resposta filha falhou",
  };
}

Em seguida, envie os resultados de volta ao pai mesmo que alguns filhos falhem:

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

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

Isso permite que o pai veja falhas parciais e continue raciocinando. Por exemplo, o pai pode decidir tentar novamente com uma tarefa mais restrita, iniciar um subagente substituto ou responder com os resultados filhos bem-sucedidos disponíveis enquanto informa a lacuna. Para filhos de longa duração, você também pode combinar isso com background: true e consulta. A lógica de recuperação permanece a mesma: aguarde o filho alcançar um estado terminal e, em seguida, retorne ao pai uma carga de sucesso ou uma carga estruturada de falha.

Limites práticos

Mantenha parallel_tool_calls definido como true quando o pai deve poder delegar várias respostas filhas em um único turno.
Defina parallel_tool_calls como false apenas quando as respostas filhas compartilham estado ou precisam ser executadas em ordem.
Defina max_tool_calls para que uma resposta pai não possa entrar em loop para sempre.
Mantenha as saídas filhas compactas para que o pai possa incorporar o resultado sem consumir muito contexto.
Mantenha store: true enquanto cria o fluxo de trabalho para que você possa inspecionar posteriormente as respostas pai e filha.
Use a página de itens de entrada Responses na Referência da API quando precisar depurar os itens exatos enviados de volta ao modelo.

Veja também

Consulte fazer pesquisa aprofundada com subagentes para uma implementação concreta deste padrão orientada à pesquisa. Consulte gerar uma resposta para o padrão básico de solicitação Responses. Use gerenciar conversas quando quiser que o fluxo de trabalho pai ou filho mantenha estado durável fora de uma única cadeia de respostas.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Gerar subagentes usando a API Responses

Como o loop funciona

Definir uma ferramenta para delegação

Receita do SDK TypeScript

Distribuir e aguardar todas as respostas filhas

Solicitação Responses bruta para a etapa de retomada

Tratamento básico de erros e recuperação

Limites práticos

Veja também

​Como o loop funciona

​Definir uma ferramenta para delegação

​Receita do SDK TypeScript

​Distribuir e aguardar todas as respostas filhas

​Solicitação Responses bruta para a etapa de retomada

​Tratamento básico de erros e recuperação

​Limites práticos

​Veja também

Como o loop funciona

Definir uma ferramenta para delegação

Receita do SDK TypeScript

Distribuir e aguardar todas as respostas filhas

Solicitação Responses bruta para a etapa de retomada

Tratamento básico de erros e recuperação

Limites práticos

Veja também