Cómo brindar a los agentes de IA herramientas del mundo real con una única API

Estás creando un agente de IA que ayuda a los usuarios con tareas técnicas. El agente debe buscar registros DNS, validar correos electrónicos, generar códigos QR y verificar certificados SSL. Los LLM pueden razonar sobre estas tareas, pero no pueden realizar llamadas de red ni generar imágenes. Su agente necesita herramientas.

El camino típico es doloroso. Conecta una biblioteca para DNS, otra para validación de correo electrónico y una tercera para códigos QR. Cada uno tiene su propia autenticación, su propio formato de respuesta y su propio manejo de errores. La capa de ejecución de herramientas de su agente se convierte en un mosaico de clientes API.

Un mejor enfoque: brindarle al agente acceso a una única API que cubra todas estas capacidades. Un token de autenticación. Un formato de respuesta. Un límite de tasa para rastrear. Esta publicación muestra cómo cablear el botoi API (Más de 150 puntos finales de herramientas de desarrollador) en tres arquitecturas de agentes: uso de herramientas Claude, llamada a funciones OpenAI y MCP.

El patrón de uso de herramientas en 30 segundos

Todos los principales proveedores de LLM ahora admiten el uso de herramientas (también llamadas llamadas a funciones). El patrón es el mismo en todos ellos:

1. Usted define un conjunto de herramientas con nombres, descripciones y esquemas de entrada.
2. Envía un mensaje de usuario al LLM junto con las definiciones de herramientas.
3. El LLM decide a qué herramienta convocar y con qué argumentos.
4. Su código ejecuta la llamada a la herramienta (una solicitud HTTP, una consulta de base de datos, una lectura de archivo).
5. Envía el resultado de la herramienta al LLM.
6. El LLM utiliza el resultado para formular su respuesta final.

El bucle se ve así en pseudocódigo:

// The tool-use loop: LLM reasons, picks a tool, you execute it
while (true) {
  const response = await llm.chat(messages);

  if (response.stop_reason === "tool_use") {
    const toolCall = response.tool_calls[0];
    const result = await executeToolCall(toolCall);
    messages.push({ role: "tool", content: result });
  } else {
    return response.content;  // Final answer
  }
}

El LLM nunca ejecuta la herramienta en sí. Produce una salida estructurada (nombre de la herramienta + argumentos) y su código realiza la ejecución. Esto significa que las herramientas pueden ser cualquier cosa: un comando de shell, una consulta de base de datos o una llamada API.

Por qué la API de Botoi se adapta bien al patrón de uso de herramientas

Cada punto final de botoi ya tiene la forma de una definición de herramienta. Cada punto final toma una entrada JSON y devuelve una salida JSON con una estructura coherente. Así es como se ve la definición de una herramienta de búsqueda de DNS:

// Each botoi endpoint maps to a tool definition
// The OpenAPI spec at /openapi.json provides this automatically
{
  "name": "dns_lookup",
  "description": "Look up DNS records for a domain",
  "parameters": {
    "type": "object",
    "properties": {
      "domain": { "type": "string", "description": "Domain to query" },
      "type": { "type": "string", "enum": ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] }
    },
    "required": ["domain"]
  }
}

Tres cosas hacen que esto funcione bien para las agentes:

• Borrar esquemas de entrada. Cada punto final acepta un cuerpo JSON pequeño y bien definido. Los LLM son buenos para producir JSON estructurado cuando el esquema es estricto.
• Formato de salida consistente. Todos los puntos finales regresan {"{ success: true, data: { ... } }"} o {"{ success: false, message: '...' }"}. El analizador de resultados de la herramienta de su agente maneja todos los puntos finales de la misma manera.
• Especificaciones de OpenAPI para descubrimiento automático. La especificación en api.botoi.com/openapi.json contiene esquemas completos para los más de 150 puntos finales. Puede generar definiciones de herramientas mediante programación en lugar de escribirlas a mano.

Arquitectura 1: uso de la herramienta Claude con el SDK de Anthropic

La API de uso de herramientas de Claude le permite pasar definiciones de herramientas junto con sus mensajes. Cuando Claude decide llamar a una herramienta, devuelve un tool_use bloque de contenido con el nombre de la herramienta y la entrada. Ejecuta la llamada y envía el resultado como un tool_result.

Aquí hay un agente en funcionamiento que puede buscar registros DNS, verificar certificados SSL y validar correos electrónicos usando botoi:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

// Define botoi endpoints as Claude tools
const tools = [
  {
    name: "dns_lookup",
    description: "Look up DNS records (A, MX, TXT, etc.) for a domain",
    input_schema: {
      type: "object",
      properties: {
        domain: { type: "string", description: "Domain to query" },
        type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
      },
      required: ["domain"],
    },
  },
  {
    name: "ssl_check",
    description: "Check SSL certificate and security headers for a domain",
    input_schema: {
      type: "object",
      properties: {
        url: { type: "string", description: "Domain or URL to check" },
      },
      required: ["url"],
    },
  },
  {
    name: "email_validate",
    description: "Validate an email address (syntax, MX, disposable check)",
    input_schema: {
      type: "object",
      properties: {
        email: { type: "string", description: "Email address to validate" },
      },
      required: ["email"],
    },
  },
];

