Jeśli chcesz zbudować jedną aplikację AI z GPT, Claude, Gemini, DeepSeek i Grok, użyj ujednoliconego API dla wspólnej ścieżki żądania i utrzymuj politykę trasowania wewnątrz aplikacji. CometAPI dostarcza zgodny z OpenAI bazowy URL oraz współdzielony katalog modeli, dzięki czemu usługa w Pythonie może wywoływać różne identyfikatory modeli przez jednego klienta. To Twój kod nadal decyduje, który model zostanie uruchomiony, jakie narzędzia są dozwolone i kiedy fallback jest bezpieczny.
Ten samouczek buduje agenta Grok 4.7, który może żądać dwóch biznesowych narzędzi tylko do odczytu, odrzuca nieznane narzędzia i błędne argumenty przed wykonaniem, oraz przełącza się na inny model przetestowany kontraktowo dopiero po wybranych przejściowych awariach. Celem nie jest magiczny autonomiczny system. To mała, inspekowalna pętla, którą można testować i obsługiwać w produkcji.
Co budujesz
Agent ma pięć jawnych części:
- Jednego klienta CometAPI. OpenAI Python SDK używa bazowego URL CometAPI pokazanym w konfiguracji poniżej.
- Grok 4.7 jako model podstawowy. Bieżący identyfikator modelu w CometAPI to
grok-4.7. - Rejestr narzędzi. Model może zaproponować wywołanie funkcji, ale tylko kod aplikacji może wykonać funkcję z listy dozwolonych.
- Ograniczoną pętlę agenta. Pętla zatrzymuje się po stałej liczbie tur modelu zamiast działać bez końca.
- Uporządkowaną politykę fallback. Zgodne identyfikatory modeli GPT, Claude, Gemini lub DeepSeek są próbowane dopiero po błędzie modelu/API kwalifikującym się do ponowienia.
Grok 4.7 obsługuje wywoływanie funkcji, a CometAPI obecnie dokumentuje zarówno trasy /v1/chat/completions, jak i /v1/responses dla tego modelu. Ten samouczek używa Chat Completions, ponieważ jego zgodne z OpenAI „tools”, wywołania narzędzi przez asystenta oraz pasujące wiadomości wynikowe typu tool mapują się bezpośrednio na zwartą, inspekowalną pętlę w Pythonie. Zgodność transportowa nie dowodzi parytetu funkcji w każdym modelu, więc każdy skonfigurowany fallback musi przejść te same testy kontraktowe, zanim trafi do produkcji.
Stan rozumowania w wieloturowych agentach Grok 4.7
Grok 4.7 przyjmuje poziom wysiłku rozumowania: low, medium, high lub xhigh, z domyślnym high. W Responses API xAI każda odpowiedź Grok 4.7 zawiera reasoning.encrypted_content; pętla wieloturowa zarządzana przez klienta powinna przekazywać zwrócone elementy rozumowania bez zmian w następnym żądaniu. Długie pętle mogą także używać context compaction: zachowuj zwrócony element kompakcji jako nieprzezroczysty stan i dołączaj po nim nowe tury. Ponieważ są to stanowe, specyficzne dla dostawcy pola odpowiedzi, zweryfikuj, że wybrana trasa CometAPI zwraca je end-to-end, zanim uczynisz z nich zależność produkcyjną.
Architektura agenta: model proponuje, aplikacja decyduje
Bezpieczny przepływ wywoływania narzędzi jest prosty:
Żądanie użytkownika → odpowiedź modelu → waliduj wywołanie narzędzia → wykonaj dozwolone narzędzie → dołącz wynik narzędzia → odpowiedź modelu
Model nigdy nie otrzymuje poświadczeń do bazy danych i nigdy nie wykonuje bezpośrednio Pythona. Zwraca ustrukturyzowane żądanie, takie jak „wywołaj get_order_status z tym identyfikatorem zamówienia”. Twoja aplikacja sprawdza nazwę narzędzia, parsuje argumenty, stosuje autoryzację i zasady biznesowe, uruchamia funkcję i zwraca zserializowany wynik.
Ten podział jest ważniejszy niż wybór modelu. Model fallback powinien dziedziczyć to samo ograniczenie granicy narzędzi — nie szersze — a wyniki narzędzi należy traktować jako niezaufane dane, gdy zawierają treści z zewnętrznych źródeł.
Jak zbudować agenta AI Grok 4.7 w Pythonie
Krok 1: Skonfiguruj OpenAI Python SDK dla CometAPI
Zainstaluj SDK OpenAI:
pip install openai
Ustaw konfigurację przez zmienne środowiskowe:
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"
Ten samouczek używa Chat Completions, ponieważ jawne wywołania narzędzi przez asystenta i pasujące wiadomości wynikowe narzędzi ułatwiają inspekcję przepływu sterowania w zwartym przykładzie w Pythonie. Dla dłuższych, stanowych pętli rozważ użycie Responses API, jak opisano wyżej. Ponadto nie kopiuj starych identyfikatorów modeli z wpisu na blogu do produkcji: pobierz publiczny katalog CometAPI GET /api/models podczas wdrażania lub uruchamiania, a następnie potwierdź możliwości i ceny w katalogu modeli.
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,
)
Świadomie ustawiono jawny timeout i wyłączono ponowienia po stronie SDK. Aplikacja sklasyfikuje błędy i zdecyduje, czy powtórzyć żądanie, czy przejść do następnego modelu. Ukryte retry utrudniają zrozumienie opóźnień, zduplikowanych efektów ubocznych i zachowania fallback.
Krok 2: Najpierw zdefiniuj wąskie, tylko do odczytu narzędzia
Zacznij od narzędzi, które odczytują dane zamiast je zmieniać. Poniższe definicje pozwalają agentowi sprawdzić zamówienie i wyszukać stan magazynu. Implementacja zwraca dane demo; zastąp ją uwierzytelnionymi wywołaniami do własnych usług.
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,
}
Schemat JSON poprawia kształt żądania, ale nie jest autoryzacją. Waliduj długości i formaty argumentów, potwierdź, że bieżący użytkownik może uzyskać dostęp do żądanego zamówienia lub SKU, i ogranicz rozmiar każdego wyniku narzędzia przed zwróceniem go do modelu.
Krok 3: Dodaj wąską politykę multi-model fallback
Fallback powinien odzyskiwać po tymczasowej awarii trasy, a nie ukrywać błędne żądania. Oficjalny przewodnik fallback CometAPI zaleca przejście do następnej skonfigurowanej trasy dla błędów połączenia, timeoutów, HTTP 408, HTTP 429 i tymczasowych odpowiedzi 5xx. Nieprawidłowe poświadczenia, nieobsługiwane parametry i nieprawidłowe żądania powinny kończyć się natychmiast.
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
Lista modeli to konfiguracja, a nie ranking jakości. Wybierz fallbacki, które obsługują ten sam schemat wiadomości, schemat narzędzi, modalność wejścia, wymagania kontekstowe i zachowanie odpowiedzi wymagane przez tego agenta. Loguj wybraną trasę i błąd, który spowodował każde przejście.
Krok 4: Uruchom ograniczoną pętlę agenta Grok 4.7
Poniższa pętla wysyła konwersację, wykonuje wszelkie wywołania dozwolonych narzędzi, dołącza wyniki z pasującym tool_call_id i prosi wybrany model o dokończenie odpowiedzi.
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"])
Kod obsługuje wiele wywołań narzędzi w jednej odpowiedzi modelu, ponieważ dołącza wynik dla każdego zwróconego wywołania. Jeśli narzędzie zmienia stan — wysyła e-mail, składa zamówienie lub wykonuje zwrot — dodaj klucz idemopotencji i krok potwierdzenia przez człowieka. Nigdy nie uruchamiaj całej tury agenta na ślepo po timeoutcie, jeśli efekt uboczny mógł już wystąpić.
Jak GPT, Claude, Gemini i DeepSeek mieszczą się w tej samej aplikacji
CometAPI może ograniczyć duplikację na warstwie połączeń: jedno konto, jeden zgodny z OpenAI bazowy URL dla wspólnej ścieżki, a identyfikator modelu wybierany przez kod aplikacji. To sprawia, że GPT, Claude, Gemini, DeepSeek i Grok są kandydatami za jednym wewnętrznym interfejsem.
To nie czyni modeli zamiennymi. Przed dodaniem fallbacku zweryfikuj:
- bieżący identyfikator modelu jest zwrócony przez katalog CometAPI;
- trasa obsługuje wymagany schemat narzędzi i role wiadomości;
- argumenty wywołań narzędzi i zachowanie wielu wywołań pasują do kontraktu agenta;
- okno kontekstu i modalności wejścia pasują do żądania;
- odpowiedź da się zwalidować, zanim dotrze do użytkownika;
- opóźnienie i koszt mieszczą się w budżecie produktu.
Funkcje natywne dostawcy mogą wymagać natywnego endpointu lub osobnego adaptera. Trzymaj te wyjątki jawnie, zamiast forsować każdą zdolność przez wspólny interfejs.
Multi-model fallback w Grok 4.7 to nie to samo co multi-agent
Łańcuch multi-model fallback wybiera inny model, gdy trasa zawiedzie. System multi-agent przydziela różne odpowiedzialności oddzielnym agentom — na przykład planistę, badacza i recenzenta. Te dwa wzorce rozwiązują różne problemy.
Jeśli rozbudujesz tego agenta Grok 4.7 do przepływu multi-agent, nadaj każdemu pracownikowi wąską rolę, osobną listę dozwolonych narzędzi, ograniczony budżet i ustrukturyzowane przekazanie. Nie pozwalaj, by każdy agent wywoływał każde narzędzie ani przekazywał nieograniczoną transkrypcję. Zacznij od jednego agenta, dopóki dane ewaluacyjne nie wykażą, że podział ról poprawia wynik.
Produkcyjne poręcze bezpieczeństwa dla agenta Grok 4.7
Waliduj przed wykonaniem narzędzia
Sprawdzaj nazwy narzędzi, schematy argumentów, własność dzierżawy, uprawnienia użytkownika i limity szybkości w kodzie aplikacji. Opisy narzędzi traktuj jako wskazówki dla modelu, a nie jako kontrolę bezpieczeństwa.
Oddziel narzędzia odczytu od narzędzi zapisu
Narzędzia tylko do odczytu można często uruchamiać automatycznie po autoryzacji. Narzędzia zapisu powinny wymagać silniejszych kontroli, idemopotencji i potwierdzenia dla działań o konsekwencjach.
Ogranicz każdą pętlę
Ustaw maksymalną liczbę tur modelu, wywołań narzędzi, czas ścienny, rozmiar promptu i budżet tokenów. Zwracaj kontrolowany błąd lub ścieżkę eskalacji po osiągnięciu limitu.
Rejestruj ślad decyzji
Loguj żądane zadanie, wersję polityki, wybrany identyfikator modelu, powód fallbacku, nazwę narzędzia, opóźnienie narzędzia, wynik walidacji, zużycie tokenów i status końcowy. Nie loguj sekretów ani niepotrzebnych treści klientów.
Używaj testów kontraktowych, nie założeń
Uruchamiaj te same zestawy testowe przeciwko każdemu skonfigurowanemu modelowi. Minimalny przydatny pakiet obejmuje zwykłą odpowiedź, jedno wywołanie narzędzia, wiele wywołań narzędzi, błędne argumenty, nieznane narzędzie, timeout narzędzia, 429 z modelu podstawowego i nieprawidłowy klucz API, który nie może uruchamiać fallbacku.
Lista kontrolna wdrożenia
- Pobierz bieżące identyfikatory modeli i zweryfikuj trasę Grok 4.7 przed wdrożeniem.
- Przechowuj klucz CometAPI w menedżerze sekretów, nigdy w kodzie źródłowym ani promptach.
- Zacznij od narzędzi tylko do odczytu i jawnych schematów JSON.
- Zastosuj uwierzytelnianie i autoryzację dzierżawy przed każdym wywołaniem narzędzia.
- Zezwól na fallback tylko dla sklasyfikowanych błędów przejściowych.
- Testuj każdy fallback według tego samego kontraktu wywołań narzędzi.
- Dodaj idemopotencję i potwierdzenie przed włączeniem narzędzi zapisu.
- Ustaw limity pętli, opóźnień, kontekstu i kosztów.
- Mierz sukces zadania, nie tylko dostępność API.
Dlaczego budować tego agenta przez CometAPI?
CometAPI jest tu przydatne, ponieważ wspólna integracja pozostaje mała. OpenAI Python SDK wskazuje jeden bazowy URL, Grok 4.7 jest wybierany identyfikatorem modelu, a zgodne modele od innych dostawców można umieścić za tą samą, kontrolowaną przez aplikację polityką trasowania.
Daje to zespołowi przestrzeń do ewaluacji GPT, Claude, Gemini i DeepSeek bez rozpraszania specyficznego dla dostawców kodu połączeń w całym produkcie. Zachowuje też ważną granicę: CometAPI dostarcza dostęp, podczas gdy Twoja aplikacja odpowiada za sprawdzenia możliwości, wykonanie narzędzi, politykę fallback, ewaluację i zachowanie widoczne dla użytkownika.
Przejrzyj bieżącą stronę modelu Grok 4.7, skonfiguruj klienta według szybkiego startu CometAPI i pobierz bieżące identyfikatory modeli, zanim wybierzesz produkcyjne fallbacki.
FAQ
Jakiego API użyć do aplikacji z GPT, Claude, Gemini i DeepSeek?
Dla wspólnej ścieżki czatu i wywoływania narzędzi ujednolicone API zgodne z OpenAI, takie jak CometAPI, może zmniejszyć nakład integracji. Zachowaj wybór modelu i politykę fallback w aplikacji, a funkcje natywne dostawców obsługuj adapterami natywnymi, gdy wymagane możliwości nie mieszczą się w wspólnym kontrakcie.
Czy Grok 4.7 może bezpośrednio wywoływać funkcje Pythona?
Grok 4.7 może zwracać ustrukturyzowane żądania wywołania funkcji. Twoja aplikacja w Pythonie parsuje żądanie, waliduje je, wykonuje funkcję z listy dozwolonych i odsyła wynik z powrotem do modelu. Sam model nie wykonuje lokalnego Pythona.
Czy każdy błąd powinien uruchamiać inny model?
Nie. Używaj fallbacku dla wybranych błędów połączenia, timeoutów, 408, 429 i tymczasowych 5xx. Nieprawidłowe żądania, błędy uwierzytelniania i nieobsługiwane parametry należy naprawić, a nie wysyłać do innego modelu.
Czy można używać jednego schematu narzędzi ze wszystkimi modelami?
Tylko po przetestowaniu. Wspólny transport nie gwarantuje identycznego zachowania narzędzi, jakości argumentów, równoległych wywołań ani egzekwowania schematu. Dodaj model do łańcucha dopiero po przejściu testów kontraktowych agenta.
Czy system multi-model fallback to system multi-agent?
Nie. Fallback zmienia model użyty do żądania po awarii trasy. Architektura multi-agent przydziela różne zadania oddzielnym agentom. Buduj je jako odrębne warstwy z osobnymi testami i kontrolami.