PydanticAI + Gonka — типізовані AI-агенти за копійки

Спочатку отримайте ключ: зареєструйтесь на gate.joingonka.ai/register — при реєстрації даємо 10M безкоштовних токенів — і створіть ключ jg-xxx у Dashboard → API Keys.

Встановлення:

pip install pydantic-ai
# або полегшений варіант тільки з OpenAI-залежностями:
# pip install "pydantic-ai-slim[openai]"

Мінімальний приклад — агент через Gonka. PydanticAI задає кастомний endpoint через OpenAIProvider(base_url=..., api_key=...), який передається в 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-ваш-ключ",
    ),
)

agent = Agent(model)

result = agent.run_sync("Поясни у двох реченнях, що таке PoUW")
print(result.output)

Це все — ваш PydanticAI-агент працює через децентралізовану мережу Gonka за копійки. Метод run_sync зручний для скриптів; для async-коду є await agent.run(...).

Параметри моделі: контекстне вікно Qwen3-235B — 128K токенів (131072), максимальна довжина відповіді через Gateway — до 8192 токенів. Обмежити виведення можна через налаштування моделі (OpenAIChatModelSettings(max_tokens=8192)). Доступні також moonshotai/Kimi-K2.6 (до 3072 токенів виведення) та MiniMaxAI/MiniMax-M2.7 (до 4096) — достатньо змінити ім'я моделі в першому аргументі OpenAIChatModel.

Головна причина вибрати PydanticAI — structured output. Замість того, щоб парсити текст відповіді регулярними виразами, ви описуєте результат як Pydantic-модель і передаєте її в параметр output_type. Фреймворк використовує tool calling моделі, щоб змусити її повернути дані строго за схемою, валідує їх і віддає вже готовий об'єкт через 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-ваш-ключ",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Витягни дані: Анна — backend-розробник, знає Python, Go та Postgres"
)
print(result.output)
# name='Анна' role='backend-розробник' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — вже list[str], не текст

Це працює, тому що Qwen3-235B (і обидві інші моделі Gonka) підтримують нативний tool calling — PydanticAI спирається на нього, щоб повернути валідну JSON-структуру. На виході ви отримуєте типізований об'єкт Python, а не рядок, який потрібно розбирати вручну. Ідеально для вилучення даних, класифікації, заповнення форм та RAG-пайплайнів, де результат повинен йти далі за кодом у строгому форматі.

PydanticAI — фреймворк для агентів та пайплайнів, які працюють безперервно: витягують дані, викликають інструменти, обробляють потоки запитів. Тут вартість токенів вирішує, чи залишиться проєкт прототипом, чи піде в production. Порівняємо типові навантаження:

Різниця — у сотні та тисячі разів. Для прототипу це означає, що 10M безкоштовних токенів вистачає на сотні прогонів агента. Для production, що обробляє сотні тисяч запитів на день, економія становить десятки тисяч доларів на місяць — при тому ж коді на PydanticAI, просто з іншим base_url.

Один ключ jg-xxx та один баланс працюють і для OpenAI-формату (/v1), і для Anthropic-формату (/v1/messages) — але для PydanticAI достатньо OpenAI-сумісного endpoint, показаного вище.

Друга ключова можливість PydanticAI — інструменти. Функцію можна зареєструвати декоратором @agent.tool_plain (без контексту) або @agent.tool (з доступом до RunContext та dependency injection). Модель сама вирішує, коли викликати інструмент, отримує результат і продовжує міркування:

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-ваш-ключ",
    ),
)

agent = Agent(
    model,
    instructions="Ти помічник. Використовуй інструменти, коли потрібно.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Кидає шестигранний кубик та повертає результат."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Обчислює математичний вираз."""
    return str(eval(expression))


result = agent.run_sync("Кинь кубик і помнож результат на 7")
print(result.output)

Оскільки tool calling у Gonka нативний, інструменти викликаються надійно — без крихкого парсингу текстових відповідей. Весь цикл (запит → виклик tool → фінальна відповідь) коштує близько $0.00001 через Gonka проти $0.04–0.22 у OpenAI/Anthropic.

Яку модель вибрати: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — дефолт, найкращий баланс якості та найбільший ліміт виведення (8192). moonshotai/Kimi-K2.6 сильна в кодінгу та складних міркуваннях (виведення до 3072). MiniMaxAI/MiniMax-M2.7 — для довгих діалогів (виведення до 4096). Всі три доступні прямо зараз за одним ключем — змінюється тільки рядок моделі. Близькі за духом інструменти: LangChain для ланцюжків та RAG, LlamaIndex для індексації даних.