PydanticAI + Gonka — Agentes de IA tipados por centavos

Primero obtén una clave: regístrate en gate.joingonka.ai/register — al registrarte te damos 10M de tokens gratis — y crea 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]"

Un ejemplo mínimo: un agente a través de Gonka. PydanticAI configura 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-tu-clave",
    ),
)

agent = Agent(model)

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

Eso es todo; tu agente PydanticAI funciona mediante la red descentralizada Gonka por una fracción del costo. El método run_sync es práctico para scripts; para código asíncrono existe await agent.run(...).

Parámetros del modelo: la ventana de contexto de los modelos de la red es de 200K tokens (200000), la longitud máxima de respuesta a través de Gateway es de hasta 8192 tokens. Puedes limitar la salida mediante la configuración del modelo (OpenAIChatModelSettings(max_tokens=8192)). También están disponibles moonshotai/Kimi-K2.6 y MiniMaxAI/MiniMax-M2.7 (hasta 8192 tokens de salida cada uno) — 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 analizar el texto de respuesta con expresiones regulares, defines el resultado como un modelo Pydantic y lo pasas al parámetro output_type. El framework utiliza el tool calling del modelo, obligándolo a devolver datos estrictamente según 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 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 list[str], no texto

Esto funciona porque ambos modelos de Gonka (Kimi K2.6 y MiniMax M2.7) soportan tool calling nativo — PydanticAI se basa en ello para devolver una estructura JSON válida. Como resultado, obtienes un objeto Python tipado en lugar de una cadena de texto que tendrías que procesar manualmente. Es ideal para extracción de datos, clasificación, relleno de formularios y RAG-pipelines, donde el resultado debe seguir procesándose en el código con un formato estricto.

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

La diferencia es de cientos y miles de veces. Para un prototipo, significa que los 10M de tokens gratuitos alcanzan para cientos de ejecuciones del agente. Para producción, que procesa cientos de miles de solicitudes al día, el ahorro es de decenas de miles de dólares al mes, usando el mismo código de PydanticAI, simplemente configurando 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 mostrado arriba.

La segunda característica clave de PydanticAI son las herramientas. Una función se puede registrar utilizando 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 con OpenAI/Anthropic.

Qué modelo elegir: moonshotai/Kimi-K2.6 — potente en codificación y razonamientos complejos, salida de hasta 8192 tokens. MiniMaxAI/MiniMax-M2.7 — para diálogos largos y tareas equilibradas, salida de hasta 8192 tokens. Ambos 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.