PydanticAI + Gonka — typowane agenty AI za grosze

Najpierw uzyskaj klucz: zarejestruj się na gate.joingonka.ai/register — przy rejestracji dajemy 10M darmowych tokenów — i utwó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 modeli sieci wynosi 200K tokenów (200000), maksymalna długość odpowiedzi przez Gateway — do 8192 tokenów. Wyjście można ograniczyć w ustawieniach modelu (OpenAIChatModelSettings(max_tokens=8192)). Dostępne są również moonshotai/Kimi-K2.6 oraz MiniMaxAI/MiniMax-M2.7 (każdy do 8192 tokenów wyjściowych) — wystarczy zmienić nazwę modelu w pierwszym argumencie OpenAIChatModel.

Głównym powodem, dla którego warto wybrać PydanticAI, jest structured output. Zamiast parsować tekst odpowiedzi za pomocą wyrażeń regularnych, 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ż jako list[str], nie tekst

Działa to, ponieważ oba modele Gonka (Kimi K2.6 i MiniMax M2.7) wspierają 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 trzeba analizować ręcznie. Idealne do ekstrakcji danych, klasyfikacji, wypełniania formularzy i potoków RAG, gdzie wynik musi dalej przechodzić przez kod w ściśle określonym formacie.

PydanticAI to framework dla agentów i pipeline'ów, które pracują w sposób ciągły: wyciągają dane, wywołują narzędzia, przetwarzają strumienie zapytań. Tutaj koszt tokenów decyduje, czy projekt pozostanie prototypem, czy trafi na produkcję. Porównajmy typowe obciążenia:

Różnica jest setki i tysiące razy większa. Dla prototypu oznacza to, że 10M darmowych tokenów wystarczy na setki uruchomień agenta. Dla produkcji przetwarzającej setki tysięcy zapytań dziennie oszczędność wynosi dziesiątki tysięcy dolarów miesięcznie — przy tym samym kodzie w PydanticAI, wystarczy podmienić base_url.

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

Druga kluczowa możliwość PydanticAI to narzędzia (tools). 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ć: moonshotai/Kimi-K2.6 — mocny w kodowaniu i złożonym rozumowaniu, output do 8192. MiniMaxAI/MiniMax-M2.7 — dla długich dialogów i zbalansowanych zadań, output do 8192. Oba są dostępne od ręki za pomocą jednego klucza — zmienia się tylko ciąg znaków modelu. Bliskie ideowo narzędzia: LangChain dla łańcuchów i RAG, LlamaIndex dla indeksowania danych.