Agente de código con Kimi K3: tools y tareas de largo alcance

Lo primero en el posicionamiento oficial de Kimi K3 es la «programación de largo alcance»: una ventana de contexto de 1M cabe un repositorio entero, el razonamiento siempre activo sostiene la planificación en varios pasos y la llamada a herramientas nativa controla la terminal y funciones externas. Eso lo hace ideal para un agente de código: lee el código por su cuenta, invoca herramientas y encadena una larga serie de acciones para terminar la tarea solo. Este artículo explica cómo montar un agente con el tool calling de K3, y la trampa que más cuesta en las tareas de largo alcance.

Fundamentos de la llamada a funciones (function calling)

K3 es compatible con la especificación tools de OpenAI. Define una herramienta y deja que el modelo decida cuándo llamarla:

import os, json
from openai import OpenAI

client = OpenAI(api_key=os.environ["MOONSHOT_API_KEY"],
                base_url="https://api.moonshot.cn/v1")

tools = [{
    "type": "function",
    "function": {
        "name": "read_file",
        "description": "Leer el contenido de un archivo del repositorio",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
}]

messages = [{"role": "user", "content": "Revisa si auth.py tiene claves hardcodeadas"}]

resp = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools,
)

Cuando el modelo decide llamar a una herramienta, el mensaje assistant devuelto trae tool_calls. Ejecutas la función correspondiente en local, devuelves el resultado como un mensaje role:"tool" y solicitas la siguiente ronda.

El fallo clave: en multironda, devuelve el mensaje assistant completo sin modificar

Aquí es donde más tropiezan quienes migran desde K2: en las conversaciones multironda y en las llamadas a herramientas, añade a la siguiente petición el mensaje assistant completo que devolvió la API, sin modificar; no conserves solo el content.

Con el razonamiento siempre activo de K3, el mensaje assistant lleva, además de content, el estado de razonamiento / herramientas. Devolver solo content le provoca «amnesia» al modelo: la cadena de razonamiento se rompe y las llamadas a herramientas se descuadran. La forma correcta:

# Añade el mensaje assistant entero (con tool_calls / estado de razonamiento) sin modificar
messages.append(resp.choices[0].message)

# Ejecuta las herramientas y devuelve los resultados como mensajes tool
for call in resp.choices[0].message.tool_calls or []:
    result = run_tool(call.function.name, json.loads(call.function.arguments))
    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": json.dumps(result),
    })

# Solicita la siguiente ronda con el historial completo
resp = client.chat.completions.create(
    model="kimi-k3", messages=messages, tools=tools,
)

Recuerda: añade el objeto de mensaje completo, no armes tú mismo uno nuevo solo con content.

Forzar llamadas y cargar herramientas dinámicamente

• Forzar llamadas: para que el modelo use una herramienta en esta ronda, pon tool_choice="required" (o indica una función concreta) — ideal para flujos de «consulta antes de responder».
• Carga dinámica de herramientas: cuando tienes muchas herramientas, puedes poner sus definiciones en un mensaje system y ofrecerlas según haga falta, en lugar de llenar el array tools en cada ronda — ahorra contexto y da más flexibilidad.
• Herramientas oficiales: Moonshot AI también ofrece un conjunto de capacidades de herramientas integradas, accesibles por endpoints oficiales como /tools y /fibers; para los detalles, sigue la documentación oficial.

Por qué las tareas de largo alcance encajan con K3

Un agente de código que corre muchas rondas acumula cada vez más contexto: el contenido del repo + ronda tras ronda de resultados de herramientas + el historial de razonamiento. Dos rasgos de K3 recogen justo esto:

• El contexto de 1M cabe el repo entero más un historial largo, así que nunca pierdes contexto a mitad de la ejecución por desbordar la ventana (para organizar contexto largo, mira la guía de contexto 1M);
• El caché por defecto hace que el prefijo invariable (repo, system, definiciones de herramientas) acierte una y otra vez, bajando el coste de entrada de un agente de largo alcance a ¥2/M — de lo contrario, reenviar el prefijo en cada ronda sale caro (echa cuentas en el desglose de precios de K3).

Por eso, al organizar los mensajes, pon el contenido del repo y las definiciones de herramientas lo más al frente posible y mantenlos estables para exprimir el caché; en cada ronda solo añade al final lo que cambia.

Refactor de todo el repositorio en la práctica

Un bucle típico de agente para un «refactor de todo el repositorio»:

1. Dale el panorama completo: mete de una vez en el contexto el repo (o las partes relevantes recuperadas por RAG) + las instrucciones system;
2. Deja que planifique: primero haz que K3 emita un plan de refactor (qué archivos cambiar, los puntos de riesgo) — aquí el razonamiento siempre activo rinde al máximo;
3. Ejecuta con herramientas: abre read_file / write_file / run_tests y déjalo editar y correr las pruebas paso a paso;
4. Devuelve sin modificar: en cada ronda devuelve el mensaje assistant completo + los resultados tool para mantener intacta la cadena de razonamiento;
5. Revisión final: haz que se autorrevise contra el plan inicial en busca de cambios olvidados y una batería de pruebas totalmente en verde.

Este flujo también puedes montarlo directamente sobre una pasarela agregadora: dejas la planificación a K3 y derivas ciertas subtareas a modelos como Claude Opus (comparativa en K3 vs Claude vs GPT), todo bajo una sola clave.

Conclusión

La táctica central de un agente de código con K3 se reduce a tres cosas: impulsa las acciones con tools, recorta el coste con caché + carga al frente, y en multironda devuelve el mensaje assistant completo sin modificar. Acierta en estos tres puntos y las tareas de largo alcance corren de forma estable. Para la integración completa y la resolución de errores, mira el tutorial de la API de Kimi K3. Para repartir libremente entre K3 y otros modelos bajo una sola clave, empieza por el panel de GetModel.