Se vuoi creare un’unica app di IA con GPT, Claude, Gemini, DeepSeek e Grok, usa un’API unificata per il percorso di richiesta comune e mantieni la politica di instradamento all’interno della tua applicazione. CometAPI fornisce un base URL compatibile con OpenAI e un catalogo di modelli condiviso, così un servizio Python può chiamare diversi ID di modello tramite un unico client. Il tuo codice decide comunque quale modello eseguire, quali strumenti sono consentiti e quando un fallback è sicuro.
Questo tutorial realizza un agente Grok 4.7 che può richiedere due strumenti aziendali di sola lettura, rifiuta strumenti sconosciuti e argomenti malformati prima dell’esecuzione e passa a un altro modello testato a contratto solo dopo selezionati errori transitori. L’obiettivo non è un sistema autonomo “magico”. È un piccolo loop ispezionabile che può essere testato e gestito in produzione.
Cosa stai costruendo
L’agente ha cinque componenti espliciti:
- Un client CometAPI. L’OpenAI Python SDK usa il base URL di CometAPI mostrato nella configurazione sottostante.
- Grok 4.7 come modello primario. L’attuale ID di modello CometAPI è
grok-4.7. - Un registro degli strumenti. Il modello può proporre una chiamata di funzione, ma solo il codice dell’applicazione può eseguire una funzione nell’elenco dei consentiti.
- Un ciclo dell’agente con limiti. Il loop si arresta dopo un numero fisso di turni del modello anziché continuare indefinitamente.
- Una politica di fallback ordinata. ID di modelli compatibili GPT, Claude, Gemini o DeepSeek vengono tentati solo dopo un errore di modello/API ripetibile.
Grok 4.7 supporta la function calling e CometAPI attualmente documenta entrambe le route /v1/chat/completions e /v1/responses per il modello. Questo tutorial usa Chat Completions perché i suoi tools compatibili con OpenAI, le chiamate a strumenti dell’assistente e i corrispondenti messaggi di risultato tool si mappano direttamente su un loop Python compatto e ispezionabile. La compatibilità di trasporto non dimostra la parità di funzionalità su ogni modello, quindi ogni fallback configurato deve superare gli stessi test di contratto prima di entrare in produzione.
Stato di ragionamento negli agenti Grok 4.7 multi-turno
Grok 4.7 accetta uno sforzo di ragionamento low, medium, high o xhigh, con high come default. Sulla Responses API di xAI, ogni risposta Grok 4.7 include reasoning.encrypted_content; un loop multi-turno gestito dal client dovrebbe ripassare gli elementi di ragionamento restituiti senza modificarli nella richiesta successiva. I loop lunghi possono anche usare la compattazione del contesto: conserva l’elemento di compattazione restituito come stato opaco e aggiungi i nuovi turni dopo di esso. Poiché questi sono campi di risposta stateful e specifici del provider, verifica che la route CometAPI selezionata li restituisca end-to-end prima di farne una dipendenza di produzione.
Architettura dell’agente: il modello propone, la tua app decide
Un flusso sicuro di chiamata strumenti è semplice:
User request → model response → validate tool call → execute allowlisted tool → append tool result → model response
Il modello non riceve credenziali del database e non esegue direttamente Python. Produce una richiesta strutturata come “chiama get_order_status con questo ID ordine.” La tua applicazione controlla il nome dello strumento, analizza gli argomenti, applica autorizzazione e regole di business, esegue la funzione e restituisce un risultato serializzato.
Questa separazione conta più della scelta del modello. Un modello di fallback dovrebbe ereditare lo stesso confine degli strumenti—non uno più ampio—e i risultati degli strumenti devono essere trattati come dati non affidabili quando contengono contenuti esterni.
Come creare un agente IA Grok 4.7 con Python
Passaggio 1: Configura l’OpenAI Python SDK per CometAPI
Installa l’SDK OpenAI:
pip install openai
Imposta la configurazione tramite variabili d’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"
Questo tutorial usa Chat Completions perché le sue chiamate esplicite agli strumenti dell’assistente e i corrispondenti messaggi di risultato degli strumenti rendono il flusso di controllo facile da ispezionare in un esempio Python compatto. Per loop stateful più lunghi, valuta la Responses API come descritto sopra. Inoltre, non copiare vecchi ID di modello da un post del blog in produzione: recupera il catalogo pubblico di CometAPI GET /api/models durante la distribuzione o l’avvio, quindi conferma capacità e prezzi nella directory dei modelli.
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,
)
Il timeout esplicito e il retry dell’SDK disabilitato sono deliberati. L’applicazione classificherà gli errori e deciderà se ripetere la richiesta o passare al modello successivo. I retry nascosti rendono latenza, effetti collaterali duplicati e comportamento di fallback più difficili da comprendere.
Passaggio 2: Definisci prima strumenti ristretti e di sola lettura
Inizia con strumenti che leggono dati anziché modificarli. Le definizioni seguenti consentono all’agente di verificare un ordine e cercare l’inventario. L’implementazione restituisce dati demo; sostituiscila con chiamate autenticate ai tuoi servizi.
import json
TOOLS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Read the current status of one order.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
},
{
"type": "function",
"function": {
"name": "check_inventory",
"description": "Read available inventory for one SKU.",
"parameters": {
"type": "object",
"properties": {
"sku": {"type": "string"}
},
"required": ["sku"],
"additionalProperties": False,
},
},
},
]
def get_order_status(order_id: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"order_id": order_id, "status": "in_transit"}
def check_inventory(sku: str) -> dict:
# Replace this demo with an authenticated, read-only service call.
return {"sku": sku, "available_units": 12}
TOOL_REGISTRY = {
"get_order_status": get_order_status,
"check_inventory": check_inventory,
}
Uno schema JSON migliora la forma della richiesta, ma non è autorizzazione. Valida lunghezze e formati degli argomenti, conferma che l’utente corrente possa accedere all’ordine o allo SKU richiesti e limita la dimensione di ogni risultato di strumento prima di restituirlo al modello.
Passaggio 3: Aggiungi una politica di fallback multi-modello ristretta
Il fallback dovrebbe recuperare da un temporaneo errore di route, non nascondere richieste rotte. La guida ufficiale di fallback di CometAPI raccomanda di passare alla route successiva configurata per errori di connessione, timeout, HTTP 408, HTTP 429 e risposte 5xx temporanee. Credenziali non valide, parametri non supportati e richieste non valide dovrebbero fallire immediatamente.
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("No configured model completed the request") from last_error
L’elenco dei modelli è configurazione, non una classifica di qualità. Scegli fallbacks che supportino gli stessi ruoli di messaggio, schema degli strumenti, modalità di input, requisiti di contesto e comportamento di risposta necessari a questo agente. Registra la route selezionata e l’errore che ha causato ogni transizione.
Passaggio 4: Esegui il ciclo limitato dell’agente Grok 4.7
Il loop seguente invia la conversazione, esegue eventuali chiamate a strumenti consentiti, aggiunge i risultati con il tool_call_id corrispondente e chiede al modello selezionato di completare la risposta.
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
if name not in TOOL_REGISTRY:
return json.dumps({"error": f"Tool not allowed: {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"Invalid tool arguments: {error}"})
def run_agent(user_text: str, max_turns: int = 4) -> dict:
messages = [
{
"role": "system",
"content": (
"You are a support agent. Use tools only when needed. "
"Never invent order or inventory data."
),
},
{"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("Agent stopped after reaching max_turns")
result = run_agent("Where is order A-104, and is SKU BLUE-42 in stock?")
print(result["answer"])
print(result["routes"])
Il codice supporta più chiamate a strumenti in una singola risposta del modello perché aggiunge un risultato per ogni chiamata restituita. Se uno strumento cambia stato—inviare un’email, effettuare un ordine o emettere un rimborso—aggiungi una chiave di idempotenza e un passaggio di conferma umana. Non riavviare mai ciecamente l’intero turno dell’agente dopo un timeout se un effetto collaterale potrebbe essere già avvenuto.
Come GPT, Claude, Gemini e DeepSeek si adattano alla stessa app
CometAPI può ridurre la duplicazione a livello di connessione: un account, un base URL compatibile con OpenAI per il percorso comune e un ID di modello selezionato dal codice dell’applicazione. Questo rende GPT, Claude, Gemini, DeepSeek e Grok candidati dietro un’unica interfaccia interna.
Non rende i modelli intercambiabili. Prima di aggiungere un fallback, verifica:
- che l’ID di modello corrente venga restituito dal catalogo CometAPI;
- che la route supporti lo schema degli strumenti e i ruoli di messaggio richiesti;
- che gli argomenti delle chiamate agli strumenti e il comportamento con chiamate multiple corrispondano al contratto dell’agente;
- che la finestra di contesto e le modalità di input si adattino alla richiesta;
- che la risposta possa essere validata prima di raggiungere l’utente;
- che latenza e costo rimangano entro il budget di prodotto.
Funzionalità native del provider possono richiedere un endpoint nativo o un adapter separato. Mantieni esplicite tali eccezioni anziché forzare ogni capacità attraverso l’interfaccia comune.
Il fallback multi-modello di Grok 4.7 non è lo stesso di un sistema multi-agente
Una catena di fallback multi-modello sceglie un altro modello quando una route fallisce. Un sistema multi-agente assegna responsabilità diverse ad agenti separati—per esempio, un planner, un ricercatore e un revisore. I due modelli risolvono problemi diversi.
Se estendi questo agente Grok 4.7 in un workflow multi-agente, assegna a ciascun lavoratore un ruolo ristretto, un elenco di strumenti consentiti separato, un budget limitato e un handoff strutturato. Non permettere a ogni agente di chiamare ogni strumento o di inoltrare una trascrizione illimitata. Inizia con un agente finché i dati di valutazione non dimostrano che la separazione dei ruoli migliora il risultato.
Parapetti di produzione per un agente IA Grok 4.7
Valida prima dell’esecuzione degli strumenti
Controlla nomi degli strumenti, schemi degli argomenti, appartenenza del tenant, permessi utente e limiti di rate in codice applicativo. Considera le descrizioni degli strumenti come guida per il modello, non come controllo di sicurezza.
Separa strumenti di lettura da strumenti di scrittura
Gli strumenti di sola lettura possono spesso essere eseguiti automaticamente dopo l’autorizzazione. Gli strumenti di scrittura dovrebbero richiedere controlli più rigorosi, idempotenza e conferma per azioni rilevanti.
Limita ogni loop
Imposta un massimo di turni del modello, chiamate a strumenti, tempo wall-clock, dimensione del prompt e budget di token. Restituisci un errore controllato o un percorso di escalation quando si raggiunge un limite.
Registra la traccia decisionale
Registra l’attività richiesta, la versione di policy, l’ID di modello selezionato, la ragione del fallback, il nome dello strumento, la latenza dello strumento, il risultato della validazione, l’uso dei token e lo stato finale. Non registrare segreti o contenuti dei clienti non necessari.
Usa test di contratto, non assunzioni
Esegui gli stessi fixture contro ogni modello configurato. Una suite minima utile copre una risposta normale, una chiamata a strumento, chiamate multiple a strumenti, argomenti malformati, uno strumento sconosciuto, un timeout dello strumento, un 429 del modello primario e una chiave API non valida che non deve innescare fallback.
Lista di controllo per la distribuzione
- Recupera gli ID di modello correnti e verifica la route Grok 4.7 prima della distribuzione.
- Conserva la chiave CometAPI in un secret manager, mai nel codice sorgente o nei prompt.
- Inizia con strumenti di sola lettura e schemi JSON espliciti.
- Applica autenticazione e autorizzazione del tenant prima di ogni chiamata a strumenti.
- Consenti il fallback solo per errori transitori classificati.
- Testa ogni fallback rispetto allo stesso contratto di chiamata degli strumenti.
- Aggiungi idempotenza e conferma prima di abilitare strumenti di scrittura.
- Imposta limiti su loop, latenza, contesto e costo.
- Misura il successo del task, non solo la disponibilità dell’API.
Perché costruire questo agente tramite CometAPI?
CometAPI è utile qui perché l’integrazione comune rimane piccola. L’OpenAI Python SDK punta a un unico base URL, Grok 4.7 è selezionato tramite ID di modello e modelli compatibili di altri provider possono essere inseriti dietro la stessa politica di route di proprietà dell’applicazione.
Questo dà al team spazio per valutare GPT, Claude, Gemini e DeepSeek senza disseminare codice di connessione specifico del provider nel prodotto. Preserva anche un confine importante: CometAPI fornisce accesso, mentre la tua applicazione gestisce controlli di capacità, esecuzione degli strumenti, politica di fallback, valutazione e comportamento rivolto all’utente.
Consulta l’attuale pagina del modello Grok 4.7, configura il client dal quickstart di CometAPI e recupera gli ID di modello correnti prima di scegliere i fallback di produzione.
FAQ
Quale API dovrei usare per un’app con GPT, Claude, Gemini e DeepSeek?
Per il percorso comune di chat e chiamata agli strumenti, un’API unificata compatibile con OpenAI come CometAPI può ridurre il lavoro di integrazione. Mantieni selezione del modello e politica di fallback nella tua applicazione e usa adapter nativi del provider quando una funzionalità richiesta non si adatta al contratto condiviso.
Grok 4.7 può chiamare direttamente funzioni Python?
Grok 4.7 può restituire richieste di chiamata di funzione strutturate. La tua applicazione Python analizza la richiesta, la valida, esegue una funzione nell’elenco dei consentiti e invia il risultato al modello. Il modello in sé non esegue Python localmente.
Ogni errore dovrebbe attivare un modello diverso?
No. Usa il fallback per selezionati errori di connessione, timeout, 408, 429 e risposte 5xx temporanee. Le richieste non valide, i fallimenti di autenticazione e i parametri non supportati dovrebbero essere corretti, non inviati a un altro modello.
Posso usare uno stesso schema di strumenti con ogni modello?
Solo dopo i test. Un trasporto condiviso non garantisce comportamento identico degli strumenti, qualità degli argomenti, comportamento con chiamate parallele o enforcement dello schema. Aggiungi un modello alla catena solo dopo che ha superato i test di contratto dell’agente.
Un sistema di fallback multi-modello è un sistema multi-agente?
No. Il fallback cambia il modello utilizzato per una richiesta dopo un errore di route. L’architettura multi-agente assegna task diversi ad agenti separati. Costruiscili come layer distinti con test e controlli separati.