Delegação e ferramentas no GPT-Live

Configure a delegação via Responses

Adicione esta configuração de delegação ao criar sua sessão Live. Escolha o modelo do Responses independentemente do modelo de voz:

1
2
3
4
5
6
7
8
9
10export const session = {
  model: "gpt-live-1",
  delegation: {
    type: "responses",
    responses: {
      model: "gpt-5.6-terra",
      instructions: "[Your backend prompt]",
    },
  },
};

1
2
3
4
5
6
7
8
9
10
11
12from openai.types.live.session_config_param import SessionConfigParam

session: SessionConfigParam = {
    "model": "gpt-live-1",
    "delegation": {
        "type": "responses",
        "responses": {
            "model": "gpt-5.6-terra",
            "instructions": "[Your backend prompt]",
        },
    },
}

Comece com o GPT-5.6 Terra ou experimente o GPT-5.6 Luna para cargas de trabalho sensíveis ao custo. Compare a qualidade das respostas e a latência nas suas tarefas antes de escolher um modelo de backend.

Registre as ferramentas compatíveis em delegation.responses.tools. Use delegation.responses.tool_choice para controlar quais ferramentas o backend pode usar: "auto" permite que ele escolha, "required" exige uma chamada de ferramenta e "none" impede chamadas de ferramenta. Você também pode selecionar uma função pelo nome. Defina delegation.responses.parallel_tool_calls como true para permitir consultas independentes em paralelo ou como false quando as chamadas precisarem ser executadas sequencialmente. Seu aplicativo continua responsável por executar suas funções personalizadas e garantir o cumprimento das dependências e aprovações. Essas configurações não obrigam o modelo ao vivo a delegar.

A configuração do Responses exige um model de backend na criação. Ela aceita definições de function e entradas de web_search em tools. Também disponibiliza max_output_tokens (no mínimo 16, quando definido), service_tier e as configurações de reasoning e text compatíveis com o modelo de backend selecionado. Consulte Reduza a latência do backend para conhecer as configurações que você pode ajustar.

Se o modo Fast estiver disponível para seu modelo e projeto, considere usá-lo em chamadas sensíveis à latência. Para o GPT-Live, selecione-o com delegation.responses.service_tier: "priority".

À medida que a conversa muda, envie session.update com alterações em session.delegation.responses para atualizar o modelo de backend, as instruções, as ferramentas disponíveis, tool_choice ou outras configurações compatíveis sem iniciar uma nova sessão Live. As configurações omitidas mantêm seus valores. Definir delegation como null seleciona o modo cliente e não permite redefinir uma sessão Responses em execução; a tentativa de alternar entre modos falha com immutable_field_update.

Essas configurações usam conceitos conhecidos do Responses, mas o Live oferece suporte a um subconjunto da API Responses independente. O Live fornece o contexto da conversa e inicia o trabalho delegado. Configure o backend pela sessão; o comando response.create do Live usa essa configuração e não aceita um corpo de requisição da API Responses independente.

Direcione a conversa ao vivo pelo seu aplicativo

A delegação via Responses gerencia o fluxo de trabalho do backend, mas seu aplicativo ainda pode enviar contexto diretamente ao modelo GPT-Live. Se você monitorar a chamada por um WebSocket auxiliar ou pela conexão principal de eventos, poderá usar session.instructions.append, session.thinking.append ou session.commentary.append com delegation_id: null. Por exemplo, uma proteção baseada na transcrição pode acrescentar uma instrução para redirecionar a conversa. Isso direciona o modelo ao vivo; não altera o prompt do backend do Responses nem cancela o trabalho já em andamento.

Processe a delegação via Responses

Para trabalho executado pelo Responses, session.delegation.created contém target: "responses" e um response_id. Os eventos subsequentes do Responses chegam dentro de um envelope response.event:

1234567891011121314{
  "type": "response.event",
  "event_id": "event_response_1",
  "delegation_id": "item_9tA2cB6n2V8c4X1z7Q5r9",
  "event": {
    "type": "response.output_text.delta",
    "sequence_number": 4,
    "item_id": "msg_123",
    "output_index": 0,
    "content_index": 0,
    "delta": "The forecast is",
    "logprobs": []
  }
}

