PydanticAI + Gonka — Agentes de IA tipificados por alguns centavos

Primeiro, pegue sua chave: cadastre-se em gate.joingonka.ai/register — no cadastro damos 3M tokens grátis — e crie uma chave jg-xxx em Dashboard → API Keys.

Instalação:

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

Exemplo mínimo — um agente via Gonka. O PydanticAI define um endpoint customizado através de OpenAIProvider(base_url=..., api_key=...), que é passado para o 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)

É isso — seu agente PydanticAI roda pela rede descentralizada Gonka por muito pouco. O método run_sync é prático para scripts; para código async existe o await agent.run(...).

Parâmetros do modelo: a janela de contexto do MiniMax M2.7 é de 180K tokens (180000), a do DeepSeek V4 Flash é de 380K e a do GLM-5.3 Flash é de 390K; o comprimento máximo da resposta pelo Gateway é de até 8192 tokens no MiniMax e no GLM-5.3 Flash, e de até 32768 no DeepSeek. Você pode limitar a saída pelas configurações do modelo (OpenAIChatModelSettings(max_tokens=8192)). Estão disponíveis MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 e zai-org/GLM-5.3-Flash — basta trocar o nome do modelo no primeiro argumento do OpenAIChatModel.

O principal motivo para escolher o PydanticAI é o structured output. Em vez de fazer parsing do texto da resposta com regex, você descreve o resultado como um modelo Pydantic e o passa para o parâmetro output_type. O framework usa o tool calling do modelo para forçá-lo a devolver dados estritamente conforme o schema, valida tudo e entrega um objeto pronto através de 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

Isso funciona porque os três modelos da Gonka (MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash) suportam tool calling nativo — o PydanticAI se apoia nele para devolver uma estrutura JSON válida. No fim, você recebe um objeto Python tipado, e não uma string que precisa ser parseada na mão. Ideal para extração de dados, classificação, preenchimento de formulários e pipelines de RAG em que o resultado precisa seguir adiante no código em um formato estrito.

PydanticAI é um framework para agentes e pipelines que operam continuamente: extraem dados, chamam ferramentas e processam fluxos de solicitações. Aqui, o custo dos tokens decide se o projeto permanecerá um protótipo ou irá para production. Vamos comparar as cargas típicas:

A diferença é de centenas a milhares de vezes. Para um protótipo, isso significa que os 3M de tokens gratuitos são suficientes para as primeiras execuções do agente. Para produção, que processa centenas de milhares de solicitações por dia, a economia chega a dezenas de milhares de dólares por mês — com o mesmo código no PydanticAI, apenas com um base_url diferente.

Uma chave jg-xxx e um saldo funcionam tanto para o formato OpenAI (/v1) quanto para o formato Anthropic (/v1/messages) — mas para o PydanticAI, basta o endpoint compatível com OpenAI mostrado acima.

A segunda capacidade central do PydanticAI são as ferramentas. Você pode registrar uma função com o decorador @agent.tool_plain (sem contexto) ou @agent.tool (com acesso ao RunContext e injeção de dependências). O modelo decide sozinho quando chamar a ferramenta, recebe o resultado e continua o raciocínio:

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)

Como o tool calling da Gonka é nativo, as ferramentas são chamadas de forma confiável — sem o parsing frágil de respostas em texto. Todo o ciclo (requisição → chamada da tool → resposta final) custa cerca de $0.00007 via Gonka, contra $0.04–0.22 na OpenAI/Anthropic.

Qual modelo escolher: MiniMaxAI/MiniMax-M2.7 — para diálogos longos e tarefas equilibradas, saída de até 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — um dos contextos mais longos da rede (380K) e prompts grandes baratos, saída de até 32768. zai-org/GLM-5.3-Flash — modelo de reasoning para raciocínios complexos e o contexto mais longo da rede (390K), saída de até 8192; o raciocínio consome parte do max_tokens, então defina-o com folga (a partir de 600). Os três estão disponíveis agora mesmo com uma única chave — só muda a linha do modelo. Ferramentas de espírito parecido: LangChain para cadeias e RAG, LlamaIndex para indexar dados.