Usar ferramentas integradas no servidor
Usar ferramentas integradas no servidor
Use busca na web e outras ferramentas integradas sem orquestração de ferramentas no cliente.
Manter o estado da conversa no servidor
Manter o estado da conversa no servidor
O estado no servidor é mantido entre os turnos por meio de
previous_response_id, sem reenviar todo o histórico de mensagens.Enviar entrada multimodal
Enviar entrada multimodal
Passe itens
input_image e input_file em uma única solicitação.Criar fluxos de trabalho no estilo de agentes
Criar fluxos de trabalho no estilo de agentes
Combine function calling, raciocínio e continuação de ferramentas em loops no estilo de agentes.
A Responses API é o endpoint
/responses no estilo da OpenAI no AI Gateway, exposto em POST /v3/router/responses. Ela implementa a especificação OpenResponses: uma solicitação contém um model e um input, e a resposta retorna itens de output estruturados junto com o uso de tokens e o custo. O endpoint oferece ferramentas integradas, como busca na web, estado de conversa no servidor, streaming e entrada multimodal. Escolha-o quando esses recursos forem importantes; para um fluxo clássico baseado em mensagens, use Chat Completions.
Invoque um agente configurado definindo
model como agent/<key>; as ferramentas, knowledge bases e memória do agente são aplicadas automaticamente. Consulte Executar agentes.Uma Model Fusion responde a uma solicitação com um painel de modelos e retorna uma única resposta avaliada: defina
model como o nome da fusion. Consulte Model Fusion.Responses vs. Chat Completions
Os dois endpoints compartilham a mesma base URL (https://router.toqan.ai/eu/v3/router), a mesma autenticação e os mesmos recursos do AI Gateway: fallbacks, retries, cache, guardrails e budgets. A tabela abaixo lista as diferenças.
O function calling funciona nos dois endpoints por meio do array
tools; consulte Tool Calling.
Início rápido
Use o SDK da OpenAI com a base URL do AI Gateway e chameclient.responses.create.
Estado
As respostas são persistidas no servidor por padrão (store tem padrão true) e podem ser recuperadas pelo ID (GET /v3/router/responses/{response_id}; consulte Retrieve Response). Continue uma conversa passando previous_response_id na próxima solicitação; o gateway usa a conversa armazenada em vez de exigir todo o histórico novamente. previous_response_id exige store: true na resposta original. As respostas armazenadas expiram conforme a janela de retenção do workspace; após a expiração, previous_response_id retorna 404 com o código previous_response_not_found, e recuperar a resposta pelo ID retorna 404 com o código not_found. Consulte Retenção de dados.
Defina
store: false para não persistir uma resposta. A resposta não poderá ser recuperada depois, e previous_response_id não funcionará nas solicitações seguintes.Streaming
Defina"stream": true no corpo da solicitação. O servidor responde com um stream de Server-Sent Events no formato da OpenAI Responses: o texto incremental chega como eventos response.output_text.delta, e o stream termina com um evento de conclusão que contém o uso final. Consulte Streaming para padrões de tratamento de eventos, retry e erros.
Telemetria
As respostas bem-sucedidas contêm os ids do OpenTelemetry do turno. O corpo da resposta inclui um objetotelemetry de nível superior com os ids de trace e de span da solicitação:
trace_id é o id hexadecimal de 32 caracteres do trace, e span_id é o id hexadecimal de 16 caracteres do span da resposta. Os mesmos valores são repetidos nos headers de resposta x-orq-trace-id e x-orq-trace-span-id, definidos por todos os endpoints do router.
O objeto
telemetry está presente apenas em chamadas bem-sucedidas. As chamadas com falha não o incluem no corpo da resposta: nesse caso, leia os ids dos headers de resposta x-orq-trace-id e x-orq-trace-span-id, que também são definidos em respostas de erro.response.completed, dentro de response.telemetry; o evento response.created não os contém. Leia-os do evento de conclusão ou dos headers da resposta.
Use os ids para correlacionar a chamada com o respectivo Trace e em qualquer lugar em que um span precise ser referenciado, como ao anotar um span ou registrar feedback.
Ferramentas integradas
As ferramentas integradas são executadas no servidor: passe-as no arraytools, e o gateway as executa durante a geração. A busca na web está disponível apenas pela Responses API, como os tipos de ferramenta web_search e web_search_preview. Consulte Busca na web na Responses API para campos da ferramenta, mapeamento por provedor e a opção include.
As ferramentas de função funcionam nos dois endpoints; consulte Tool Calling.
Entrada multimodal
Envie imagens e PDFs junto com texto no arrayinput usando itens input_image e input_file. Consulte Imagem, PDF e áudio: entradas e geração multimodais para formatos compatíveis e exemplos completos.
Recursos do AI Gateway
Todos os recursos do AI Gateway se aplicam à Responses API. A maioria é configurada por solicitação, por meio de campos do corpo da solicitação; os budgets são configurados no console e se aplicam por escopo.Veja também
- Create Response: referência completa de solicitação e resposta
- Retrieve Response: obtenha uma resposta armazenada pelo ID
- API compatível com a OpenAI: base URL e todos os endpoints compatíveis
- Executar agentes: invoque um agente configurado pela Responses API
- Raciocínio: esforço de
reasoningpara modelos da OpenAI pela Responses API - Memory stores: memória persistente entre solicitações com o campo
memory