Encaminhe os eventos com base em envelope.event.type e preserve o delegation_id externo. Não trate todo valor response.* de nível superior como um evento do Responses sem envelope. Aceite eventos aninhados adicionais do ciclo de vida do Responses.

A fala ao vivo e o trabalho delegado continuam de forma independente. Uma resposta concluída pelo backend não significa, por si só, que o usuário ouviu a resposta. Use a transcrição de saída e o áudio do Live para a parte falada da interação.

Conclua uma chamada de função executável pelo cliente

Leia as chamadas de função concluídas nos eventos aninhados response.output_item.done. O item de função finalizado contém call_id, name e arguments; um evento de conclusão dos argumentos, por si só, não é suficiente para identificar a chamada.

Acompanhe o ID da resposta do evento aninhado response.created junto com o delegation_id externo e colete as chamadas de função dessa resposta em response.output_item.done. Os snapshots encaminhados do ciclo de vida contêm deliberadamente response.output: [], inclusive em response.completed; o array tools está vazio, instructions é null e input é omitido. Uma lista de saída final vazia não significa que não há chamadas de função pendentes. Use as chamadas coletadas para determinar quais resultados devem ser enviados antes de continuar.

Depois de executar a operação autorizada, acrescente o resultado como um item do Responses:

1
2
3
4
5
6
7
8
9
10
11export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "tool_result_1",
    item: {
      type: "function_call_output",
      call_id: "call_123",
      output: '{"status":"confirmed","order_id":"order_123"}',
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "function_call_output",
        "call_id": "call_123",
        "output": '{"status":"confirmed","order_id":"order_123"}',
    }
    await connection.response.item.create(
        event_id="tool_result_1",
        item=item,
    )

Em seguida, continue explicitamente a resposta:

1
2
3
4
5
6export function sendUpdate(connection) {
  connection.send({
    type: "response.create",
    event_id: "continue_1",
  });
}

1
2
3
4
5
6
7
8
9
10from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.response.create(
        event_id="continue_1",
    )

Envie todos os resultados necessários das chamadas de ferramenta pendentes antes de continuar. Acrescentar o resultado de uma função não dá continuidade automática à resposta. response.item.create não tem uma confirmação de sucesso separada; continue processando os erros e os eventos aninhados subsequentes do ciclo de vida da resposta.

response.create é um comando do Live para criar ou continuar trabalho delegado ao Responses, usando o backend configurado na sessão. Não anexe a esse evento um corpo de requisição de criação da API Responses, uma substituição do modelo de backend ou delegation_id. Ambos os comandos exigem delegação via Responses.

Configure a delegação ao cliente

Defina delegation ao criar sua sessão Live:

1
2
3
4
5
6export const session = {
  model: "gpt-live-1",
  delegation: {
    type: "client",
  },
};

1
2
3from openai.types.live.session_config_param import SessionConfigParam

session: SessionConfigParam = {"model": "gpt-live-1", "delegation": {"type": "client"}}

Isso seleciona a delegação ao cliente para a sessão. Configure o backend separadamente: seu aplicativo escolhe o modelo ou serviço, as instruções, as ferramentas e como encaminhar o trabalho. Se você usar a API Responses nesse backend, defina o modelo e as ferramentas nas suas próprias requisições ao Responses. A sessão Live não configura nem executa essas ferramentas do backend.

Quando o GPT-Live solicita ajuda, seu aplicativo monta a requisição ao backend com base no contexto da conversa e do aplicativo, executa o trabalho e decide quais resultados retornar. Garanta o cumprimento das permissões e das confirmações obrigatórias antes de executar suas ferramentas. Mantenha o histórico completo da conversa no seu aplicativo para fornecer o contexto relevante a cada requisição ao backend.

Mantenha o contexto da conversa no seu aplicativo

Na delegação ao cliente, colete as transcrições e mantenha o estado atual da tarefa por conta própria.

