Introducción

Los agentes de IA se vuelven útiles cuando pueden comunicarse con el mundo exterior. Las APIs REST son la forma más común en que los sistemas exponen funcionalidad, por lo que un agente debe poder llamarlas bajo demanda. El reto es que la mayoría de las APIs están diseñadas para clientes operados por humanos (paneles, aplicaciones móviles), no para tomadores de decisiones autónomos. Antes de que un agente pueda usar una API, necesitas traducir el contrato de la API en algo que el agente pueda entender e invocar.

Envolver una API como herramienta

Una herramienta, desde la perspectiva del agente, es una función con un nombre, una descripción y un conjunto de parámetros. Construyes un envoltorio delgado que recibe entrada estructurada del agente (por ejemplo, el nombre de una ciudad) y devuelve un resultado estructurado.

import requests

def get_weather(city: str) -> dict:
    url = "https://api.example.com/weather"
    params = {"q": city, "units": "metric"}
    response = requests.get(url, params=params, timeout=10)
    response.raise_for_status()
    return response.json()

El envoltorio oculta los detalles HTTP (cabeceras, códigos de estado, parseo de JSON) y expone una firma de función limpia. El agente solo ve el nombre de la función, su docstring o descripción y los parámetros tipados.

Estructurar la descripción para el agente

La descripción es lo que indica al agente cuándo y cómo llamar a la herramienta. Una buena descripción de herramienta tiene tres partes: un resumen de una línea de lo que hace la herramienta, una nota sobre cuándo usarla (y, igualmente importante, cuándo no) y una descripción de cada parámetro, incluyendo formato y restricciones.

{
  "name": "get_weather",
  "description": "Get current weather for a city. Use when the user asks about weather, temperature, or conditions outdoors. Do not use for forecasts beyond 24 hours.",
  "parameters": {
    "city": {
      "type": "string",
      "description": "City name in English, e.g. 'Hanoi' or 'Tokyo'"
    }
  }
}

Mantén las descripciones factuales. Evita palabras exageradas como "potente" o "avanzado": el agente toma decisiones de invocación basándose en la utilidad, no en lenguaje de marketing.

Gestión de límites de velocidad, paginación y errores

Las APIs fallan de formas predecibles. Tu envoltorio debe manejar esos fallos para que el agente reciba retroalimentación útil en lugar de trazas de pila crudas.

Para límites de velocidad, respeta la cabecera Retry-After cuando esté presente y aplica backoff exponencial ante respuestas 429 repetidas. Envuelve la llamada en un bucle de reintentos con un número máximo de intentos para evitar esperas infinitas.

import time
import requests

def call_with_retry(url, params, max_attempts=3):
    for attempt in range(max_attempts):
        response = requests.get(url, params=params, timeout=10)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Rate limited after retries")

Para paginación, diseña el envoltorio de modo que acepte un parámetro page o cursor y devuelva una señal clara cuando haya más páginas disponibles. Deja que el agente decida si seguir fetching: puede razonar sobre coste y relevancia mejor que un bucle hardcoded.

Para errores, devuelve un objeto estructurado en lugar de lanzar excepciones a ciegas. Incluye el código de estado, una razón breve legible por humanos y, opcionalmente, una pista sobre cómo recuperarse. Esto permite al agente reintentar con parámetros corregidos, cambiar de herramienta o reportar el problema al usuario.

Resumen

Trata cada API como una herramienta con tres capas: una firma de función limpia, una descripción precisa que el agente pueda usar para seleccionarla y un envoltorio robusto que gestione las realidades del HTTP: reintentos, paginación y reporte de errores. El envoltorio es el contrato entre un servicio externo poco fiable y un agente razonador que necesita entradas predecibles para tomar buenas decisiones.

Errores comunes

Envolver una API sin una descripción que especifique cuándo no usarla. Dejar que las excepciones crudas se propaguen al agente en lugar de devolver objetos de error estructurados. Hardcodear bucles de paginación para que el agente no pueda saltar páginas o detenerse antes. Ignorar la cabecera Retry-After y usar retardos fijos que te baneen más rápido.