// Map tool names to botoi API endpoints
const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  ssl_check: "/v1/ssl",
  email_validate: "/v1/email/validate",
};

async function callBotoiTool(name, input) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(input),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 1024,
      tools,
      messages,
    });

    // If Claude wants to use a tool, execute it and feed the result back
    if (response.stop_reason === "tool_use") {
      const toolBlock = response.content.find((b) => b.type === "tool_use");
      const result = await callBotoiTool(toolBlock.name, toolBlock.input);

      messages.push({ role: "assistant", content: response.content });
      messages.push({
        role: "user",
        content: [
          {
            type: "tool_result",
            tool_use_id: toolBlock.id,
            content: JSON.stringify(result),
          },
        ],
      });
    } else {
      // Claude is done; return the final text
      return response.content[0].text;
    }
  }
}

// Usage
const answer = await runAgent(
  "Check the DNS records and SSL certificate for stripe.com"
);
console.log(answer);

Pregúntele a este agente "Verifique los registros DNS y el certificado SSL de stripe.com" y Claude realizará dos llamadas a la herramienta en secuencia y luego sintetizará los resultados en un resumen legible. El agente maneja automáticamente el razonamiento de varios pasos; Claude elige qué herramientas llamar, en qué orden, según la pregunta del usuario.

Arquitectura 2: llamada a función OpenAI

La llamada a funciones de OpenAI sigue el mismo patrón con diferentes nombres de campos. Las herramientas se definen bajo un tools matriz con type: "function". El modelo regresa tool_calls cuando quiere ejecutar una función.

Una diferencia: GPT puede solicitar múltiples llamadas a herramientas en una sola respuesta. El siguiente código maneja la ejecución paralela de la herramienta:

import OpenAI from "openai";

const openai = new OpenAI();
const BOTOI_KEY = process.env.BOTOI_API_KEY;

