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 lżejsza 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 pracuje przez zdecentralizowaną sieć Gonka za grosze. Metoda run_sync jest wygodna dla skryptów; dla kodu asynchronicznego istnieje await agent.run(...).

Parametry modelu: okno kontekstowe Qwen3-235B to 128K tokenów (131072), maksymalna długość odpowiedzi przez Gateway to do 8192 tokenów. Wyjście można ograniczyć poprzez ustawienia modelu (OpenAIChatModelSettings(max_tokens=8192)). Dostępne są również moonshotai/Kimi-K2.6 (do 3072 tokenów wyjścia) i MiniMaxAI/MiniMax-M2.7 (do 4096) — wystarczy zmienić nazwę modelu w pierwszym argumencie OpenAIChatModel.

Głównym powodem wyboru 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 wykorzystuje wywołanie narzędzi modelu, aby wymusić zwrócenie danych ściśle według schematu, waliduje je i zwraca gotowy obiekt poprzez 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 — programista backendu, zna Pythona, Go i Postgres"
)
print(result.output)
# name='Anna' role='programista backendu' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — już list[str], nie tekst

Działa to, ponieważ Qwen3-235B (i oba inne modele Gonka) obsługują natywne wywoływanie narzędzi — PydanticAI opiera się na tym, aby zwrócić prawidłową strukturę JSON. W rezultacie otrzymujesz typizowany obiekt Pythona, a nie ciąg znaków, który musisz ręcznie analizować. Idealne do ekstrakcji danych, klasyfikacji, wypełniania formularzy oraz potoków RAG, gdzie wynik musi przejść dalej w kodzie w ścisłym formacie.

PydanticAI to framework dla agentów i potoków, które działają nieprzerwanie: wydobywają dane, wywołują narzędzia, przetwarzają strumienie zapytań. W tym przypadku koszt tokenów decyduje o tym, czy projekt pozostanie prototypem, czy wejdzie do produkcji. Porównajmy typowe obciążenia:

Różnica — setki i tysiące razy. Dla prototypu oznacza to, że 10M darmowych tokenów wystarcza na setki uruchomień agenta. Dla produkcji, która przetwarza setki tysięcy zapytań dziennie, oszczędności sięgają dziesiątek 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 dla formatu Anthropic (/v1/messages) — ale dla PydanticAI wystarczy endpoint kompatybilny z OpenAI, pokazany powyżej.

Druga kluczowa możliwość PydanticAI — narzędzia. Funkcję można zarejestrować za pomocą dekoratora @agent.tool_plain (bez kontekstu) lub @agent.tool (z dostępem do RunContext i wstrzykiwaniem zależności). Model sam decyduje, kiedy wywołać narzędzie, odbiera 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-twój-klucz",
    ),
)

agent = Agent(
    model,
    instructions="Jesteś pomocnikiem. 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ż wywoływanie narzędzi w Gonka jest natywne, narzędzia są wywoływane niezawodnie — bez kruchego parsowania tekstowych odpowiedzi. Cały cykl (zapytanie → wywołanie narzędzia → ostateczna odpowiedź) kosztuje około $0.00001 za pośrednictwem Gonka w porównaniu do $0.04–0.22 w OpenAI/Anthropic.

Jaki model wybrać: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — domyślny, najlepszy balans jakości i największy limit wyjścia (8192). moonshotai/Kimi-K2.6 jest silny w kodowaniu i złożonych rozumowaniach (wyjście do 3072). MiniMaxAI/MiniMax-M2.7 — do długich dialogów (wyjście do 4096). Wszystkie trzy są dostępne od razu za pomocą jednego klucza — zmienia się tylko nazwa modelu. Podobne narzędzia: LangChain do łańcuchów i RAG, LlamaIndex do indeksowania danych.