Compatibilidade com o SDK da OpenAI
Nesta página
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