PydanticAI + Gonka — Agentes de IA tipados por centavos

Primero consigue tu clave: regístrate en gate.joingonka.ai/register — al registrarte te damos 3M tokens gratis — y crea una clave jg-xxx en Dashboard → API Keys.

Instalación:

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

Ejemplo mínimo — un agente a través de Gonka. PydanticAI define un endpoint personalizado mediante OpenAIProvider(base_url=..., api_key=...), que se pasa a 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)

Eso es todo: tu agente PydanticAI funciona a través de la red descentralizada Gonka por muy poco dinero. El método run_sync es cómodo para scripts; para código async existe await agent.run(...).

Parámetros del modelo: la ventana de contexto de MiniMax M2.7 es de 180K tokens (180000), la de DeepSeek V4 Flash es de 380K y la de GLM-5.3 Flash es de 390K; la longitud máxima de respuesta a través del Gateway es de hasta 8192 tokens en MiniMax y GLM-5.3 Flash, y de hasta 32768 en DeepSeek. Puedes limitar la salida con la configuración del modelo (OpenAIChatModelSettings(max_tokens=8192)). Están disponibles MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 y zai-org/GLM-5.3-Flash: basta con cambiar el nombre del modelo en el primer argumento de OpenAIChatModel.

La razón principal para elegir PydanticAI es el structured output. En lugar de parsear el texto de la respuesta con regex, describes el resultado como un modelo Pydantic y lo pasas al parámetro output_type. El framework usa el tool calling del modelo para obligarlo a devolver datos estrictamente según el esquema, los valida y entrega un objeto ya listo a travé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

Esto funciona porque los tres modelos de Gonka (MiniMax M2.7, DeepSeek V4 Flash y GLM-5.3 Flash) admiten tool calling nativo: PydanticAI se apoya en él para devolver una estructura JSON válida. Como resultado obtienes un objeto Python tipado, no una cadena que hay que parsear a mano. Ideal para extracción de datos, clasificación, relleno de formularios y pipelines de RAG donde el resultado debe seguir avanzando por el código en un formato estricto.

PydanticAI es un framework para agentes y pipelines que operan continuamente: extraen datos, llaman a herramientas y procesan flujos de solicitudes. Aquí, el costo de los tokens determina si el proyecto seguirá siendo un prototipo o llegará a production. Comparemos las cargas típicas:

La diferencia es de cientos y miles de veces. Para un prototipo, esto significa que los 3M de tokens gratis son suficientes para las primeras ejecuciones del agente. Para producción, que procesa cientos de miles de solicitudes al día, el ahorro asciende a decenas de miles de dólares al mes, manteniendo el mismo código en PydanticAI, simplemente con un base_url diferente.

Una clave jg-xxx y un saldo funcionan tanto para el formato OpenAI (/v1) como para el formato Anthropic (/v1/messages), pero para PydanticAI basta con el endpoint compatible con OpenAI que se mostró anteriormente.

La segunda capacidad clave de PydanticAI son las herramientas. Puedes registrar una función con el decorador @agent.tool_plain (sin contexto) o @agent.tool (con acceso a RunContext e inyección de dependencias). El modelo decide por sí mismo cuándo llamar a la herramienta, recibe el resultado y continúa razonando:

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 el tool calling de Gonka es nativo, las herramientas se invocan de forma fiable, sin el frágil parseo de respuestas de texto. Todo el ciclo (solicitud → llamada a la tool → respuesta final) cuesta alrededor de $0.00007 a través de Gonka frente a $0.04–0.22 en OpenAI/Anthropic.

Qué modelo elegir: MiniMaxAI/MiniMax-M2.7 — para diálogos largos y tareas equilibradas, salida de hasta 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — uno de los contextos más largos de la red (380K) y prompts grandes baratos, salida de hasta 32768. zai-org/GLM-5.3-Flash — modelo de reasoning para razonamientos complejos y el contexto más largo de la red (390K), salida de hasta 8192; el razonamiento consume parte de max_tokens, así que defínelo con margen (desde 600). Los tres están disponibles ahora mismo con una sola clave: solo cambia la línea del modelo. Herramientas de espíritu similar: LangChain para cadenas y RAG, LlamaIndex para indexar datos.