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

Öncelikle bir anahtar edinin: gate.joingonka.ai/register adresinden kaydolun — kayıt sırasında 3M ücretsiz token veriyoruz — ve Dashboard → API Keys kısmından jg-xxx anahtarınızı 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]"

Minimum örnek — Gonka üzerinden bir ajan. PydanticAI, OpenAIChatModel içine 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-anahtarınız",
    ),
)

agent = Agent(model)

result = agent.run_sync("PoUW'nin ne olduğunu iki cümlede açıkla")
print(result.output)

Hepsi bu kadar — PydanticAI ajanınız merkeziyetsiz Gonka ağı üzerinden çok düşük maliyetle çalışıyor. run_sync metodu scriptler için uygundur; async kod için await agent.run(...) kullanabilirsiniz.

Model parametreleri: MiniMax M2.7 bağlam penceresi 200K token (200000), DeepSeek V4 Flash'ta 380K, GLM-5.3 Flash'ta 390K'dır; Gateway üzerinden maksimum yanıt uzunluğu MiniMax ve GLM-5.3 Flash için 8192 tokene kadar, DeepSeek için 32768 tokene kadardır. Çıktıyı model ayarlarından 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 — sadece OpenAIChatModel'in ilk argümanındaki model adını değiştirmeniz yeterlidir.

PydanticAI'yi seçmenin ana nedeni structured output (yapılandırılmış çıktı) özelliğidir. Yanıt metnini regex ile ayrıştırmak yerine, sonucu bir Pydantic modeli olarak tanımlar ve output_type parametresine aktarırsınız. Framework, modelin tool calling yeteneğini kullanarak verileri tam olarak şemaya göre döndürmesini sağlar, bunları doğrular ve result.output üzerinden hazır bir nesne olarak 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-anahtarınız",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Verileri çıkar: Anna 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'] — metin değil, liste

Bu çalışır çünkü üç Gonka modeli de (MiniMax M2.7, DeepSeek V4 Flash ve GLM-5.3 Flash) yerel tool calling destekler — PydanticAI geçerli bir JSON yapısı döndürmek için buna güvenir. Sonuçta, manuel olarak ayrıştırmanız gereken bir dize yerine tiplendirilmiş bir Python nesnesi alırsınız. Veri çıkarma, sınıflandırma, form doldurma ve RAG pipeline'ları için idealdir; burada sonuç, kodun geri kalanında kesin bir formatta ilerlemelidir.

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'nin ikinci temel özelliği araçlardır (tools). Bir fonksiyon, @agent.tool_plain (bağlam olmadan) veya @agent.tool (RunContext ve dependency injection erişimi ile) dekoratörü kullanılarak 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-ваш-ключ",
    ),
)

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ı ayrıştırma (parsing) gibi kırılgan yöntemlere ihtiyaç duymadan güvenilir bir şekilde çağrılır. Tüm döngü (istek → tool çağrısı → nihai yanıt) Gonka üzerinden yaklaşık $0.00007 maliyetindeyken, OpenAI/Anthropic'te bu $0.04–0.22 civarındadır.

Hangi modeli seçmeli: MiniMaxAI/MiniMax-M2.7 – uzun diyaloglar ve dengeli görevler için, 8192'ye kadar çıktı. deepseek-ai/DeepSeek-V4-Flash-0731 – ağdaki en uzun bağlamlardan (380K) birine sahip ve ucuz büyük promptlar için, 32768'e kadar çıktı. zai-org/GLM-5.3-Flash – karmaşık akıl yürütme için reasoning-model ve ağdaki en uzun bağlam (390K), 8192'ye kadar çıktı; akıl yürütme işlemleri max_tokens'ın bir kısmını harcar, bu yüzden limiti yüksek tutun (600'den itibaren). Üçü de tek bir anahtarla hemen kullanılabilir; sadece model dizisi değişir. Benzer araçlar: Zincirleme işlemler ve RAG için LangChain, veri indeksleme için LlamaIndex.