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

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

Kurulum:

pip install pydantic-ai
# veya sadece OpenAI bağımlılıkları ile hafif sürüm:
# pip install "pydantic-ai-slim[openai]"

Minimal bir örnek — Gonka üzerinden bir ajan. PydanticAI, OpenAIChatModel'e aktarılan OpenAIProvider(base_url=..., api_key=...) aracılığıyla ö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-anahtariniz",
    ),
)

agent = Agent(model)

result = agent.run_sync("PoUW nedir, iki cümleyle açıkla")
print(result.output)

Hepsi bu kadar — PydanticAI ajanınız, merkeziyetsiz Gonka ağı üzerinden kuruşlarla çalışıyor. run_sync metodu scriptler için pratiktir; async kod için await agent.run(...) kullanılabilir.

Model parametreleri: Ağ modellerinin bağlam penceresi 200K token (200000), Gateway üzerinden maksimum yanıt uzunluğu 8192 tokene kadardır. Çıktıyı model ayarları üzerinden sınırlayabilirsiniz (OpenAIChatModelSettings(max_tokens=8192)). Ayrıca moonshotai/Kimi-K2.6 ve MiniMaxAI/MiniMax-M2.7 (her biri 8192 çıktı tokenine kadar) mevcuttur — sadece OpenAIChatModel'in ilk argümanındaki model ismini değiştirmeniz yeterlidir.

PydanticAI'yi seçmenin ana nedeni structured output özelliğidir. Yanıt metnini regex ile ayrıştırmak yerine, sonucu bir Pydantic modeli olarak tanımlarsınız ve bunu output_type parametresine aktarırsınız. Framework, modelin kendi tool calling yeteneğini kullanarak veriyi tam olarak şemaya göre döndürür, doğrular ve result.output üzerinden hazır bir obje olarak teslim eder.

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-anahtariniz",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Veri çıkar: Anna bir backend geliştiricisi, Python, Go ve Postgres biliyor"
)
print(result.output)
# name='Anna' role='backend geliştiricisi' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — zaten list[str], metin değil

Bu işe yarar çünkü her iki Gonka modeli de (Kimi K2.6 ve MiniMax M2.7) doğal (native) tool calling'i destekler — PydanticAI, geçerli bir JSON yapısı döndürmek için buna güvenir. Sonuç olarak, manuel olarak ayrıştırılması gereken bir string değil, tiplendirilmiş bir Python objesi alırsınız. Veri çıkarma, sınıflandırma, form doldurma ve sonucun katı bir formatta kod içinde ilerlemesi gereken RAG pipeline'ları için idealdir.

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

Fark, yüzlerce ve binlerce kattır. Bir prototip için bu, 10M ücretsiz tokenin yüzlerce ajan çalıştırılmasına yettiği anlamına gelir. Günde yüz binlerce isteği işleyen üretimde ise, aynı PydanticAI kodunu sadece farklı bir base_url ile 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'nin ikinci önemli özelliği araçlardır (tools). Bir fonksiyon, @agent.tool_plain (kontekst olmadan) veya @agent.tool (RunContext ve dependency injection erişimi ile) dekoratörü ile kaydedilebilir. 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-anahtarınız",
    ),
)

agent = Agent(
    model,
    instructions="Sen bir asistansın. Gerektiğinde araçları kullan.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Altı yüzlü bir zar atar ve sonucu döndürür."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Matematiksel bir ifadeyi hesaplar."""
    return str(eval(expression))


result = agent.run_sync("Zar at ve sonucu 7 ile çarp")
print(result.output)

Gonka'da tool calling yerel (native) olduğu için araçlar, metin yanıtlarını parçalamaya çalışırken oluşan kırılganlıklar olmadan güvenilir bir şekilde çağrılır. Tüm döngü (istek → araç çağrısı → nihai yanıt) Gonka üzerinden yaklaşık $0.00007 tutarken, OpenAI/Anthropic'te bu değer $0.04–0.22'dir.

Hangi modeli seçmeli?: moonshotai/Kimi-K2.6 — kodlama ve karmaşık akıl yürütmede güçlü, 8192'ye kadar çıktı. MiniMaxAI/MiniMax-M2.7 — uzun diyaloglar ve dengeli görevler için, 8192'ye kadar çıktı. Her ikisi de tek bir anahtar ile hemen erişilebilir — sadece model dizgisi değiştirilir. Benzer araçlar: Zincirleme ve RAG için LangChain, veri indeksleme için LlamaIndex.