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

Önce anahtarınızı alın: gate.joingonka.ai/register adresine kaydolun - kayıtta 10M ücretsiz token veriyoruz - ve Kontrol Paneli → API Anahtarları bölümünde jg-xxx anahtarını oluşturun.

Kurulum:

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

Minimum örnek - Gonka aracılığıyla bir ajan. PydanticAI, OpenAIChatModel'e iletilen OpenAIProvider(base_url=..., api_key=...) aracılığıyla özel bir uç nokta belirler:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-anahtarınız",
    ),
)

agent = Agent(model)

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

Hepsi bu kadar - PydanticAI aracınız merkeziyetsiz Gonka ağı aracılığıyla kuruşa çalışıyor. run_sync yöntemi betikler için uygundur; asenkron kod için await agent.run(...) vardır.

Model parametreleri: Qwen3-235B'nin bağlam penceresi - 128K token (131072), Gateway aracılığıyla maksimum yanıt uzunluğu - 8192 tokene kadar. Çıktıyı model ayarları aracılığıyla sınırlayabilirsiniz (OpenAIChatModelSettings(max_tokens=8192)). Ayrıca moonshotai/Kimi-K2.6 (3072 tokene kadar çıktı) ve MiniMaxAI/MiniMax-M2.7 (4096'ya kadar) de mevcuttur - sadece OpenAIChatModel'in ilk argümanındaki model adını değiştirin.

PydanticAI'yi seçmenin ana nedeni yapılandırılmış çıktı'dır. Yanıt metnini düzenli ifadelerle ayrıştırmak yerine, sonucu bir Pydantic modeli olarak tanımlarsınız ve bunu output_type parametresine iletirsiniz. Çerçeve, modelin verileri kesinlikle şemaya uygun olarak döndürmesini sağlamak için modelin araç çağrısını kullanır, bunları doğrular ve sonuçta hazır bir nesneyi result.output aracılığıyla verir.

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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 ayıklayın: Anna bir backend geliştiricisidir, Python, Go ve Postgres biliyor"
)
print(result.output)
# name='Anna' role='backend-geliştirici' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — zaten list[str], metin değil

Bu işe yarar çünkü Qwen3-235B (ve diğer iki Gonka modeli) yerel araç çağrısını destekler - PydanticAI, geçerli bir JSON yapısı döndürmek için buna dayanır. Çıktıda, manuel olarak ayrıştırmanız gereken bir dize değil, tip güvenli bir Python nesnesi alırsınız. Veri çıkarma, sınıflandırma, form doldurma ve sonucun sıkı bir formatta kod boyunca devam etmesi gereken RAG ardışık düzenleri için idealdir.

PydanticAI, sürekli çalışan ajanlar ve ardışık düzenler için bir çerçevedir: verileri ayıklar, araçları çağırır, istek akışlarını işler. Burada token maliyeti, projenin bir prototip olarak kalıp kalmayacağını veya üretime geçip geçmeyeceğini belirler. Tipik yükleri karşılaştıralım:

Fark yüzlerce ve binlerce kat. Bir prototip için bu, 10M ücretsiz tokenin yüzlerce ajan çalıştırması için yeterli olduğu anlamına gelir. Günde yüz binlerce isteği işleyen bir üretim için, ayda on binlerce dolarlık bir tasarruf - aynı PydanticAI koduyla, sadece farklı bir base_url ile.

Tek bir jg-xxx anahtarı ve tek 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 uç nokta yeterlidir.

PydanticAI'nin ikinci temel özelliği araçlardır. Bir fonksiyon @agent.tool_plain (bağlam olmadan) veya @agent.tool (RunContext ve bağımlılık enjeksiyonuna erişimle) 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-anahtarınız",
    ),
)

agent = Agent(
    model,
    instructions="Sen bir asistantsı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:
    """Bir matematiksel ifadeyi hesaplar."""
    return str(eval(expression))


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

Gonka'da araç çağırma yerel olduğu için, araçlar güvenilir bir şekilde çağrılır - metin yanıtlarının kırılgan ayrıştırması olmadan. Tüm döngü (istek → araç çağrısı → nihai yanıt) Gonka aracılığıyla yaklaşık 0,00001 dolara mal olurken, OpenAI/Anthropic aracılığıyla 0,04-0,22 dolara mal olur.

Hangi modeli seçmeli: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 - Varsayılan, kalite ve en büyük çıktı limiti (8192) arasında en iyi denge. moonshotai/Kimi-K2.6 kodlamada ve karmaşık akıl yürütmede güçlüdür (3072'ye kadar çıktı). MiniMaxAI/MiniMax-M2.7 - uzun diyaloglar için (4096'ya kadar çıktı). Üçü de tek bir anahtarla hemen kullanılabilir - sadece model dizesi değişir. Benzer ruhlu araçlar: zincirler ve RAG için LangChain, veri indeksleme için LlamaIndex.