PydanticAI + Gonka — Agentes de IA tipados por centavos

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

Instalación:

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

Un ejemplo minimalista: un agente a través de Gonka. PydanticAI establece un endpoint personalizado a través de 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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 centavos. El método run_sync es conveniente para scripts; para código asíncrono, existe await agent.run(...).

Parámetros del modelo: La ventana de contexto de Qwen3-235B es de 128K tokens (131072), la longitud máxima de respuesta a través de Gateway es de hasta 8192 tokens. Puede limitar la salida a través de la configuración del modelo (OpenAIChatModelSettings(max_tokens=8192)). También están disponibles moonshotai/Kimi-K2.6 (hasta 3072 tokens de salida) y MiniMaxAI/MiniMax-M2.7 (hasta 4096), simplemente cambie el nombre del modelo en el primer argumento de OpenAIChatModel.

La principal razón para elegir PydanticAI es la salida estructurada. En lugar de analizar el texto de la respuesta con expresiones regulares, usted describe el resultado como un modelo Pydantic y lo pasa al parámetro output_type. El framework utiliza la llamada a herramientas del modelo para forzarlo a devolver los datos estrictamente según el esquema, los valida y le devuelve el 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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: Anna es una desarrolladora backend, sabe Python, Go y Postgres"
)
print(result.output)
# name='Anna' role='desarrolladora backend' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — ya es list[str], no texto

Esto funciona porque Qwen3-235B (y los otros dos modelos de Gonka) admiten llamadas nativas a herramientas; PydanticAI se basa en esto para devolver una estructura JSON válida. Como resultado, obtienes un objeto Python tipado, no una cadena que necesitas analizar manualmente. Ideal para la extracción de datos, clasificación, llenado de formularios y pipelines RAG donde el resultado debe pasar al código en un formato estricto.

PydanticAI es un framework para agentes y pipelines que funcionan continuamente: extraen datos, llaman a herramientas, procesan flujos de solicitudes. Aquí, el costo de los tokens decide si un proyecto sigue siendo un prototipo o pasa a producción. Comparemos las cargas típicas:

La diferencia es de cientos o miles de veces. Para un prototipo, esto significa que 10M de tokens gratuitos son suficientes para cientos de ejecuciones de agentes. Para la producción, que procesa cientos de miles de solicitudes al día, el ahorro asciende a decenas de miles de dólares al mes, con el mismo código en PydanticAI, simplemente con una base_url diferente.

Una única clave jg-xxx y un mismo saldo funcionan tanto para el formato OpenAI (/v1) como para el formato Anthropic (/v1/messages), pero para PydanticAI basta con un endpoint compatible con OpenAI, como se muestra arriba.

La segunda capacidad clave de PydanticAI son las herramientas. Una función puede registrarse con el decorador @agent.tool_plain (sin contexto) o @agent.tool (con acceso a RunContext e inyección de dependencias). El modelo decide cuándo llamar a la herramienta, obtiene 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-tu-clave",
    ),
)

agent = Agent(
    model,
    instructions="Eres un asistente. Utiliza 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 un dado y multiplica el resultado por 7")
print(result.output)

Dado que la llamada a la herramienta en Gonka es nativa, las herramientas se invocan de forma fiable, sin el frágil análisis de las respuestas de texto. Todo el ciclo (solicitud → llamada a la herramienta → respuesta final) cuesta alrededor de $0.00001 a través de Gonka en comparación con $0.04-0.22 con OpenAI/Anthropic.

Qué modelo elegir: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 es el predeterminado, el mejor equilibrio entre calidad y el límite de salida más grande (8192). moonshotai/Kimi-K2.6 es fuerte en codificación y razonamiento complejo (salida de hasta 3072). MiniMaxAI/MiniMax-M2.7 es para diálogos largos (salida de hasta 4096). Los tres están disponibles ahora mismo con una sola clave; solo cambia la cadena del modelo. Herramientas similares incluyen: LangChain para cadenas y RAG, LlamaIndex para indexación de datos.