PydanticAI + Gonka — Agentes de IA tipados por centavos

Primero, obtenga una clave: regístrese en gate.joingonka.ai/register — al registrarse le regalamos 3M de tokens gratuitos — y cree una clave jg-xxx en Dashboard → API Keys.

Instalación:

pip install pydantic-ai
# o la versión ligera solo con dependencias de OpenAI:
# pip install "pydantic-ai-slim[openai]"

Ejemplo mínimo: un agente a través de Gonka. PydanticAI establece un endpoint personalizado mediante OpenAIProvider(base_url=..., api_key=...), que se transmite 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-tu-clave",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explica en dos frases qué es PoUW")
print(result.output)

Eso es todo: su agente PydanticAI funciona a través de la red descentralizada Gonka por unos céntimos. 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 200K tokens (200000), en DeepSeek V4 Flash es de 380K, y en GLM-5.3 Flash es de 390K; la longitud máxima de respuesta a través de Gateway es de hasta 8192 tokens para MiniMax y GLM-5.3 Flash, hasta 32768 para DeepSeek. Puede limitar la salida a través de 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 structured output. En lugar de parsear el texto de respuesta con expresiones regulares, usted describe el resultado como un modelo de Pydantic y lo pasa al parámetro output_type. El framework utiliza el tool calling del modelo para forzarlo a devolver datos siguiendo estrictamente el esquema, los valida y entrega un objeto listo para usar 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-tu-clave",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extrae los datos: Ana es desarrolladora backend, sabe Python, Go y Postgres"
)
print(result.output)
# name='Ana' role='desarrolladora backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — ya es una lista, no texto

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, obtiene un objeto de Python tipado, no una cadena de texto que debe analizar manualmente. Ideal para extracción de datos, clasificación, llenado de formularios y pipelines de RAG, donde el resultado debe continuar procesándose en el código con 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 característica clave de PydanticAI son las herramientas. Una función se puede registrar 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 el razonamiento:

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-tu-clave",
    ),
)

agent = Agent(
    model,
    instructions="Eres un asistente. Usa herramientas cuando sea necesario.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Lanza un dado de seis caras y devuelve el resultado."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Calcula una expresión matemática."""
    return str(eval(expression))


result = agent.run_sync("Lanza el dado y multiplica el resultado por 7")
print(result.output)

Como el tool calling en Gonka es nativo, las herramientas se invocan de forma fiable, sin el frágil análisis de respuestas de texto. Todo el ciclo (solicitud → llamada a 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 económicos, salida de hasta 32768. zai-org/GLM-5.3-Flash — modelo de razonamiento para deducciones complejas y el contexto más largo de la red (390K), salida de hasta 8192; el razonamiento consume parte de max_tokens, configúralo con margen (desde 600). Los tres están disponibles ahora mismo con una sola clave: solo cambia la cadena del modelo. Herramientas similares: LangChain para cadenas y RAG, LlamaIndex para indexación de datos.