PydanticAI + Gonka — 超低コストのタイプ付き AI エージェント

まず、キーを取得します。gate.joingonka.ai/register で登録してください。登録時に10M の無料トークンを提供します。Dashboard → API Keys で jg-xxx キーを作成します。

インストール:

pip install pydantic-ai
# または OpenAI の依存関係のみを使用する軽量版:
# pip install "pydantic-ai-slim[openai]"

最小限の例 — Gonka 経由のエージェント。PydanticAI は、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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-あなたのキー",
    ),
)

agent = Agent(model)

result = agent.run_sync("PoUW とは何ですか？2つの文で説明してください。")
print(result.output)

これで完了です — あなたの PydanticAI エージェントは Gonka の分散型ネットワークを介して超低コストで動作します。run_sync メソッドはスクリプトに便利です。非同期コードには await agent.run(...) があります。

モデルのパラメータ: Qwen3-235B のコンテキストウィンドウは 128K トークン (131072) で、Gateway 経由での最大出力長は 8192 トークンです。出力はモデル設定 (OpenAIChatModelSettings(max_tokens=8192)) を介して制限できます。moonshotai/Kimi-K2.6 (最大出力 3072 トークン) と MiniMaxAI/MiniMax-M2.7 (最大出力 4096) も利用可能です。OpenAIChatModel の最初の引数でモデル名を変更するだけで十分です。

PydanticAI を選択する主な理由は、構造化された出力です。応答テキストを正規表現で解析する代わりに、結果を Pydantic モデルとして記述し、output_type パラメータに渡します。フレームワークはモデルのツール呼び出し機能を利用して、モデルが厳密にスキーマに従ってデータを返すように強制し、それらを検証して、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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-あなたのキー",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "データを抽出してください: アンナはバックエンド開発者で、Python、Go、Postgres を知っています"
)
print(result.output)
# name='アンナ' role='バックエンド開発者' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — list[str] であり、テキストではありません

これは、Qwen3-235B (および他の 2 つの Gonka モデル) がネイティブなツール呼び出しをサポートしているため機能します。PydanticAI はこれを利用して有効な JSON 構造を返します。結果として、手動で解析する必要のある文字列ではなく、型付けされた Python オブジェクトが得られます。データ抽出、分類、フォーム入力、および厳密な形式で結果をコードに渡す必要がある RAG パイプラインに最適です。

PydanticAI は、データの抽出、ツールの呼び出し、リクエストストリームの処理など、継続的に動作するエージェントとパイプラインのためのフレームワークです。ここでは、トークンコストが、プロジェクトがプロトタイプで終わるか、本番環境に進むかを決定します。典型的なワークロードを比較してみましょう:

差は数百倍から数千倍です。プロトタイプにとっては、10M の無料トークンでエージェントを何百回も実行できることを意味します。1日あたり数十万のリクエストを処理する本番環境では、base_url を変更するだけで PydanticAI の同じコードで、月に数万ドルの節約になります。

1つのキー jg-xxx と1つの残高は、OpenAI 形式 (/v1) と Anthropic 形式 (/v1/messages) の両方で機能しますが、PydanticAI の場合は上記の OpenAI 互換エンドポイントで十分です。

PydanticAI の2つ目の主要な機能はツールです。関数は @agent.tool_plain デコレータ (コンテキストなし) または @agent.tool デコレータ (RunContext と依存性注入へのアクセスあり) で登録できます。モデルはツールを呼び出すタイミングを自分で決定し、結果を受け取り、推論を続行します。

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-あなたのキー",
    ),
)

agent = Agent(
    model,
    instructions="あなたはアシスタントです。必要なときにツールを使用してください。",
)


@agent.tool_plain
def roll_dice() -> str:
    """6面サイコロを振り、結果を返します。"""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """数式を計算します。"""
    return str(eval(expression))


result = agent.run_sync("サイコロを振って、結果に7を掛けてください")
print(result.output)

Gonka のツール呼び出しはネイティブであるため、脆弱なテキスト応答解析なしでツールが確実に呼び出されます。Gonka を介したサイクル全体 (要求 → ツール呼び出し → 最終応答) のコストは約 $0.00001 で、OpenAI/Anthropic の $0.04～0.22 と比較すると非常に安価です。

どのモデルを選択するか: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 はデフォルトで、品質と最大出力制限 (8192) のバランスが最も優れています。moonshotai/Kimi-K2.6 はコーディングと複雑な推論に優れています (出力は最大 3072)。MiniMaxAI/MiniMax-M2.7 は長い対話に役立ちます (出力は最大 4096)。これら3つはすべて、1つのキーで現在利用可能で、モデル文字列を変更するだけで利用できます。同様のツールについては、チェーンと RAG 用の LangChain、データインデックス作成用の LlamaIndex も参照してください。