Los FunctionTool patterns en LlamaIndex.ts

Los FunctionTool patterns en LlamaIndex.ts son la forma estándar de crear herramientas personalizadas para tus agentes AI. No es algo inventado - es API oficial documentada.

¿Qué es FunctionTool?

FunctionTool es la clase base de LlamaIndex para crear herramientas que tus agentes AI pueden usar durante conversaciones. Permite que el modelo ejecute acciones específicas según el contexto.

import { FunctionTool } from "llamaindex";

const tool = FunctionTool.from(
  async (params) => {
    // Tu implementación aquí
    return "Resultado de la herramienta";
  },
  {
    name: "nombre_herramienta",
    description: "Descripción clara de qué hace",
    parameters: {
      // JSON Schema para validación
      type: "object",
      properties: {
        message: { type: "string" }
      },
      required: ["message"]
    }
  }
);

Ejemplo Práctico: Herramienta de Clima

const weatherTool = FunctionTool.from(
  async ({ city }: { city: string }) => {
    // Simulamos llamada a API de clima
    const weather = await fetch(`/api/weather/${city}`);
    const data = await weather.json();
    
    return `El clima en ${city}: ${data.temperature}°C, ${data.condition}`;
  },
  {
    name: "get_weather",
    description: "Obtiene información del clima para una ciudad específica",
    parameters: {
      type: "object",
      properties: {
        city: {
          type: "string",
          description: "Nombre de la ciudad"
        }
      },
      required: ["city"]
    }
  }
);

Integrando Tools con Agentes

import { OpenAI, FunctionTool, ChatEngine } from "llamaindex";

// Crear múltiples herramientas
const tools = [
  weatherTool,
  scheduleReminderTool,
  searchWebTool
];

// Inicializar agente con herramientas
const llm = new OpenAI({ model: "gpt-4" });
const chatEngine = new ChatEngine({ llm, tools });

// El agente puede usar las herramientas automáticamente
const response = await chatEngine.chat("¿Cómo está el clima en Madrid?");

Patterns Avanzados

1. Tool con Estado Persistente

class DatabaseTool extends FunctionTool {
  constructor(private db: Database) {
    super();
  }
  
  async call({ query }: { query: string }) {
    const results = await this.db.execute(query);
    return JSON.stringify(results);
  }
}

2. Tool Async con Error Handling

const apiTool = FunctionTool.from(
  async ({ endpoint, method = "GET" }: { endpoint: string, method?: string }) => {
    try {
      const response = await fetch(endpoint, { method });
      if (!response.ok) throw new Error(`HTTP ${response.status}`);
      return await response.text();
    } catch (error) {
      return `Error: ${error.message}`;
    }
  },
  {
    name: "api_call",
    description: "Realiza llamadas HTTP a APIs externas",
    parameters: {
      type: "object",
      properties: {
        endpoint: { type: "string" },
        method: { type: "string", enum: ["GET", "POST", "PUT", "DELETE"] }
      },
      required: ["endpoint"]
    }
  }
);

Mejores Prácticas

✅ Hazlo Bien

• Descripciones claras: El modelo decide cuándo usar la tool basado en la descripción
• Validación de parámetros: Usa JSON Schema completo
• Manejo de errores: Siempre retorna strings, nunca throws
• Funciones puras: Sin efectos secundarios impredecibles

❌ Evita Esto

// ❌ Descripción vaga
description: "Hace algo"

// ❌ Sin validación
parameters: {}

// ❌ Throwing errors
async (params) => {
  throw new Error("Algo salió mal");
}

Casos de Uso Reales

• APIs externas: Clima, noticias, traducción
• Base de datos: Consultas, inserts, updates
• Servicios: Email, SMS, notificaciones
• Archivos: Lectura, escritura, procesamiento
• Calendarios: Eventos, recordatorios, citas

Alternativas en LlamaIndex

Además de FunctionTool.from(), LlamaIndex ofrece:

• QueryEngineTool: Para búsquedas en documentos
• BaseToolWithCall: Para implementaciones custom avanzadas
• VectorStoreRetrieverTool: Para retrieval semántico

---

FunctionTool es el patrón estándar más usado por su simplicidad y flexibilidad. Ideal para la mayoría de casos de uso donde necesitas que tu agente AI ejecute acciones específicas.

¿Estás construyendo herramientas personalizadas con LlamaIndex? Charlemos.