Respostas em segundo plano

Use o modo background quando uma resposta puder levar muito tempo para ser concluída, como no uso de ferramentas em várias etapas ou em tarefas de geração extensas. A API retorna imediatamente com uma resposta enfileirada, e você recupera o resultado mais tarde por polling ou streaming.

Criar uma resposta em segundo plano

Defina background como true e stream como false. A API cria a resposta, inicia seu processamento de forma assíncrona e retorna imediatamente com status: "queued".

mka1 llm responses create \
  --background \
  --model meetkai:functionary-pt \
  --input '"Escreva um ensaio de 500 palavras sobre a história da internet."' \
  -H 'X-On-Behalf-Of: <end-user-id>'

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

const mka1 = new SDK({
  bearerAuth: `Bearer ${YOUR_API_KEY}`,
});

const response = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>', // opcional — atribua a solicitação a um dos seus usuários finais
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    input: 'Escreva um ensaio de 500 palavras sobre a história da internet.',
    background: true,
    stream: false,
  },
}) as ResponseObject;

console.log(response.id, response.status); // resp_abc123 queued

import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const response = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Escreva um ensaio de 500 palavras sobre a história da internet.',
  background: true,
  stream: false,
});

console.log(response.id, response.status); // resp_abc123 queued

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var res = await sdk.Llm.Responses.CreateAsync(
    body: new ResponsesCreateRequest()
    {
        Model = "meetkai:functionary-pt",
        Input = ResponsesCreateRequestInput.CreateStr(
            "Escreva um ensaio de 500 palavras sobre a história da internet."),
        Background = true,
        Stream = false,
    },
    xOnBehalfOf: "<end-user-id>" // opcional — atribua a solicitação a um dos seus usuários finais
);

Console.WriteLine($"{res.ResponseObject!.Id} {res.ResponseObject!.Status}"); // resp_abc123 queued

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

res = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Escreva um ensaio de 500 palavras sobre a história da internet.",
    background=True,
    stream=False,
    x_on_behalf_of="<end-user-id>",  # opcional — atribua a solicitação a um dos seus usuários finais
)

print(res.id, res.status)  # resp_abc123 queued

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",
    "input": "Escreva um ensaio de 500 palavras sobre a história da internet.",
    "background": true,
    "stream": false
  }'

Salve o id para recuperar o resultado mais tarde.

Consultar o resultado por polling

Chame GET /responses/{response_id} até que o status atinja um estado terminal.

mka1 llm responses get --response-id resp_abc123

let polled = await mka1.llm.responses.get({
  responseId: response.id,
  xOnBehalfOf: '<end-user-id>',
}) as ResponseObject;

while (polled.status === 'queued' || polled.status === 'in_progress') {
  await new Promise(r => setTimeout(r, 2000));
  polled = await mka1.llm.responses.get({
    responseId: response.id,
    xOnBehalfOf: '<end-user-id>',
  }) as ResponseObject;
}

console.log(polled.status); // completed
console.log(polled.output);

let polled = await openai.responses.retrieve(response.id);

while (polled.status === 'queued' || polled.status === 'in_progress') {
  await new Promise(r => setTimeout(r, 2000));
  polled = await openai.responses.retrieve(response.id);
}

console.log(polled.status); // completed
console.log(polled.output);

var polled = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
{
    ResponseId = res.ResponseObject!.Id,
    XOnBehalfOf = "<end-user-id>",
});

while (polled.ResponseObject!.Status == "queued" || polled.ResponseObject!.Status == "in_progress")
{
    await Task.Delay(2000);
    polled = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
    {
        ResponseId = res.ResponseObject!.Id,
        XOnBehalfOf = "<end-user-id>",
    });
}

Console.WriteLine(polled.ResponseObject!.Status); // completed

import time

polled = sdk.llm.responses.get(
    response_id=res.id,
    x_on_behalf_of="<end-user-id>",
)

while polled.status in ("queued", "in_progress"):
    time.sleep(2)
    polled = sdk.llm.responses.get(
        response_id=res.id,
        x_on_behalf_of="<end-user-id>",
    )

print(polled.status)  # completed
print(polled.output)

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123 \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Uma resposta passa por estes status durante o processamento:

Status	Significado
`queued`	A solicitação está aguardando para ser processada
`in_progress`	O modelo está gerando saída
`completed`	A geração foi concluída com sucesso
`failed`	Ocorreu um erro durante o processamento
`incomplete`	A resposta foi interrompida (por exemplo, limite de tokens)
`cancelled`	A resposta foi cancelada antes da conclusão

Faça polling em um intervalo razoável (por exemplo, a cada dois segundos) até que o status não seja mais queued ou in_progress.

Transmitir eventos de uma resposta em segundo plano

Se quiser atualizações em tempo real em vez de polling, recupere a resposta com stream definido como true. A API retorna eventos enviados pelo servidor à medida que a resposta é processada.

mka1 llm responses get --response-id resp_abc123 --stream

const streamed = await mka1.llm.responses.get({
  responseId: response.id,
  stream: true,
  xOnBehalfOf: '<end-user-id>',
});

const stream = await openai.responses.retrieve(response.id, {
  stream: true,
});

