PydanticAI + Gonka — 低成本的类型化 AI 代理

首先获取密钥：在 gate.joingonka.ai/register 注册——注册即赠送 3M 免费 tokens——然后在 Dashboard → API Keys 中创建 jg-xxx 密钥。

安装：

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

最小示例——通过 Gonka 运行的 agent。PydanticAI 通过 OpenAIProvider(base_url=..., api_key=...) 设置自定义 endpoint，再传给 OpenAIChatModel：

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)

就这样——你的 PydanticAI agent 通过 Gonka 去中心化网络运行，成本低到可以忽略不计。脚本用 run_sync 方法最方便；async 代码则用 await agent.run(...)。

模型参数：MiniMax M2.7 的上下文窗口为 180K tokens（180000），DeepSeek V4 Flash 为 380K，GLM-5.3 Flash 为 390K；通过 Gateway 的最大回答长度，MiniMax 和 GLM-5.3 Flash 最高 8192 tokens，DeepSeek 最高 32768。可以通过模型设置限制输出（OpenAIChatModelSettings(max_tokens=8192)）。可用模型：MiniMaxAI/MiniMax-M2.7、deepseek-ai/DeepSeek-V4-Flash-0731 和 zai-org/GLM-5.3-Flash——只需修改 OpenAIChatModel 第一个参数中的模型名称即可。

选择 PydanticAI 的首要理由是结构化输出（structured output）。你不用再拿正则去解析回答文本，而是把结果描述成一个 Pydantic 模型，传给 output_type 参数。框架会利用模型的 tool calling 强制其严格按 schema 返回数据，完成校验后，再通过 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(
    "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

之所以可行，是因为 Gonka 上的三款模型（MiniMax M2.7、DeepSeek V4 Flash 和 GLM-5.3 Flash）都支持原生 tool calling——PydanticAI 依靠它返回合法的 JSON 结构。最终你拿到的是带类型的 Python 对象，而不是需要手动解析的字符串。非常适合数据抽取、分类、表单填写，以及要求结果以严格格式继续在代码中流转的 RAG 流程。

PydanticAI 是一个用于连续运行的智能体和流水线的框架：它们提取数据、调用工具并处理请求流。在这里，token 成本决定了项目是仅仅维持在原型阶段还是能够投入生产环境。让我们比较一下典型的负载：

差距在数百到数千倍。对于原型开发，这意味着 3M 免费 token 足以进行最初的智能体运行测试。对于每天处理数十万请求的生产环境，节省的资金每月可达数万美元 — 代码依然是 PydanticAI，只需更改 base_url。

一个 jg-xxx 密钥和一个余额既适用于 OpenAI 格式 (/v1)，也适用于 Anthropic 格式 (/v1/messages) — 但对于 PydanticAI，使用上述 OpenAI 兼容端点就足够了。

PydanticAI 的第二大核心能力是工具（tools）。你可以用 @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(
    "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 的 tool calling 是原生的，工具调用十分可靠——无需对文本回答做脆弱的解析。整个流程（请求 → 工具调用 → 最终回答）通过 Gonka 只需约 $0.00007，而 OpenAI/Anthropic 为 $0.04–0.22。

该选哪款模型：MiniMaxAI/MiniMax-M2.7——适合长对话和均衡型任务，输出上限 8192。deepseek-ai/DeepSeek-V4-Flash-0731——网络中最长的上下文之一（380K），大 prompt 成本低廉，输出上限 32768。zai-org/GLM-5.3-Flash——面向复杂推理的 reasoning 模型，拥有网络中最长的上下文（390K），输出上限 8192；推理过程会消耗一部分 max_tokens，设置时请留出余量（从 600 起）。三款模型现在用一个密钥即可全部调用——只需更换模型字符串。同类工具还有：LangChain 用于链路和 RAG，LlamaIndex 用于数据索引。