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

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

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

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# 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-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

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

Параметри моделі: контекстне вікно MiniMax M2.7 — 180K токенів (180000), у 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-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

Це працює, бо всі три моделі 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-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rolls a six-sided die and returns the result."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 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 для індексації даних.