Invocación de herramientas en Agent: haz que la IA llame APIs y servicios externos

¿Te ha pasado? Quieres que la IA consulte el tiempo, lea un archivo o llame una API y responde «no puedo acceder a datos externos».

No es falta de inteligencia: le falta invocación de herramientas. Hoy hablamos de la tecnología que pasa la IA de «solo charlar» a «hacer el trabajo».

¿Qué es la invocación de herramientas en IA?

En pocas palabras: le das «manos» a la IA.

Los LLM clásicos solo responden con datos de entrenamiento. Preguntas por el tiempo en Pekín y dicen que no tienen datos en vivo. Con herramientas, la IA puede invocar funciones (p. ej. API del tiempo) y devolverte el resultado.

Es el salto de «estratega en papel» a «general que ejecuta en el campo».

Tres enfoques principales

OpenAI Function Calling para lo simple; Claude Tool Use para agentes complejos; MCP si quieres ecosistema.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

OpenAI Function Calling

Tres pasos:

1. Definir herramientas
2. La IA elige cuál invocar (nombre + parámetros)
3. Ejecutas y devuelves el resultado

Ejemplo completo

Herramienta de clima:

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Obtiene el clima actual de una ciudad",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Nombre de ciudad, p. ej. 'Pekín', 'Shanghái'"
                },
                "unit": {
                    "type": "string",
                    "enum": ["celsius", "fahrenheit"],
                    "description": "Unidad de temperatura, celsius por defecto"
                }
            },
            "required": ["city"]
        }
    }
}]

El description importa: la IA decide cuándo usar la herramienta según él. «Obtener clima» vs «Obtiene el clima actual de una ciudad» puede pasar de 60% a 95% de acierto.

Petición:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "¿Hace calor hoy en Pekín?"}
    ],
    tools=tools
)

La IA devuelve la invocación:

tool_call = response.choices[0].message.tool_calls[0]
# tool_call.function.name = "get_weather"
# tool_call.function.arguments = '{"city": "Pekín"}'

Ejecutas y devuelves:

weather_result = get_weather_from_api("Pekín")

final_response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "¿Hace calor hoy en Pekín?"},
        response.choices[0].message,
        {
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(weather_result)
        }
    ]
)

Respuesta natural: «Pekín hoy 28 °C, hace calor; usa protección solar.»

Strict Mode

OpenAI (2024) estabiliza el match con JSON Schema:

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "strict": True,
        # ... resto de campos
    }
}]

Parámetros 100% conformes al Schema. Actívalo en producción.

Claude Tool Use

Diferencias de diseño respecto a OpenAI.

Llamadas paralelas

Claude puede devolver varias invocaciones a la vez. «Compara el clima de Pekín y Shanghái» → dos get_weather:

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=[{"role": "user", "content": "Compara el clima de Pekín y Shanghái"}],
    tools=tools
)

for block in response.content:
    if block.type == "tool_use":
        print(f"Invocar {block.name}, args: {block.input}")

Claude distingue qué puede ir en paralelo y qué en serie.

Tool Choice

tool_choice = {"type": "auto"}      # por defecto
tool_choice = {"type": "any"}       # obliga a usar herramienta
tool_choice = {"type": "tool", "name": "get_weather"}  # herramienta concreta

Usa any cuando la respuesta exige herramienta (p. ej. estado de pedido en BD).

Manejo de errores

tool_result = {
    "type": "tool_result",
    "tool_use_id": tool_use.id,
    "content": "Fallo API: timeout de conexión",
    "is_error": True
}

La IA intenta alternativas o avisa al usuario sin stack traces.

MCP: estandarización futura

¿Por qué MCP?

Ecosistema fragmentado: GitHub para Claude, Slack para ChatGPT, cada uno por separado. MCP unifica: escribe una vez, usa en todas partes.

MCP Client (Claude Code / Claude Desktop)
        ↕
    MCP Server (proveedor de herramientas)
        ↕
   Herramienta / API externa

MCP en Claude Code

claude mcp add my-server --transport sse --url https://api.example.com/mcp
claude mcp add local-tool --command node ./my-tool.js

Tras configurar, Claude descubre herramientas automáticamente. Preguntas por open issues y las lista sin que notes la invocación.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Producción: trampas habituales

Seguridad

1. Permisos por niveles — solo lo necesario; sensibles con confirmación
2. Validación de entrada — no pases parámetros de la IA directo a la API
3. Auditoría — registra parámetros y resultados

Caso real: la IA pasó entrada maliciosa a una consulta SQL → inyección indirecta.

Timeout y reintentos

async def call_tool_with_retry(tool_func, args, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await asyncio.wait_for(
                tool_func(**args),
                timeout=10.0
            )
        except asyncio.TimeoutError:
            if attempt == max_retries - 1:
                return {"error": "Timeout en invocación de herramienta"}
            await asyncio.sleep(1)

Costo en tokens

Definiciones y resultados consumen tokens. Consejos:

1. Descripciones concisas pero claras
2. Filtra respuestas de API
3. Caché de consultas repetidas

Cierre

La invocación de herramientas es el núcleo del agente de IA. Sin ella, solo teoría; con ella, trabajo real.

Function Calling de OpenAI: simple; Tool Use de Claude: potente; MCP: tendencia a largo plazo.

Sea cual sea tu elección, piensa antes en seguridad, errores y rendimiento.

Referencias

• Documentación Claude Tool Use
• Guía OpenAI Function Calling
• Especificación Model Context Protocol
• Configuración MCP en Claude Code
• Blog Anthropic sobre uso avanzado de herramientas