PydanticAI + Gonka — Agentes de IA tipificados por alguns centavos

Primeiro, obtenha uma chave: registre-se em gate.joingonka.ai/register — ao se registrar, oferecemos 10M 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]"

Um exemplo mínimo — um agente através do Gonka. O PydanticAI define um endpoint personalizado via 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 assíncrono, existe o await agent.run(...).

Parâmetros do modelo: a janela de contexto dos modelos da rede é de 200K tokens (200000), o comprimento máximo de resposta via Gateway é de até 8192 tokens. É possível 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 e MiniMaxAI/MiniMax-M2.7 (até 8192 tokens de saída cada) — basta alterar o nome do modelo no primeiro argumento do OpenAIChatModel.

O principal motivo para escolher o PydanticAI é o structured output. Em vez de analisar o texto da resposta com regEx, você descreve o resultado como um modelo Pydantic e o passa no parâmetro output_type. O framework usa a função de tool calling do modelo para forçá-lo a retornar dados estritamente conforme o esquema, valida-os e entrega um objeto pronto para uso através do 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 é backend-developer, sabe Python, Go e Postgres"
)
print(result.output)
# name='Ana' role='backend-developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — já é uma list[str], não texto

Isso funciona porque ambos os modelos Gonka (Kimi K2.6 e MiniMax M2.7) suportam tool calling nativo — o PydanticAI depende disso para retornar uma estrutura JSON válida. Como resultado, você obtém um objeto Python tipado, em vez de uma string que precise ser analisada manualmente. Ideal para extração de dados, classificação, preenchimento de formulários e RAG-pipelines, onde o resultado deve seguir no código em um formato estrito.

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

A diferença é de centenas e milhares de vezes. Para um protótipo, significa que os 10M de tokens gratuitos são suficientes para centenas de execuções do agente. Para a produção, que processa centenas de milhares de solicitações por dia, a economia é de 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 um endpoint compatível com a OpenAI, conforme mostrado acima.

A segunda funcionalidade chave do PydanticAI são as ferramentas. Uma função pode ser registrada usando o decorador @agent.tool_plain (sem contexto) ou @agent.tool (com acesso a RunContext e injeção de dependência). O próprio modelo decide 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 parsing frágil de respostas em texto. Todo o ciclo (solicitação → chamada de tool → resposta final) custa cerca de $0.00007 via 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 de até 8192 tokens. MiniMaxAI/MiniMax-M2.7 — para diálogos longos e tarefas equilibradas, saída de até 8192 tokens. Ambos estão disponíveis agora mesmo com uma única chave — basta alterar a string do modelo. Ferramentas que seguem a mesma linha: LangChain para cadeias e RAG, LlamaIndex para indexação de dados.