for await (const event of stream) {
  console.log(event.type);
}

var streamed = await sdk.Llm.Responses.GetAsync(new GetResponseRequest()
{
    ResponseId = res.ResponseObject!.Id,
    Stream = true,
    XOnBehalfOf = "<end-user-id>",
});

from meetkai_mka1.responses import GetAcceptEnum

streamed = sdk.llm.responses.get(
    response_id=res.id,
    stream=True,
    accept_header_override=GetAcceptEnum.TEXT_EVENT_STREAM,
    x_on_behalf_of="<end-user-id>",
)

for event in streamed:
    print(event.data.type)

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123?stream=true \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Os eventos chegam à medida que são produzidos. O stream é fechado após um evento terminal, como response.completed ou response.failed. Se a resposta já tiver sido concluída quando você chamar este endpoint, receberá um único evento terminal com a resposta final, e o stream será fechado imediatamente.

Transmitir eventos no momento da criação

Você também pode transmitir eventos diretamente ao criar uma resposta em segundo plano definindo background e stream como true.

mka1 llm responses create \
  --background \
  --stream \
  --model meetkai:functionary-pt \
  --input '"Escreva um ensaio de 500 palavras sobre a história da internet."'

const result = await mka1.llm.responses.create({
  xOnBehalfOf: '<end-user-id>',
  responsesCreateRequest: {
    model: 'meetkai:functionary-pt',
    input: 'Escreva um ensaio de 500 palavras sobre a história da internet.',
    background: true,
    stream: true,
  },
});

const stream = await openai.responses.create({
  model: 'meetkai:functionary-pt',
  input: 'Escreva um ensaio de 500 palavras sobre a história da internet.',
  background: true,
  stream: true,
});

for await (const event of stream) {
  console.log(event.type);
  // response.queued → response.created → ... → response.completed
}

var res = await sdk.Llm.Responses.CreateAsync(
    body: new ResponsesCreateRequest()
    {
        Model = "meetkai:functionary-pt",
        Input = ResponsesCreateRequestInput.CreateStr(
            "Escreva um ensaio de 500 palavras sobre a história da internet."),
        Background = true,
        Stream = true,
    },
    xOnBehalfOf: "<end-user-id>"
);

stream = sdk.llm.responses.create(
    model="meetkai:functionary-pt",
    input="Escreva um ensaio de 500 palavras sobre a história da internet.",
    background=True,
    stream=True,
    x_on_behalf_of="<end-user-id>",
)

for event in stream:
    print(event.data.type)
    # response.queued → response.created → ... → response.completed

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",
    "input": "Escreva um ensaio de 500 palavras sobre a história da internet.",
    "background": true,
    "stream": true
  }'

O primeiro evento é response.queued, seguido por response.created, eventos intermediários como response.output_text.delta e, por fim, um evento terminal como response.completed. Isso é útil quando você deseja mostrar o progresso em uma interface enquanto o trabalho é executado em segundo plano. Se o cliente se desconectar, a resposta continuará sendo processada e poderá ser recuperada mais tarde.

Cancelar uma resposta em segundo plano

Se você não precisar mais do resultado, cancele uma resposta enfileirada ou em andamento.

mka1 llm responses cancel --response-id resp_abc123

const cancelled = await mka1.llm.responses.cancel({
  responseId: response.id,
  xOnBehalfOf: '<end-user-id>',
});

console.log(cancelled.status); // cancelled

const cancelled = await openai.responses.cancel(response.id);

console.log(cancelled.status); // cancelled

var cancelled = await sdk.Llm.Responses.CancelAsync(
    responseId: res.ResponseObject!.Id,
    xOnBehalfOf: "<end-user-id>"
);

Console.WriteLine(cancelled.Status); // cancelled

cancelled = sdk.llm.responses.cancel(
    response_id=res.id,
    x_on_behalf_of="<end-user-id>",
)

print(cancelled.status)  # cancelled

curl https://apigw.mka1.com/api/v1/llm/responses/resp_abc123/cancel \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

O status da resposta muda para cancelled. Respostas que já foram concluídas ou falharam não podem ser canceladas.

Próximas etapas

Consulte gerar uma resposta para conhecer os conceitos básicos de criação de respostas
Consulte gerenciar agentes quando quiser definições de agentes reutilizáveis e execuções persistentes
Consulte a referência da API Responses para ver a lista completa de parâmetros e campos de resposta

⌘I

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Respostas em segundo plano

Criar uma resposta em segundo plano

Consultar o resultado por polling

Transmitir eventos de uma resposta em segundo plano

Transmitir eventos no momento da criação

Cancelar uma resposta em segundo plano

Próximas etapas

​Criar uma resposta em segundo plano

​Consultar o resultado por polling

​Transmitir eventos de uma resposta em segundo plano

​Transmitir eventos no momento da criação

​Cancelar uma resposta em segundo plano

​Próximas etapas

Criar uma resposta em segundo plano

Consultar o resultado por polling

Transmitir eventos de uma resposta em segundo plano

Transmitir eventos no momento da criação

Cancelar uma resposta em segundo plano

Próximas etapas