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

Спочатку отримайте ключ: зареєструйтеся на gate.joingonka.ai/register — при реєстрації даємо 3M безкоштовних токенів — і створіть ключ 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(
    "MiniMaxAI/MiniMax-M2.7",
    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(...).

Параметри моделі: контекстне вікно MiniMax M2.7 — 200K токенів (200000), у DeepSeek V4 Flash — 380K, у GLM-5.3 Flash — 390K; максимальна довжина відповіді через Gateway — до 8192 токенів у MiniMax та GLM-5.3 Flash, до 32768 у DeepSeek. Обмежити вивід можна через налаштування моделі (OpenAIChatModelSettings(max_tokens=8192)). Доступні MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 та zai-org/GLM-5.3-Flash — достатньо змінити ім'я моделі в першому аргументі 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(
    "MiniMaxAI/MiniMax-M2.7",
    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], не текст

Це працює, тому що всі три моделі Gonka (MiniMax M2.7, DeepSeek V4 Flash та GLM-5.3 Flash) підтримують нативний tool calling — PydanticAI спирається на нього, щоб повернути валідну JSON-структуру. На виході ви отримуєте типізований об'єкт Python, а не рядок, який потрібно розбирати вручну. Ідеально для вилучення даних, класифікації, заповнення форм та RAG-пайплайнів, де результат має йти далі по коду в суворому форматі.

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

Різниця — в сотні й тисячі разів. Для прототипу це означає, що 3M безкоштовних токенів вистачає на перші прогони агента. Для 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(
    "MiniMaxAI/MiniMax-M2.7",
    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.00007 через Gonka проти $0.04–0.22 у OpenAI/Anthropic.

Яку модель обрати: MiniMaxAI/MiniMax-M2.7 — для довгих діалогів і збалансованих завдань, вивід до 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — один з найдовших контекстів мережі (380K) і дешеві великі промпти, вивід до 32768. zai-org/GLM-5.3-Flash — reasoning-модель для складних міркувань і найдовший контекст мережі (390K), вивід до 8192; міркування витрачають частину max_tokens, задавайте його із запасом (від 600). Усі три доступні прямо зараз за одним ключем — змінюється лише рядок моделі. Близькі за духом інструменти: LangChain для ланцюжків і RAG, LlamaIndex для індексації даних.