Se você quer construir um único app de IA com GPT, Claude, Gemini, DeepSeek e Grok, use uma API unificada para o caminho comum de requisição e mantenha a política de roteamento dentro do seu aplicativo. CometAPI fornece um base URL compatível com OpenAI e um catálogo compartilhado de modelos, então um serviço Python pode chamar diferentes IDs de modelo por meio de um único cliente. Seu código ainda decide qual modelo roda, quais ferramentas são permitidas e quando um fallback é seguro.
Este tutorial constrói um agente Grok 4.7 que pode solicitar duas ferramentas de negócios somente leitura, rejeita ferramentas desconhecidas e argumentos malformados antes da execução, e muda para outro modelo testado por contrato apenas após falhas transitórias selecionadas. O objetivo não é um sistema autônomo mágico. É um loop pequeno e inspecionável que pode ser testado e operado em produção.
O Que Você Está Construindo
O agente tem cinco partes explícitas:
- Um cliente CometAPI. O SDK Python da OpenAI usa o base URL da CometAPI mostrado na configuração abaixo.
- Grok 4.7 como modelo primário. O ID de modelo atual da CometAPI é
grok-4.7. - Um registro de ferramentas. O modelo pode propor uma chamada de função, mas apenas o código da aplicação pode executar uma função em uma lista de permissões.
- Um loop de agente limitado. O loop para após um número fixo de turnos do modelo em vez de rodar indefinidamente.
- Uma política de fallback ordenada. IDs de modelos compatíveis GPT, Claude, Gemini ou DeepSeek são tentados apenas após uma falha de modelo/API classificável como transitória.
Grok 4.7 suporta chamadas de função, e a CometAPI atualmente documenta as rotas /v1/chat/completions e /v1/responses para o modelo. Este tutorial usa Chat Completions porque seus tools compatíveis com OpenAI, chamadas de ferramenta do assistente e mensagens de resultado tool correspondentes mapeiam diretamente para um loop Python compacto e inspecionável. Compatibilidade de transporte não prova paridade de recursos em todos os modelos, então todo fallback configurado deve passar pelos mesmos testes de contrato antes de entrar em produção.
Estado de Raciocínio em Agentes Grok 4.7 de Múltiplos Turnos
Grok 4.7 aceita esforços de raciocínio low, medium, high ou xhigh, com high como padrão. Na Responses API da xAI, toda resposta do Grok 4.7 inclui reasoning.encrypted_content; um loop de múltiplos turnos gerenciado pelo cliente deve passar os itens de raciocínio retornados de volta inalterados na próxima requisição. Loops longos também podem usar compactação de contexto: preserve o item de compactação retornado como estado opaco e acrescente novos turnos depois dele. Como esses são campos de resposta com estado e específicos do provedor, verifique que a rota escolhida da CometAPI os retorna de ponta a ponta antes de torná-los uma dependência de produção.
Arquitetura do Agente: O Modelo Propõe, Seu App Decide
Um fluxo seguro de chamada de ferramentas é simples:
User request → model response → validate tool call → execute allowlisted tool → append tool result → model response
O modelo nunca recebe credenciais de banco de dados e nunca executa Python diretamente. Ele produz uma requisição estruturada como “chamar get_order_status com este ID de pedido”. Sua aplicação verifica o nome da ferramenta, analisa os argumentos, aplica autorização e regras de negócio, executa a função e retorna um resultado serializado.
Essa separação importa mais do que a escolha do modelo. Um modelo de fallback deve herdar a mesma fronteira de ferramentas — não uma mais ampla — e resultados de ferramentas devem ser tratados como dados não confiáveis quando contêm conteúdo externo.
Como Construir um Agente de IA Grok 4.7 com Python
Passo 1: Configurar o SDK Python da OpenAI para a CometAPI
Instale o SDK da OpenAI:
pip install openai
Defina a configuração via variáveis de ambiente:
export COMETAPI_KEY="your-cometapi-key"
export PRIMARY_MODEL="grok-4.7"
export FALLBACK_MODEL_1="your-compatible-gpt-model-id"
export FALLBACK_MODEL_2="your-compatible-claude-model-id"
export FALLBACK_MODEL_3="your-compatible-gemini-model-id"
export FALLBACK_MODEL_4="your-compatible-deepseek-model-id"
Este tutorial usa Chat Completions porque suas chamadas de ferramenta explícitas do assistente e mensagens de resultado de ferramenta correspondentes tornam o fluxo de controle fácil de inspecionar em um exemplo Python compacto. Para loops com estado mais longos, avalie a Responses API conforme descrito acima. Além disso, não copie IDs de modelo antigos de um post de blog para produção: busque o catálogo público GET /api/models da CometAPI durante o deploy ou na inicialização e confirme capacidades e preços no diretório de modelos.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
timeout=30.0,
)
O timeout explícito e o retry desativado no SDK são deliberados. A aplicação vai classificar falhas e decidir se repete a requisição ou move para o próximo modelo. Repetições ocultas tornam latência, efeitos colaterais duplicados e comportamento de fallback mais difíceis de entender.
Passo 2: Defina Primeiro Ferramentas Estreitas e Somente Leitura
Comece com ferramentas que leem dados em vez de alterá-los. As definições abaixo permitem que o agente verifique um pedido e consulte o inventário. A implementação retorna dados de demonstração; substitua por chamadas autenticadas para seus próprios serviços.
import json
TOOLS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Ler o status atual de um pedido.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
},
{
"type": "function",
"function": {
"name": "check_inventory",
"description": "Ler o inventário disponível para um SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {"type": "string"}
},
"required": ["sku"],
"additionalProperties": False,
},
},
},
]
def get_order_status(order_id: str) -> dict:
# Substitua esta demo por uma chamada autenticada de serviço somente leitura.
return {"order_id": order_id, "status": "in_transit"}
def check_inventory(sku: str) -> dict:
# Substitua esta demo por uma chamada autenticada de serviço somente leitura.
return {"sku": sku, "available_units": 12}
TOOL_REGISTRY = {
"get_order_status": get_order_status,
"check_inventory": check_inventory,
}
Um esquema JSON melhora o formato da requisição, mas não é autorização. Valide comprimentos e formatos de argumentos, confirme que o usuário atual pode acessar o pedido ou SKU solicitado e limite o tamanho de cada resultado de ferramenta antes de retorná-lo ao modelo.
Passo 3: Adicione uma Política de Fallback Multimodelo Estreita
Fallback deve recuperar de falha temporária de rota, não esconder requisições com problemas. O guia oficial de fallback da CometAPI recomenda mover para a próxima rota configurada em erros de conexão, timeouts, HTTP 408, HTTP 429 e respostas 5xx temporárias. Credenciais inválidas, parâmetros não suportados e requisições inválidas devem falhar imediatamente.
from openai import APIConnectionError, APIStatusError, APITimeoutError
def configured_models() -> list[str]:
names = [
os.getenv("PRIMARY_MODEL", "grok-4.7"),
os.getenv("FALLBACK_MODEL_1"),
os.getenv("FALLBACK_MODEL_2"),
os.getenv("FALLBACK_MODEL_3"),
os.getenv("FALLBACK_MODEL_4"),
]
return [name for name in names if name]
def is_retryable(error: Exception) -> bool:
if isinstance(error, (APIConnectionError, APITimeoutError)):
return True
if isinstance(error, APIStatusError):
return error.status_code in {408, 429} or error.status_code >= 500
return False
def complete_with_fallback(messages: list[dict], tools: list[dict]):
models = configured_models()
last_error = None
for index, model in enumerate(models):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tools,
tool_choice="auto",
)
return response, model
except Exception as error:
last_error = error
final_route = index == len(models) - 1
if final_route or not is_retryable(error):
raise
raise RuntimeError("Nenhum modelo configurado concluiu a requisição") from last_error
A lista de modelos é configuração, não um ranking de qualidade. Escolha fallbacks que suportem os mesmos papéis de mensagem, esquema de ferramentas, modalidade de entrada, requisito de contexto e comportamento de resposta necessários por este agente. Registre a rota selecionada e a falha que causou cada transição.
Passo 4: Rode o Loop Limitado do Agente Grok 4.7
O loop abaixo envia a conversa, executa quaisquer chamadas de ferramentas na lista de permissões, acrescenta resultados com o tool_call_id correspondente e pede ao modelo selecionado para finalizar a resposta.
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
if name not in TOOL_REGISTRY:
return json.dumps({"error": f"Ferramenta não permitida: {name}"})
try:
arguments = json.loads(tool_call.function.arguments)
result = TOOL_REGISTRY[name](**arguments)
return json.dumps(result)
except (json.JSONDecodeError, TypeError, ValueError) as error:
return json.dumps({"error": f"Argumentos de ferramenta inválidos: {error}"})
def run_agent(user_text: str, max_turns: int = 4) -> dict:
messages = [
{
"role": "system",
"content": (
"Você é um agente de suporte. Use ferramentas apenas quando necessário. "
"Nunca invente dados de pedido ou inventário."
),
},
{"role": "user", "content": user_text},
]
route_log = []
for turn in range(max_turns):
response, model = complete_with_fallback(messages, TOOLS)
route_log.append({"turn": turn + 1, "model": model})
assistant = response.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
if not assistant.tool_calls:
return {
"answer": assistant.content,
"routes": route_log,
"usage": response.usage.model_dump() if response.usage else None,
}
for tool_call in assistant.tool_calls:
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": execute_tool_call(tool_call),
}
)
raise RuntimeError("Agente interrompido após alcançar max_turns")
result = run_agent("Onde está o pedido A-104 e o SKU BLUE-42 está em estoque?")
print(result["answer"])
print(result["routes"])
O código suporta várias chamadas de ferramenta em uma única resposta do modelo porque acrescenta um resultado para cada chamada retornada. Se uma ferramenta alterar estado — enviar um e-mail, fazer um pedido ou emitir um reembolso — adicione uma chave de idempotência e uma etapa de confirmação humana. Nunca reinicie cegamente todo o turno do agente após um timeout se um efeito colateral puder já ter acontecido.
Como GPT, Claude, Gemini e DeepSeek Encaixam no Mesmo App
A CometAPI pode reduzir duplicação na camada de conexão: uma conta, um base URL compatível com OpenAI para o caminho comum, e um ID de modelo selecionado pelo código da aplicação. Isso torna GPT, Claude, Gemini, DeepSeek e Grok candidatos atrás de uma única interface interna.
Isso não torna os modelos intercambiáveis. Antes de adicionar um fallback, verifique:
- se o ID de modelo atual é retornado pelo catálogo da CometAPI;
- se a rota suporta o esquema de ferramentas e papéis de mensagem requeridos;
- se os argumentos de chamada de ferramenta e o comportamento de múltiplas chamadas correspondem ao contrato do agente;
- se a janela de contexto e as modalidades de entrada se ajustam à requisição;
- se a resposta pode ser validada antes de chegar ao usuário;
- se latência e custo permanecem dentro do orçamento do produto.
Recursos nativos de provedores podem exigir um endpoint nativo ou um adaptador separado. Mantenha essas exceções explícitas em vez de forçar toda capacidade pelo caminho comum.
Fallback Multimodelo do Grok 4.7 Não é o Mesmo que Multiagente
Uma cadeia de fallback multimodelo escolhe outro modelo quando uma rota falha. Um sistema multiagente atribui responsabilidades diferentes a agentes separados — por exemplo, um planejador, um pesquisador e um revisor. Os dois padrões resolvem problemas diferentes.
Se você estender este agente Grok 4.7 para um fluxo de trabalho multiagente, dê a cada trabalhador um papel estreito, lista de permissões de ferramentas separada, orçamento limitado e repasse estruturado. Não permita que todo agente chame toda ferramenta nem encaminhe um transcript ilimitado. Comece com um único agente até que dados de avaliação provem que a separação de papéis melhora o resultado.
Trilhos de Proteção de Produção para um Agente Grok 4.7
Validar Antes da Execução de Ferramentas
Verifique nomes de ferramentas, esquemas de argumentos, propriedade do tenant, permissões do usuário e limites de taxa no código da aplicação. Trate descrições de ferramentas como orientação para o modelo, não como controle de segurança.
Separar Ferramentas de Leitura de Ferramentas de Escrita
Ferramentas somente leitura frequentemente podem rodar automaticamente após autorização. Ferramentas de escrita devem exigir verificações mais fortes, idempotência e confirmação para ações consequenciais.
Limitar Todo Loop
Defina máximos de turnos do modelo, chamadas de ferramentas, tempo de relógio, tamanho de prompt e orçamento de tokens. Retorne um erro controlado ou caminho de escalonamento quando um limite for atingido.
Registrar a Trilha de Decisão
Registre a tarefa solicitada, versão da política, ID de modelo selecionado, motivo do fallback, nome da ferramenta, latência da ferramenta, resultado da validação, uso de tokens e status final. Não registre segredos nem conteúdo desnecessário de clientes.
Usar Testes de Contrato, Não Suposições
Execute os mesmos fixtures contra todo modelo configurado. Um conjunto mínimo útil cobre uma resposta normal, uma chamada de ferramenta, múltiplas chamadas de ferramenta, argumentos malformados, uma ferramenta desconhecida, timeout de uma ferramenta, um 429 do modelo primário e uma chave de API inválida que não deve acionar fallback.
Checklist de Deploy
- Buscar IDs de modelo atuais e verificar a rota Grok 4.7 antes do deploy.
- Manter a chave da CometAPI em um gerenciador de segredos, nunca no código-fonte ou em prompts.
- Começar com ferramentas somente leitura e esquemas JSON explícitos.
- Aplicar autenticação e autorização de tenant antes de cada chamada de ferramenta.
- Permitir fallback apenas para erros transitórios classificados.
- Testar todo fallback contra o mesmo contrato de chamadas de ferramentas.
- Adicionar idempotência e confirmação antes de habilitar ferramentas de escrita.
- Definir limites de loop, latência, contexto e custo.
- Medir sucesso da tarefa, não apenas disponibilidade da API.
Por Que Construir Este Agente via CometAPI?
A CometAPI é útil aqui porque a integração comum permanece pequena. O SDK Python da OpenAI aponta para um único base URL, Grok 4.7 é selecionado por ID de modelo, e modelos compatíveis de outros provedores podem ser colocados atrás da mesma política de rota de propriedade da aplicação.
Isso dá à equipe espaço para avaliar GPT, Claude, Gemini e DeepSeek sem espalhar código de conexão específico do provedor pelo produto. Também preserva uma fronteira importante: a CometAPI fornece acesso, enquanto sua aplicação é responsável por verificações de capacidade, execução de ferramentas, política de fallback, avaliação e comportamento voltado ao usuário.
Revise a página do modelo Grok 4.7, configure o cliente a partir do guia de início rápido da CometAPI e busque IDs de modelo atuais antes de escolher fallbacks de produção.
FAQ
Qual API devo usar para um app com GPT, Claude, Gemini e DeepSeek?
Para o caminho comum de chat e chamadas de ferramenta, uma API unificada compatível com OpenAI como a CometAPI pode reduzir o trabalho de integração. Mantenha a seleção de modelo e a política de fallback na sua aplicação e use adaptadores nativos do provedor quando um recurso necessário não se encaixar no contrato compartilhado.
Grok 4.7 pode chamar funções Python diretamente?
Grok 4.7 pode retornar requisições estruturadas de chamada de função. Sua aplicação Python analisa a requisição, valida, executa uma função na lista de permissões e envia o resultado de volta ao modelo. O próprio modelo não executa Python local.
Todo erro deve acionar um modelo diferente?
Não. Use fallback para falhas de conexão selecionadas, timeouts, 408, 429 e respostas 5xx temporárias. Requisições inválidas, falhas de autenticação e parâmetros não suportados devem ser corrigidos em vez de enviados para outro modelo.
Posso usar um único esquema de ferramenta com todos os modelos?
Somente após testes. Um transporte compartilhado não garante comportamento idêntico de ferramentas, qualidade de argumentos, comportamento de chamadas paralelas ou enforcement de esquema. Adicione um modelo à cadeia apenas após ele passar nos testes de contrato do agente.
Um sistema de fallback multimodelo é um sistema multiagente?
Não. Fallback muda o modelo usado para uma requisição após uma falha de rota. Arquitetura multiagente atribui tarefas diferentes a agentes separados. Construa-os como camadas distintas com testes e controles separados.