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(
    "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(...).

Параметри моделі: контекстне вікно моделей мережі — 200K токенів (200000), максимальна довжина відповіді через Gateway — до 8192 токенів. Обмежити вивід можна через налаштування моделі (OpenAIChatModelSettings(max_tokens=8192)). Доступні також moonshotai/Kimi-K2.6 та MiniMaxAI/MiniMax-M2.7 (до 8192 токенів виводу кожна) — достатньо змінити ім'я моделі в першому аргументі 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 (Kimi K2.6 та MiniMax M2.7) підтримують нативний 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(
    "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.

Яку модель вибрати: moonshotai/Kimi-K2.6 — сильна в кодингу та складних міркуваннях, вивід до 8192. MiniMaxAI/MiniMax-M2.7 — для довгих діалогів і збалансованих завдань, вивід до 8192. Обидві доступні прямо зараз за одним ключем — змінюється тільки рядок моделі. Близькі за духом інструменти: LangChain для ланцюжків і RAG, LlamaIndex для індексації даних.