PydanticAI + Gonka — Agentes de IA tipificados por alguns centavos

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

Instalação:

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

Exemplo mínimo — agente via Gonka. PydanticAI define um endpoint personalizado via OpenAIProvider(base_url=..., api_key=...), que é passado para OpenAIChatModel:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 alguns centavos. O método run_sync é conveniente para scripts; para código assíncrono, há await agent.run(...).

Parâmetros do modelo: a janela de contexto do Qwen3-235B é de 128K tokens (131072), o comprimento máximo de resposta via Gateway é de até 8192 tokens. A saída pode ser limitada através das configurações do modelo (OpenAIChatModelSettings(max_tokens=8192)). Também estão disponíveis moonshotai/Kimi-K2.6 (até 3072 tokens de saída) e MiniMaxAI/MiniMax-M2.7 (até 4096) — basta alterar o nome do modelo no primeiro argumento de OpenAIChatModel.

A principal razão para escolher o PydanticAI é a saída estruturada. 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 a função de chamada de modelo para forçá-lo a retornar os dados estritamente de acordo com o esquema, os valida e retorna o 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 é uma desenvolvedora backend, conhece Python, Go e Postgres"
)
print(result.output)
# name='Anna' role='desenvolvedora backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — já é list[str], não texto

Isso funciona porque o Qwen3-235B (e os outros dois modelos Gonka) suportam tool calling nativo — o PydanticAI se baseia nele para retornar uma estrutura JSON válida. Como resultado, você obtém um objeto Python tipificado, e não uma string que precisa ser analisada manualmente. Ideal para extração de dados, classificação, preenchimento de formulários e pipelines RAG, onde o resultado precisa seguir um formato rigoroso no código.

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

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

Uma única chave jg-xxx e um único saldo funcionam para o formato OpenAI (/v1) e para o formato Anthropic (/v1/messages) — mas para PydanticAI, um endpoint compatível com OpenAI, mostrado acima, é suficiente.

A segunda capacidade 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 a RunContext e injeção de dependência). O modelo decide 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 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("Lance o dado e multiplique o resultado por 7")
print(result.output)

Como o tool calling da Gonka é nativo, as ferramentas são chamadas de forma confiável — sem a análise frágil de respostas de texto. Todo o ciclo (solicitação → chamada da ferramenta → resposta final) custa cerca de US$ 0,00001 via Gonka contra US$ 0,04–0,22 na OpenAI/Anthropic.

Qual modelo escolher: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — padrão, melhor equilíbrio de qualidade e maior limite de saída (8192). moonshotai/Kimi-K2.6 é forte em codificação e raciocínio complexo (saída até 3072). MiniMaxAI/MiniMax-M2.7 — para diálogos longos (saída até 4096). Todos os três estão disponíveis agora com uma única chave — apenas o nome do modelo muda. Ferramentas semelhantes: LangChain para cadeias e RAG, LlamaIndex para indexação de dados.