Monitore session.input_transcript.delta e session.output_transcript.delta. Esses eventos contêm o texto da transcrição em delta, junto com os registros de tempo start_ms e end_ms. Mantenha histórico suficiente para entender respostas curtas como “sim”, correções como “quinta-feira, não sexta-feira” e detalhes fornecidos anteriormente. Um fragmento de transcrição não equivale a um turno completo do usuário, e as transcrições podem conter erros.

O evento separado session.delegation.created contém um registro de tempo offset_ms e metadados de delegação, incluindo delegation.id e delegation.target. Ele não contém a fala do usuário nem o texto da tarefa. Use os eventos de transcrição e o estado do aplicativo para entender o que o usuário quer. Salve delegation.id para associar as atualizações a essa solicitação.

Mantenha registros longos e a saída completa das ferramentas no backend. Se você criar uma sessão substituta, restaure o contexto relevante a partir do seu aplicativo e verifique quais ações já foram executadas antes de repetir qualquer trabalho.

Receba uma delegação ao cliente

session.delegation.created identifica uma delegação:

12345678910{
  "type": "session.delegation.created",
  "event_id": "event_delegation",
  "offset_ms": 1000,
  "delegation": {
    "id": "item_9tA2bF3h7K9m2P5q8R1s4",
    "type": "delegation",
    "target": "client"
  }
}

Leia event.delegation.id. O objeto de delegação contém metadados, não o texto da tarefa. Mantenha a transcrição e o contexto da aplicação necessários para seu próprio processador de trabalho delegado. Os IDs atuais têm o prefixo item_, como ilustrado aqui; trate o ID completo como opaco e retorne-o sem alterações, em vez de construir um ID ou analisar sua estrutura.

Retorne um resultado usando esse ID:

1
2
3
4
5
6
7
8export function sendUpdate(connection) {
  connection.send({
    type: "session.commentary.append",
    event_id: "result_123",
    delegation_id: "item_9tA2bF3h7K9m2P5q8R1s4",
    content: "The order shipped today and should arrive tomorrow.",
  });
}

1
2
3
4
5
6
7
8
9
10
11
12from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    await connection.session.commentary.append(
        event_id="result_123",
        delegation_id="item_9tA2bF3h7K9m2P5q8R1s4",
        content="The order shipped today and should arrive tomorrow.",
    )

Use session.thinking.append para adicionar informações ao raciocínio interno do modelo sem que sejam faladas em voz alta no momento da adição. Use session.commentary.append para um resultado que o modelo deve falar em voz alta; o modelo é treinado para parafrasear o texto adicionado. Todas as adições contêm uma string simples e exigem delegation_id, inclusive quando seu valor é null. Um ID não nulo deve identificar uma delegação ao cliente conhecida.

Adições sucessivas de resultados podem dar continuidade à mesma delegação ao cliente. A confirmação da adição chega após o momento estimado de injeção do contexto; ela não comprova que o modelo consumiu ou falou o resultado, nem que uma ação externa foi concluída com sucesso.

