PydanticAI + Gonka — Agentes de IA tipificados por alguns centavos

Primeiro, obtenha uma chave: cadastre-se em gate.joingonka.ai/register — ao se cadastrar, oferecemos 1.5M 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 OpenAI:
# pip install "pydantic-ai-slim[openai]"

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

agent = Agent(model)

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

Isso é tudo — seu agente PydanticAI funciona através da rede descentralizada Gonka por uma fração do custo. O método run_sync é conveniente para scripts; para código async, existe await agent.run(...).

Parâmetros do modelo: a janela de contexto dos modelos da rede é de 200K tokens (200000), no DeepSeek V4 Flash é de 380K; o tamanho máximo de resposta via Gateway é de até 8192 tokens, no DeepSeek é de até 32768. Você pode limitar a saída através das configurações do modelo (OpenAIChatModelSettings(max_tokens=8192)). Também estão disponíveis moonshotai/Kimi-K2.6, MiniMaxAI/MiniMax-M2.7 e deepseek-ai/DeepSeek-V4-Flash-0731 — 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 usa o tool calling do modelo para forçá-lo a retornar dados estritamente conforme o esquema, valida-os 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-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: Anna é backend-developer, sabe Python, Go e Postgres"
)
print(result.output)
# name='Anna' role='backend-developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — já é list[str], não texto

Isso funciona porque os três modelos Gonka (Kimi K2.6, MiniMax M2.7 e DeepSeek V4 Flash) suportam tool calling nativo — o PydanticAI baseia-se nisso para retornar uma estrutura JSON válida. Como resultado, você obtém um objeto Python tipado, 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 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 1.5M 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 chave 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 ao RunContext e dependency injection). O modelo decide por si mesmo quando chamar a ferramenta, obtém 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:
    """Lança um dado de seis faces 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("Lança um dado e multiplica 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 parsing frágil 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: moonshotai/Kimi-K2.6 — forte em codificação e raciocínios complexos, saída até 8192. MiniMaxAI/MiniMax-M2.7 — para diálogos longos e tarefas equilibradas, saída até 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — o maior contexto da rede (380K) e prompts grandes baratos, saída até 32768. Todos os três estão disponíveis agora com uma única chave — apenas a string do modelo muda. Ferramentas com espírito semelhante: LangChain para cadeias e RAG, LlamaIndex para indexação de dados.