const tools = [
  {
    type: "function",
    function: {
      name: "dns_lookup",
      description: "Look up DNS records for a domain",
      parameters: {
        type: "object",
        properties: {
          domain: { type: "string" },
          type: { type: "string", enum: ["A", "AAAA", "MX", "TXT", "CNAME", "NS"] },
        },
        required: ["domain"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "qr_generate",
      description: "Generate a QR code SVG from text or a URL",
      parameters: {
        type: "object",
        properties: {
          text: { type: "string", description: "Content to encode" },
          size: { type: "number", description: "Size in pixels (100-1000)" },
        },
        required: ["text"],
      },
    },
  },
];

const toolEndpoints = {
  dns_lookup: "/v1/dns/lookup",
  qr_generate: "/v1/qr/generate",
};

async function callBotoiTool(name, args) {
  const endpoint = toolEndpoints[name];
  const res = await fetch(\`https://api.botoi.com\${endpoint}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${BOTOI_KEY}\`,
    },
    body: JSON.stringify(args),
  });
  return await res.json();
}

async function runAgent(userMessage) {
  const messages = [{ role: "user", content: userMessage }];

  while (true) {
    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      tools,
      messages,
    });

    const choice = response.choices[0];

    if (choice.finish_reason === "tool_calls") {
      messages.push(choice.message);

      for (const call of choice.message.tool_calls) {
        const args = JSON.parse(call.function.arguments);
        const result = await callBotoiTool(call.function.name, args);

        messages.push({
          role: "tool",
          tool_call_id: call.id,
          content: JSON.stringify(result),
        });
      }
    } else {
      return choice.message.content;
    }
  }
}

const answer = await runAgent(
  "Generate a QR code for https://botoi.com and look up the MX records"
);
console.log(answer);

GPT-4o puede llamar a ambas dns_lookup y qr_generate en paralelo cuando las tareas son independientes. El bucle procesa todas las llamadas a herramientas antes de enviar los resultados al modelo.

Arquitectura 3: agentes basados ​​en MCP

El Protocolo de contexto modelo (MCP) es un enfoque diferente. En lugar de definir herramientas en su código, el agente descubre herramientas de un servidor MCP en tiempo de ejecución. Botoi ejecuta un servidor MCP en api.botoi.com/mcp con 44 herramientas seleccionadas.

Esta es la opción de código cero. No hay definiciones de herramientas para escribir. No hay capa de ejecución para construir. El cliente MCP (Claude Desktop, Cursor, Claude Code, VS Code) se conecta al servidor, descubre las herramientas y maneja la ejecución.

// Claude Desktop, Cursor, or VS Code: add to your MCP config
{
  "mcpServers": {
    "botoi": {
      "type": "streamable-http",
      "url": "https://api.botoi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

// Claude Code: one command
// claude mcp add botoi --transport streamable-http https://api.botoi.com/mcp

Después de agregar esta configuración, su asistente de IA puede llamar a cualquiera de las 44 herramientas por su nombre. Pregunte "busque los registros MX de github.com" y el asistente llamará al lookup_dns herramienta, pasa el dominio y el tipo de registro, y devuelve JSON estructurado.

MCP es la elección correcta cuando se utiliza un asistente de IA de forma interactiva (en un IDE o cliente de chat). La llamada a funciones es la elección correcta cuando se crea un agente programático que se ejecuta de forma autónoma.

Por qué una API única es importante para las agentes

Cuando conectas herramientas para un agente, la capa de ejecución de herramientas es la pieza que se rompe en producción. Cada API externa que agregue introduce su propio modo de falla. Considere lo que sucede cuando su agente usa cinco API diferentes:

• Cinco claves API para rotar y almacenar de forma segura.
• Cinco límites de tarifas para realizar un seguimiento de forma independiente.
• Cinco formatos de respuesta para normalizar antes de enviar los resultados al LLM.
• Cinco rutas de manejo de errores con diferentes códigos de estado y formas de error.
• Cinco paneles de facturación para monitorear.

Con una única API, la función de ejecución de su herramienta se reduce a un patrón:

// Shared helper: route any tool call to the right botoi endpoint
async function executeBotoiTool(name, input) {
  const ENDPOINTS = {
    dns_lookup:      "/v1/dns/lookup",
    ssl_check:       "/v1/ssl",
    email_validate:  "/v1/email/validate",
    qr_generate:     "/v1/qr/generate",
    ip_lookup:       "/v1/ip/lookup",
    hash_generate:   "/v1/hash",
    jwt_decode:      "/v1/jwt/decode",
    pii_detect:      "/v1/pii/detect",
    whois_lookup:    "/v1/whois",
    token_count:     "/v1/token/count",
  };

  const path = ENDPOINTS[name];
  if (!path) throw new Error("Unknown tool: " + name);

  const res = await fetch(\`https://api.botoi.com\${path}\`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": \`Bearer \${process.env.BOTOI_API_KEY}\`,
    },
    body: JSON.stringify(input),
  });

  if (!res.ok) {
    const err = await res.json();
    return { error: err.message || "API call failed" };
  }

  return await res.json();
}

Cada llamada a la herramienta pasa por el mismo encabezado de autenticación, la misma forma de error, el mismo límite de tasa. Agregar una nueva herramienta significa agregar una línea al ENDPOINTS mapa. Sin nuevas dependencias, sin nuevas credenciales.

Elegir las herramientas adecuadas para su agente

No registre los más de 150 puntos finales como herramientas. Los LLM obtienen peores resultados cuando la lista de herramientas es larga porque tienen que razonar sobre más opciones. Elija entre 5 y 15 herramientas que su agente necesita para su caso de uso específico.

Algunos arquetipos de agentes y las herramientas que se adaptan a ellos:

• Agente de monitoreo de infraestructura: Búsqueda de DNS, verificación de SSL, encabezados HTTP, verificación del rendimiento del sitio, verificación del tiempo de actividad, búsqueda de IP
• Auditor de seguridad del correo electrónico: Verificación SPF, verificación DMARC, verificación DKIM, verificación de registros MX, validación de correo electrónico, verificación de correo electrónico desechable
• Agente de procesamiento de datos: Formato JSON, CSV a JSON, XML a JSON, codificación/decodificación Base64, HTML a Markdown, detección de PII
• Asistente de desarrolladora: Decodificación JWT, generación de hash, generación de UUID, análisis cron, prueba de expresiones regulares, recuento de tokens

Empiece por poco. Agregue herramientas cuando los usuarios de su agente soliciten capacidades que este no puede manejar. Supervise qué herramientas se llaman y elimine las que nunca se activan.

Puntos clave

• Razón de los LLM; las herramientas actúan. El patrón de uso de herramientas separa la planificación del LLM de la ejecución de acciones del mundo real. Su agente necesita herramientas confiables para cerrar esa brecha.
• Una API, una ruta de ejecución. Una única API con autenticación, formato de respuesta y manejo de errores consistentes simplifica la capa de ejecución de herramientas que cada agente necesita.
• Tres arquitecturas, misma API. El uso de la herramienta Claude, la llamada a funciones OpenAI y MCP funcionan con puntos finales de botoi. Elija el que coincida con su modelo de implementación.
• Mantenga pequeña la lista de herramientas. Registre entre 5 y 15 herramientas por agente. Demasiadas opciones degradan la precisión de selección de herramientas del LLM.
• MCP para uso interactivo, llamada de función para agentes autónomos. MCP maneja el descubrimiento y ejecución de herramientas por usted. La llamada a funciones le brinda control total sobre el bucle.

La Documentos API enumere cada punto final con esquemas de solicitud/respuesta. El Especificaciones de OpenAPI le permite generar definiciones de herramientas mediante programación. El Manifiesto de la herramienta MCP muestra las 44 herramientas seleccionadas disponibles a través de MCP.