Ir para o conteúdo principal
Português— Escolher um idioma
Menu

API de Respostas e function_call_output

Aula 10 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. A API de Respostas: o novo endpoint
  2. Diferenças em relação às Completions de Chat
  3. Utilizar a API de Respostas com o SDK da OpenAI
  4. Gerir a resposta
  5. O campo previous_response_id
  6. Armazenamento de mensagens no servidor
  7. Quando utilizar a API de Respostas?
  8. Pontos-chave

A API de Respostas: o novo endpoint

A API de Respostas é o novo endpoint principal da xAI, distinto do endpoint de Completions de Chat compatível com a OpenAI. Introduz um formato diferente para chamadas de funções, utilizando o tipo function_call_output para devolver resultados de ferramentas.

Diferenças em relação às Completions de Chat

O endpoint de Completions de Chat (compatível com a OpenAI) utiliza mensagens com a função tool para devolver resultados. A API de Respostas usa um formato diferente, estruturado em torno de tipos de eventos.

Completions de Chat (formato legado)

# Devolver o resultado através de uma mensagem com a função "tool"
messages.append({
    "role": "tool",
    "tool_call_id": "call_abc123",
    "content": {temp: 22, city: Paris}
})

API de Respostas (novo formato)

# Devolver o resultado através de um objeto function_call_output
{
    "type": "function_call_output",
    "call_id": "call_abc123",
    "output": {temp: 22, city: Paris}
}

Principais diferenças:

  • type: "function_call_output" substitui role: "tool"
  • call_id substitui tool_call_id
  • output substitui content

Utilizar a API de Respostas com o SDK da OpenAI

Pode utilizar o SDK da OpenAI para chamar a API de Respostas da xAI:

from openai import OpenAI

client = OpenAI(
    api_key="votre-cle-api",
    base_url="https://api.x.ai/v1"
)

# Criar uma resposta com ferramentas
response = client.responses.create(
    model="grok-4.5",
    input="What's the weather like in Paris?",
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get the weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"}
            },
            "required": ["city"]
        }
    }]
)

Note que a API de Respostas utiliza input em vez de messages, e a estrutura das ferramentas é ligeiramente diferente (sem objeto function aninhado).

Gerir a resposta

A resposta da API de Respostas contém um array output com eventos:

for item in response.output:
    if item.type == "function_call":
        print(f"Function: {item.name}")
        print(f"Arguments: {item.arguments}")
        print(f"Call ID: {item.call_id}")

        # Executar a função
        result = get_weather(city="Paris")

        # Continuar a conversa com o resultado
        follow_up = client.responses.create(
            model="grok-4.5",
            input=[
                {"type": "function_call_output",
                 "call_id": item.call_id,
                 "output": json.dumps(result)}
            ],
            tools=tools,
            previous_response_id=response.id
        )

O campo previous_response_id

A API de Respostas introduz um mecanismo de encadeamento de conversas através do previous_response_id. Em vez de reenviar todo o histórico de mensagens, basta referenciar a resposta anterior:

# Primeiro pedido
response1 = client.responses.create(
    model="grok-4.5",
    input="Look up the weather in Paris"
)

# Segundo pedido (encadeado)
response2 = client.responses.create(
    model="grok-4.5",
    input=[{
        "type": "function_call_output",
        "call_id": response1.output[0].call_id,
        "output": {temp: 22}
    }],
    previous_response_id=response1.id
)

Isto simplifica a gestão do contexto e reduz o tamanho dos pedidos.

Armazenamento de mensagens no servidor

Com store_messages=True, a xAI armazena as mensagens nos seus servidores:

response = client.responses.create(
    model="grok-4.5",
    input="User question",
    tools=tools,
    store_messages=True
)

Combinado com previous_response_id, isto permite manter conversas longas sem reenviar o histórico completo em cada pedido.

Quando utilizar a API de Respostas?

Para um novo projeto construído especificamente para a xAI, a API de Respostas é a escolha padrão, por várias razões cumulativas. As inovações chegam aqui primeiro — as novas funcionalidades são adicionadas à API de Respostas antes de qualquer outro local, por vezes em exclusivo. Certas ferramentas de servidor integradas estão apenas disponíveis através deste canal. E para conversas longas, o encadeamento via previous_response_id é estruturalmente mais eficiente do que reenviar o histórico completo a cada turno: menos tokens transferidos, menos código de gestão de estado da sua parte.

As Completions de Chat mantêm dois casos de uso fortes: código existente escrito para a API da OpenAI, que funciona tal como está ao alterar o URL base, e projetos multi-fornecedor onde a portabilidade tem precedência — nestas situações, a compatibilidade supera as funcionalidades exclusivas.

Pontos-chave

  • A API de Respostas utiliza function_call_output em vez da função tool
  • Os campos mudam: call_id em vez de tool_call_id, output em vez de content
  • previous_response_id permite encadear conversas sem reenviar o histórico
  • store_messages=True ativa o armazenamento no lado do servidor
  • A API de Respostas é o endpoint recomendado para novos projetos xAI
  • As Completions de Chat permanecem disponíveis para retrocompatibilidade com a OpenAI