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

Compatibilidade com o SDK da OpenAI

Aula 6 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Utilização do modo multi-agente através do SDK da OpenAI
  2. Configuração do cliente
  3. Controlo do número de agentes com reasoning.effort
  4. O mapeamento effort → agents
  5. Chat Completions não é suportado
  6. Streaming com o SDK da OpenAI
  7. Vantagens e limites desta abordagem
  8. Pontos-chave

Utilização do modo multi-agente através do SDK da OpenAI

Muitas equipas já construíram a sua camada de chamadas em torno do SDK da OpenAI, com os seus wrappers, testes e convenções de registo. Boas notícias: aceder ao modo multi-agente do Grok não o obriga a reescrever tudo. A xAI expõe uma API compatível com o formato Responses da OpenAI, pelo que pode manter o cliente da OpenAI e simplesmente apontá-lo para a API da xAI.

Configuração do cliente

Apenas duas definições são necessárias: o URL base da xAI e a sua chave de API da xAI.

from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

A partir daqui, utiliza a API Responses como habitualmente, especificando grok-4.20-multi-agent-0309 como modelo. O restante código da sua chamada permanece inalterado.

Controlo do número de agentes com reasoning.effort

É aqui que ocorre a tradução entre os dois mundos. Enquanto o SDK da xAI expõe um agent_count explícito, o SDK da OpenAI oferece apenas reasoning.effort — assim, não solicita um número de agentes, mas sim um nível de esforço que a xAI converte num número de agentes.

# 4 agentes (esforço baixo)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "What are the latest open source models from 2026?"}],
)
print(response.output_text)
# 16 agentes (esforço elevado)
response = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "high"},
    input=[{"role": "user", "content": "Compare the EU and US AI strategies in 2026"}],
)
print(response.output_text)

O mapeamento effort → agents

O campo aceita quatro valores, mas estes produzem apenas dois tamanhos de equipa: "low" e "medium" utilizam 4 agentes, enquanto "high" e "xhigh" utilizam 16.

Este detalhe merece atenção cuidadosa. Passar de low para medium, ou de high para xhigh, não altera o número de agentes: estes níveis intermédios podem influenciar outros aspetos do comportamento do modelo, mas dentro de cada par a equipa mantém-se igual. Imagine uma interface onde oferecesse ao utilizador quatro níveis de profundidade de pesquisa; ele perceberia apenas dois, e os seus dois botões extra apenas confundiriam a sua escolha.

Chat Completions não é suportado

Eis a restrição que faz a maioria dos programadores falhar na primeira tentativa: Chat Completions não é suportado para multi-agente. Deve utilizar a API Responses, ou seja, client.responses.create, e não client.chat.completions.create.

# NÃO FUNCIONA
response = client.chat.completions.create(
    model="grok-4.20-multi-agent-0309",
    messages=[{"role": "user", "content": "..."}],
)

Esta chamada devolve um erro. Se o seu código existente depender inteiramente do Chat Completions — como acontece em muitas bases de código existentes — a alteração não é apenas uma troca de nome do modelo: tem de migrar a chamada para um formato de entrada e saída diferente. Avalie esse esforço antes de prometer a integração.

Streaming com o SDK da OpenAI

O streaming continua disponível, novamente através da API Responses:

stream = client.responses.create(
    model="grok-4.20-multi-agent-0309",
    reasoning={"effort": "low"},
    input=[{"role": "user", "content": "Summarize this week's tech announcements"}],
    stream=True,
)

for event in stream:
    if hasattr(event, 'delta') and event.delta:
        print(event.delta, end="", flush=True)

Vale a pena manter o teste hasattr(event, 'delta') tal como está: o fluxo de eventos da API Responses contém mais do que texto, e ler cegamente event.delta em cada evento provocaria uma exceção.

Vantagens e limites desta abordagem

A principal vantagem desta rota é a poupança de tempo: não instala outro SDK, os seus programadores obtêm uma sintaxe familiar e a alternância entre modelos xAI e OpenAI na mesma base de código torna-se trivial. Para uma equipa que deseja avaliar o modo multi-agente sem se comprometer com um projeto completo, este é o caminho mais curto.

Os limites decorrem todos da mesma causa: está a passar por uma camada de compatibilidade, pelo que perde o que é específico da xAI. Não obtém agent_count (substituído por um controlo indireto através de reasoning.effort), verbose_streaming ou use_encrypted_content. Além disso, o mapeamento effort → agents provém de uma API beta e pode alterar-se: se o seu produto depender especificamente do número de agentes utilizados, o SDK nativo permanece a escolha prudente.

Pontos-chave

  • O SDK da OpenAI funciona com multi-agente através de base_url="https://api.x.ai/v1"
  • Controla o número de agentes através de reasoning.effort (low/medium = 4, high/xhigh = 16)
  • Chat Completions NÃO é suportado — utilize apenas a API Responses
  • Alguns parâmetros exclusivos do SDK da xAI (agent_count, verbose_streaming) não estão disponíveis