Com a delegação ao Responses, coloque uma mensagem do usuário na fila do backend:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16export function sendUpdate(connection) {
  connection.send({
    type: "response.item.create",
    event_id: "typed_order_number",
    item: {
      type: "message",
      role: "user",
      content: [
        {
          type: "input_text",
          text: "My order number is A0042.",
        },
      ],
    },
  });
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17from openai.resources.live.live import AsyncLiveConnection
from openai.resources.live.sideband import AsyncSidebandConnection
from openai.types.responses.response_input_item_param import ResponseInputItemParam


async def send_update(
    connection: AsyncLiveConnection | AsyncSidebandConnection,
) -> None:
    item: ResponseInputItemParam = {
        "type": "message",
        "role": "user",
        "content": [{"type": "input_text", "text": "My order number is A0042."}],
    }
    await connection.response.item.create(
        event_id="typed_order_number",
        item=item,
    )

Envie response.create quando estiver pronto para executar ou continuar o processamento no backend. Se o backend estiver aguardando resultados de funções, retorne primeiro todos os resultados necessários. Colocar texto na fila não cancela, por si só, o trabalho já em execução.

Com a delegação pelo cliente, envie o valor digitado diretamente ao backend responsável pela conversa. Se esse valor corrigir uma tarefa em execução, atualize essa tarefa em vez de iniciar o mesmo trabalho novamente. Você pode enviar uma cópia de um breve resumo factual para a sessão ao vivo com session.thinking.append ou usar session.commentary.append para um resultado que o usuário deva ouvir.

Com a delegação via Responses, configure um modelo de backend com recursos de visão. Coloque na fila um item de entrada de imagem compatível com Responses usando response.item.create e, em seguida, envie response.create para executar ou retomar o trabalho no backend. Retorne todos os resultados de funções pendentes necessários antes de continuar. Consulte Como lidar com a delegação via Responses.

Com a delegação pelo cliente, envie a entrada visual ao backend que processa as solicitações delegadas, junto com a conversa e o estado do aplicativo relevantes. Retorne conclusões concisas usando o fluxo de resultados do cliente.

Delegação via Responses

O Live gerencia conexões WebSocket persistentes com Responses, prepara antecipadamente a conexão e a configuração já conhecida da solicitação e reutiliza o estado de respostas anteriores quando disponível. Você não precisa implementar essas etapas para o backend hospedado. A reutilização depende da conexão ativa e de um estado compatível; ela não garante um acerto de cache nem uma latência específica.

Ajuste o backend por meio de delegation.responses:

• model: escolha o modelo responsável pelo raciocínio e pela seleção de ferramentas independentemente do modelo de voz.
• reasoning.effort: equilibre o tempo de raciocínio e a qualidade da tarefa usando valores compatíveis com esse modelo.
• service_tier: use auto, default, flex ou priority, conforme o suporte do modelo e o acesso do projeto. auto segue a configuração do projeto. Avalie o desempenho e o custo do nível escolhido.

Atualize as configurações compatíveis durante a sessão com session.update. Suas ferramentas personalizadas continuam sendo executadas no seu aplicativo, portanto chamadas lentas a serviços, filas e armazenamento de resultados de ferramentas em buffer podem atrasar a resposta mesmo quando o Live gerencia a conexão com Responses. Retorne prontamente cada resultado de ferramenta necessário e continue a resposta do backend.

Delegação pelo cliente

Seu aplicativo é responsável por todo o fluxo, desde o recebimento da delegação até o retorno de um resultado. Prepare esse fluxo enquanto a sessão de voz estiver em andamento:

• Reutilize as conexões do backend. Mantenha o cliente da API e seu pool de conexões ativos entre as delegações. Para chamadas repetidas a Responses, considere uma conexão WebSocket de Responses persistente.
• Prepare a configuração já conhecida. Inicialize instruções, ferramentas e conexões antes que a primeira solicitação precise delas. O modo WebSocket de Responses também permite preparar antecipadamente o estado já conhecido da solicitação antes da geração; siga as orientações de configuração.
• Transmita resultados úteis de forma incremental. Retorne trechos coerentes e verificados com session.commentary.append. Use session.thinking.append para informar o progresso sem anunciá-lo em voz alta. Preserve o ID da delegação pelo cliente e o limite de 500 tokens por adição. Mantenha o raciocínio privado no backend e confirme as ações antes de anunciar o sucesso.
• Mantenha estáveis as entradas reutilizáveis. Preserve as instruções, as definições e a ordem das ferramentas e os prefixos do histórico que não mudaram. Acrescente novas informações após o conteúdo reutilizável quando seu backend oferecer suporte a cache e continuação.
• Evite o armazenamento desnecessário em buffer. Encaminhe um resultado útil assim que estiver pronto. Armazene em buffer apenas o suficiente para classificar a saída e formar um trecho coerente. Prefira metadados estruturados de fase; se usar prefixos de texto para distinguir progresso de resultados, espere o prefixo completo antes de encaminhar o texto.

Meça o tempo até a primeira resposta falada útil ao comparar esse fluxo com a delegação via Responses.