PydanticAI + Gonka — typowane agenty AI za grosze

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

Instalacja:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# pip install "pydantic-ai-slim[openai]"

Minimalny przykład — agent przez Gonka. PydanticAI ustawia własny endpoint przez OpenAIProvider(base_url=..., api_key=...), który przekazujesz 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-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

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

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

Główny powód, by wybrać PydanticAI, to structured output. Zamiast parsować tekst odpowiedzi regexami, opisujesz wynik jako model Pydantic i przekazujesz go w parametrze output_type. Framework korzysta z tool calling modelu, żeby wymusić zwrócenie 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-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

Działa to dlatego, że 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, żeby zwrócić poprawną strukturę JSON. Na wyjściu dostajesz typowany obiekt Pythona, a nie string, który trzeba rozbierać ręcznie. Idealne do ekstrakcji danych, klasyfikacji, wypełniania formularzy i pipeline'ów RAG, gdzie wynik musi trafić dalej do kodu 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 możliwość PydanticAI to narzędzia. Funkcję rejestrujesz dekoratorem @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-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rolls a six-sided die and returns the result."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 7")
print(result.output)

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

Który model wybrać: MiniMaxAI/MiniMax-M2.7 — do długich rozmó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 reasoningowy do złożonych rozumowań i najdłuższy kontekst w sieci (390K), wyjście do 8192; rozumowanie zużywa część max_tokens, ustaw go z zapasem (od 600). Wszystkie trzy są dostępne od razu przez jeden klucz — zmienia się tylko nazwa modelu. Narzędzia o podobnym duchu: LangChain do łańcuchów i RAG, LlamaIndex do indeksowania danych.