PydanticAI + Gonka — Agentes de IA tipificados por alguns centavos

Primeiro, obtenha uma chave: registre-se em gate.joingonka.ai/register — ao se registrar, oferecemos 3M de tokens gratuitos — e crie uma chave jg-xxx em Dashboard → API Keys.

Instalação:

pip install pydantic-ai
# ou a versão leve apenas com dependências do OpenAI:
# pip install "pydantic-ai-slim[openai]"

Exemplo mínimo — um agente via Gonka. O PydanticAI define um endpoint personalizado através do 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-sua-chave",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explique em duas frases o que é PoUW")
print(result.output)

É isso — seu agente PydanticAI funciona através da rede descentralizada Gonka por centavos. 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 200K tokens (200000), no DeepSeek V4 Flash é de 380K, e no GLM-5.3 Flash é de 390K; a duração máxima da resposta através do Gateway é de até 8192 tokens para MiniMax e GLM-5.3 Flash, até 32768 para DeepSeek. Você pode limitar a saída através das 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 alterar o nome do modelo no primeiro argumento do OpenAIChatModel.

A principal razão para escolher o PydanticAI é o structured output. Em vez de analisar o texto da resposta com expressões regulares, você descreve o resultado como um modelo Pydantic e o passa para o parâmetro output_type. O framework utiliza o tool calling do modelo para forçá-lo a retornar dados seguindo estritamente o esquema, valida-os e entrega um objeto pronto para uso 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-sua-chave",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extraia os dados: Ana é desenvolvedora backend, sabe Python, Go e Postgres"
)
print(result.output)
# name='Ana' role='desenvolvedora backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — já é uma lista, não texto

Isso funciona porque todos os três modelos da Gonka (MiniMax M2.7, DeepSeek V4 Flash e GLM-5.3 Flash) suportam tool calling nativo — o PydanticAI se baseia nisso para retornar uma estrutura JSON válida. Como resultado, você obtém um objeto Python tipado, e não uma string que precisa ser analisada manualmente. Ideal para extração de dados, classificação, preenchimento de formulários e pipelines de RAG, onde o resultado deve continuar sendo processado no código com 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 funcionalidade principal do PydanticAI são as ferramentas. Uma função pode ser registrada com o decorador @agent.tool_plain (sem contexto) ou @agent.tool (com acesso a RunContext e injeção de dependência). O modelo decide por si só 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-sua-chave",
    ),
)

agent = Agent(
    model,
    instructions="Você é um assistente. Use ferramentas quando necessário.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Joga um dado de seis lados e retorna o resultado."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Calcula uma expressão matemática."""
    return str(eval(expression))


result = agent.run_sync("Jogue o dado e multiplique o resultado por 7")
print(result.output)

Como o tool calling no Gonka é nativo, as ferramentas são invocadas de forma confiável — sem o frágil parsing de respostas de texto. Todo o ciclo (solicitação → chamada de tool → resposta final) custa cerca de $0.00007 através do 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 até 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — um dos contextos mais longos da rede (380K) e grandes prompts baratos, saída até 32768. zai-org/GLM-5.3-Flash — modelo de raciocínio para deduções complexas e o maior contexto da rede (390K), saída até 8192; o raciocínio consome parte do max_tokens, configure com folga (a partir de 600). Todos os três estão disponíveis agora com uma única chave — apenas a string do modelo muda. Ferramentas similares: LangChain para cadeias e RAG, LlamaIndex para indexação de dados.