Nivel 20 · Uso de herramientas

Hasta ahora el modelo solo escribía texto. En este nivel aprenderás a darle herramientas: funciones de tu código que el modelo puede pedir que ejecutes, como consultar un pedido, buscar en una base de datos o enviar un correo. Es la pieza que permite a un modelo actuar sobre el mundo y la base directa de los agentes del nivel 40.

Para quién es

• Has terminado el nivel 10 o ya sabes escribir prompts con formato validado.
• Quieres conectar un modelo a tus APIs o datos internos.
• Has oído hablar de function calling o de MCP y quieres entender cómo funcionan por dentro.

Qué vas a saber hacer

Al terminar sabrás implementar el ciclo completo de tool use, definir herramientas que el modelo usa bien, devolver errores de forma que el modelo se recupere, controlar cuándo y cuáles usa con tool_choice, y empaquetar tus herramientas en un servidor MCP que puedes conectar a tu propio código o a aplicaciones como Claude Desktop.

Lecciones

1. Function calling: el ciclo tool_use → tool_result. El protocolo: el modelo pide, tu código ejecuta, le devuelves el resultado. Con un bucle completo en Python y TypeScript.
2. Definir herramientas con JSON Schema. Nombres, descripciones y JSON Schema: lo que decide si el modelo elige bien la herramienta y le pasa bien los argumentos.
3. Manejo de errores e is_error. Qué hacer cuando la herramienta falla, cuándo marcar is_error y cómo evitar bucles infinitos.
4. Controlar la elección con tool_choice. Dejar decidir al modelo, obligarle a usar una herramienta concreta o prohibírselo, y cuándo conviene cada opción.
5. MCP: conectar un servidor de herramientas. Escribir un servidor MCP con MCPServer, probarlo y conectarlo a tu aplicación.

El proyecto del nivel

Construirás un asistente de pedidos para una tienda ficticia. Los datos pueden vivir en un diccionario o en un SQLite pequeño; lo importante es el protocolo.

Está terminado si cumple todo esto:

• servidor_tienda.py expone con MCPServer tres herramientas: buscar_pedido(id_pedido), pedidos_de_cliente(email) y solicitar_devolucion(id_pedido, motivo).
• Cada herramienta tiene docstring con qué hace, cuándo usarla y qué devuelve, y tipos en todos los parámetros.
• solicitar_devolucion rechaza pedidos inexistentes o fuera de plazo con un error claro.
• cliente.py lanza el servidor por stdio, convierte sus herramientas al formato de la API y ejecuta el bucle hasta end_turn, con un máximo de 10 pasos.
• Cada tool_use recibe exactamente un tool_result, con is_error cuando corresponde.
• trazas.txt muestra las tres conversaciones pedidas, con cada llamada a herramienta y su resultado.

Después de este nivel

Sigue con Nivel 30 · Contexto, memoria y RAG para darle al modelo acceso a tus documentos, o salta a Nivel 40 · Tu primer agente si quieres convertir este bucle en un agente. Como referencia rápida tienes Uso de herramientas y MCP.