PydanticAI + Gonka — typowane agenty AI za grosze

Najpierw uzyskaj klucz: zarejestruj się na gate.joingonka.ai/register — przy rejestracji dajemy 3M darmowych tokenów — i stwórz klucz jg-xxx w Dashboard → API Keys.

Instalacja:

pip install pydantic-ai
# lub lekka wersja tylko z zależnościami OpenAI:
# pip install "pydantic-ai-slim[openai]"

Minimalny przykład — agent przez Gonka. PydanticAI ustawia niestandardowy endpoint przez OpenAIProvider(base_url=..., api_key=...), który jest przekazywany do OpenAIChatModel:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-twój-klucz",
    ),
)

agent = Agent(model)

result = agent.run_sync("Wyjaśnij w dwóch zdaniach, czym jest PoUW")
print(result.output)

To wszystko — twój agent PydanticAI działa przez zdecentralizowaną sieć Gonka za grosze. Metoda run_sync jest wygodna dla skryptów; dla kodu async istnieje await agent.run(...).

Parametry modelu: okno kontekstowe MiniMax M2.7 — 200K tokenów (200000), u DeepSeek V4 Flash — 380K, u GLM-5.3 Flash — 390K; maksymalna długość odpowiedzi przez Gateway — do 8192 tokenów dla MiniMax i GLM-5.3 Flash, do 32768 dla DeepSeek. Możesz ograniczyć wyjście poprzez ustawienia modelu (OpenAIChatModelSettings(max_tokens=8192)). Dostępne są MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 oraz zai-org/GLM-5.3-Flash — wystarczy zmienić nazwę modelu w pierwszym argumencie OpenAIChatModel.

Głównym powodem, by wybrać PydanticAI, jest structured output. Zamiast parsować tekst odpowiedzi wyrażeniami regularnymi, opisujesz wynik jako model Pydantic i przekazujesz go do parametru output_type. Framework używa tool calling modelu, aby zmusić go do zwrócenia danych ściśle według schematu, waliduje je i oddaje gotowy obiekt przez result.output.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-twój-klucz",
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Wyodrębnij dane: Anna — backend-developer, zna Python, Go i Postgres"
)
print(result.output)
# name='Anna' role='backend-developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — już list[str], nie tekst

To działa, ponieważ wszystkie trzy modele Gonka (MiniMax M2.7, DeepSeek V4 Flash i GLM-5.3 Flash) obsługują natywny tool calling — PydanticAI opiera się na nim, aby zwrócić poprawną strukturę JSON. Na wyjściu otrzymujesz obiekt Python z typami, a nie ciąg znaków, który musiałbyś analizować ręcznie. Idealne do ekstrakcji danych, klasyfikacji, wypełniania formularzy i potoków RAG, gdzie wynik musi być dalej przetwarzany w kodzie w ścisłym formacie.

PydanticAI — framework dla agentów i pipeline'ów, które pracują nieprzerwanie: wyodrębniają dane, wywołują narzędzia, przetwarzają strumienie zapytań. Tutaj koszt tokenów decyduje o tym, czy projekt pozostanie prototypem, czy wejdzie w production. Porównajmy typowe obciążenia:

Różnica — setki i tysiące razy. Dla prototypu oznacza to, że 3M darmowych tokenów wystarcza na pierwsze uruchomienia agenta. Dla production, obsługującego setki tysięcy zapytań dziennie, oszczędność wynosi dziesiątki tysięcy dolarów miesięcznie — przy tym samym kodzie na PydanticAI, po prostu z innym base_url.

Jeden klucz jg-xxx i jedno saldo działają zarówno dla formatu OpenAI (/v1), jak i formatu Anthropic (/v1/messages) — ale dla PydanticAI wystarczy kompatybilny z OpenAI endpoint, pokazany powyżej.

Druga kluczowa funkcja PydanticAI to narzędzia. Funkcję można zarejestrować za pomocą dekoratora @agent.tool_plain (bez kontekstu) lub @agent.tool (z dostępem do RunContext i dependency injection). Model sam decyduje, kiedy wywołać narzędzie, otrzymuje wynik i kontynuuje rozumowanie:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-twój-klucz",
    ),
)

agent = Agent(
    model,
    instructions="Jesteś asystentem. Używaj narzędzi, gdy jest to potrzebne.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rzuca sześcienną kostką i zwraca wynik."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Oblicza wyrażenie matematyczne."""
    return str(eval(expression))


result = agent.run_sync("Rzuć kostką i pomnóż wynik przez 7")
print(result.output)

Ponieważ tool calling w Gonka jest natywny, narzędzia są wywoływane niezawodnie — bez kruchego parsowania odpowiedzi tekstowych. Cały cykl (zapytanie → wywołanie tool → finalna odpowiedź) kosztuje około $0.00007 przez Gonka wobec $0.04–0.22 w OpenAI/Anthropic.

Jaki model wybrać: MiniMaxAI/MiniMax-M2.7 — do długich dialogów i zrównoważonych zadań, wyjście do 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — jeden z najdłuższych kontekstów w sieci (380K) i tanie duże prompty, wyjście do 32768. zai-org/GLM-5.3-Flash — model reasoning do złożonych rozważań i najdłuższy kontekst w sieci (390K), wyjście do 8192; rozważania zużywają część max_tokens, należy ustawiać go z zapasem (od 600). Wszystkie trzy są dostępne od ręki za pomocą jednego klucza — zmienia się tylko ciąg znaków modelu. Bliskie ideowo narzędzia: LangChain do łańcuchów i RAG, LlamaIndex do indeksowania danych.