PydanticAI + Gonka — tip güvenli yapay zeka ajanları kuruşa

Önce anahtarı alın: gate.joingonka.ai/register adresinden kaydolun — kayıtta 3M ücretsiz token veriyoruz — ve Dashboard → API Keys bölümünde jg-xxx anahtarını oluşturun.

Kurulum:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# pip install "pydantic-ai-slim[openai]"

Minimal örnek — Gonka üzerinden bir agent. PydanticAI, OpenAIChatModel'e aktarılan OpenAIProvider(base_url=..., api_key=...) ile özel bir endpoint tanımlar:

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)

Hepsi bu — PydanticAI agent'ınız merkeziyetsiz Gonka ağı üzerinden neredeyse bedavaya çalışıyor. run_sync metodu script'ler için kullanışlıdır; async kod için await agent.run(...) var.

Model parametreleri: MiniMax M2.7'nin bağlam penceresi 180K token (180000), DeepSeek V4 Flash'ın 380K, GLM-5.3 Flash'ın 390K; Gateway üzerinden maksimum yanıt uzunluğu MiniMax ve GLM-5.3 Flash'ta 8192 token'a, DeepSeek'te 32768'e kadar. Çıktıyı model ayarlarıyla sınırlayabilirsiniz (OpenAIChatModelSettings(max_tokens=8192)). MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 ve zai-org/GLM-5.3-Flash kullanılabilir — OpenAIChatModel'in ilk argümanındaki model adını değiştirmeniz yeterli.

PydanticAI'yı seçmenin ana nedeni structured output. Yanıt metnini regex'lerle ayrıştırmak yerine, sonucu bir Pydantic modeli olarak tanımlar ve output_type parametresine aktarırsınız. Framework, modelin tool calling özelliğini kullanarak veriyi kesinlikle şemaya uygun döndürmesini sağlar, doğrular ve result.output üzerinden hazır bir nesne sunar.

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

Bu işe yarıyor çünkü üç Gonka modeli de (MiniMax M2.7, DeepSeek V4 Flash ve GLM-5.3 Flash) yerel tool calling'i destekliyor — PydanticAI geçerli bir JSON yapısı döndürmek için buna dayanıyor. Sonuçta elle ayrıştırmanız gereken bir string değil, tipli bir Python nesnesi elde edersiniz. Veri çıkarma, sınıflandırma, form doldurma ve sonucun kodda katı bir formatta ilerlemesi gereken RAG pipeline'ları için ideal.

PydanticAI, sürekli çalışan ajanlar ve pipeline'lar için bir çerçevedir: veri çeker, araçları çağırır, istek akışlarını işler. Burada token maliyeti, projenin prototip mi kalacağını yoksa üretime mi geçeceğini belirler. Tipik yükleri karşılaştıralım:

Fark yüzlerce ve binlerce katıdır. Bir prototip için bu, 3M ücretsiz tokenin ajanın ilk testleri için yeterli olduğu anlamına gelir. Günde yüz binlerce istek işleyen bir üretim ortamında, aynı PydanticAI koduyla sadece farklı bir base_url kullanarak ayda on binlerce dolar tasarruf edersiniz.

Bir jg-xxx anahtarı ve bir bakiye, hem OpenAI formatı (/v1) hem de Anthropic formatı (/v1/messages) için çalışır — ancak PydanticAI için yukarıda gösterilen OpenAI uyumlu endpoint yeterlidir.

PydanticAI'nın ikinci kilit özelliği araçlar. Bir fonksiyonu @agent.tool_plain decorator'ı (bağlam olmadan) veya @agent.tool (RunContext'e ve dependency injection'a erişimle) ile kaydedebilirsiniz. Model, aracı ne zaman çağıracağına kendisi karar verir, sonucu alır ve akıl yürütmeye devam eder:

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)

Gonka'da tool calling yerel olduğu için araçlar güvenilir şekilde çağrılır — metin yanıtlarının kırılgan ayrıştırması olmadan. Tüm döngü (istek → tool çağrısı → nihai yanıt) Gonka üzerinden yaklaşık $0.00007'ye mal olurken, OpenAI/Anthropic'te $0.04–0.22 arasında.

Hangi modeli seçmeli: MiniMaxAI/MiniMax-M2.7 — uzun diyaloglar ve dengeli görevler için, çıktı 8192'ye kadar. deepseek-ai/DeepSeek-V4-Flash-0731 — ağın en uzun bağlamlarından biri (380K) ve ucuz büyük prompt'lar, çıktı 32768'e kadar. zai-org/GLM-5.3-Flash — karmaşık akıl yürütme için bir reasoning modeli ve ağın en uzun bağlamı (390K), çıktı 8192'ye kadar; akıl yürütme max_tokens'ın bir kısmını harcar, bu yüzden onu pay bırakarak ayarlayın (600'den itibaren). Üçü de şu anda tek anahtarla kullanılabilir — sadece model satırı değişir. Benzer araçlar: zincirler ve RAG için LangChain, veri indeksleme için LlamaIndex.