Как предоставить агентам ИИ реальные инструменты с помощью единого API

Вы создаете ИИ-агент, который помогает пользователям решать технические задачи. Агенту необходимо искать записи DNS, проверять электронную почту, генерировать QR-коды и проверять сертификаты SSL. LLM могут рассуждать об этих задачах, но не могут совершать сетевые вызовы или генерировать изображения. Вашему агенту нужны инструменты.

Типичный путь болезненный. Вы подключаете одну библиотеку для DNS, другую для проверки электронной почты, третью для QR-кодов. У каждого своя авторизация, свой формат ответа, своя обработка ошибок. Уровень выполнения инструментов вашего агента становится лоскутным одеялом из клиентов API.

Лучший подход: предоставить агенту доступ к единому API, который охватывает все эти возможности. Один токен аутентификации. Один формат ответа. Один предел скорости для отслеживания. В этом посте показано, как подключить Ботой API (более 150 конечных точек инструментов разработчика) на три архитектуры агентов: использование инструмента Claude, вызов функций OpenAI и MCP.

Схема использования инструмента за 30 секунд

Каждый крупный поставщик LLM теперь поддерживает использование инструментов (также называемое вызовом функций). Схема одинакова для всех:

1. Вы определяете набор инструментов с именами, описаниями и входными схемами.
2. Вы отправляете сообщение пользователя в LLM вместе с определениями инструментов.
3. LLM решает, какой инструмент вызывать и с какими аргументами.
4. Ваш код выполняет вызов инструмента (запрос HTTP, запрос к базе данных, чтение файла).
5. Вы отправляете результат инструмента обратно в LLM.
6. LLM использует результат для формулирования окончательного ответа.

В псевдокоде цикл выглядит следующим образом:

// 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
  }
}

LLM никогда не запускает сам инструмент. Он выдает структурированный вывод (имя инструмента + аргументы), а ваш код выполняет его. Это означает, что инструментами может быть что угодно: команда оболочки, запрос к базе данных или вызов API.

Почему API botoi хорошо соответствует шаблону использования инструментов

Каждая конечная точка ботоя уже имеет форму определения инструмента. Каждая конечная точка принимает входные данные JSON и возвращает выходные данные JSON с согласованной структурой. Вот как выглядит определение инструмента поиска 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"]
  }
}

Три вещи делают эту работу эффективной для агентов:

• Очистить входные схемы. Каждая конечная точка принимает небольшое, четко определенное тело JSON. LLM хорошо создают структурированный JSON, когда схема тесная.
• Согласованный формат вывода. Все конечные точки возвращаются {"{ success: true, data: { ... } }"} или {"{ success: false, message: '...' }"}. Анализатор результатов инструмента вашего агента обрабатывает каждую конечную точку одинаково.
• Спецификация OpenAPI для автоматического обнаружения. Спецификация на api.botoi.com/openapi.json содержит полные схемы для всех более чем 150 конечных точек. Вы можете программно генерировать на его основе определения инструментов вместо того, чтобы писать их вручную.

Архитектура 1. Использование инструмента Claude с Anthropic SDK.

API использования инструментов Claude позволяет передавать определения инструментов вместе с вашими сообщениями. Когда Клод решает вызвать инструмент, он возвращает tool_use блок контента с именем инструмента и вводом. Вы выполняете вызов и отправляете результат обратно в виде tool_result.

Вот рабочий агент, который может искать записи DNS, проверять сертификаты SSL и проверять электронную почту с помощью 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);

Попросите этого агента «Проверьте записи DNS и SSL-сертификат для Stripe.com», и Клод последовательно выполнит два вызова инструмента, а затем синтезирует результаты в удобочитаемую сводку. Агент автоматически обрабатывает многоэтапные рассуждения; Клод выбирает, какие инструменты вызывать и в каком порядке, в зависимости от вопроса пользователя.

Архитектура 2: вызов функций OpenAI

Вызов функций OpenAI следует тому же шаблону с разными именами полей. Инструменты определены под tools массив с type: "function". Модель возвращается tool_calls когда он хочет выполнить функцию.

Одно отличие: GPT может запрашивать несколько вызовов инструментов в одном ответе. Код ниже обрабатывает параллельное выполнение инструмента:

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 может вызывать оба dns_lookup и qr_generate параллельно, когда задачи независимы. Цикл обрабатывает все вызовы инструментов перед отправкой результатов обратно в модель.

Архитектура 3: агенты на базе MCP

Протокол контекста модели (MCP) представляет собой другой подход. Вместо определения инструментов в вашем коде агент обнаруживает инструменты на сервере MCP во время выполнения. Ботой запускает сервер MCP по адресу api.botoi.com/mcp с 44 ​​тщательно подобранными инструментами.

Это вариант с нулевым кодом. Нет определений инструментов для написания. Нет исполнительного уровня для построения. Клиент MCP (Claude Desktop, Cursor, Claude Code, VS Code) подключается к серверу, обнаруживает инструменты и управляет выполнением.

// 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

После добавления этой конфигурации ваш ИИ-помощник сможет вызывать любой из 44 инструментов по имени. Попросите «найти записи MX для github.com», и помощник вызовет lookup_dns инструмент, передает домен и тип записи и возвращает структурированный JSON.

MCP — правильный выбор, когда вы используете помощника искусственного интеллекта в интерактивном режиме (в IDE или чат-клиенте). Вызов функций — правильный выбор при создании программного агента, работающего автономно.

Почему единый API важен для агентов

Когда вы подключаете инструменты для агента, уровень выполнения инструментов — это та часть, которая ломается в рабочей среде. Каждый внешний API, который вы добавляете, имеет свой собственный режим сбоя. Рассмотрим, что происходит, когда ваш агент использует пять разных API:

• Пять ключей API для безопасного ротации и хранения.
• Пять ограничений скорости для независимого отслеживания.
• Пять форматов ответов, которые необходимо нормализовать перед отправкой результатов обратно в LLM.
• Пять путей обработки ошибок с различными кодами состояния и формами ошибок.
• Пять биллинговых панелей для мониторинга.

Благодаря единому API функция выполнения вашего инструмента сводится к одному шаблону:

// 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();
}

Каждый вызов инструмента проходит через один и тот же заголовок аутентификации, одну и ту же форму ошибки, одно и то же ограничение скорости. Добавление нового инструмента означает добавление одной строки в ENDPOINTS карта. Никаких новых зависимостей, никаких новых учетных данных.

Выбор подходящих инструментов для вашего агента

Не регистрируйте все более 150 конечных точек в качестве инструментов. LLM работают хуже, когда список инструментов длинный, потому что им приходится обдумывать больше вариантов. Выберите 5–15 инструментов, которые нужны вашему агенту для конкретного случая использования.

Некоторые архетипы агентов и инструменты, которые им подходят:

• Агент мониторинга инфраструктуры: Поиск DNS, проверка SSL, заголовки HTTP, проверка производительности сайта, проверка работоспособности, поиск IP
• Аудитор безопасности электронной почты: Проверка SPF, проверка DMARC, проверка DKIM, проверка записи MX, проверка электронной почты, одноразовая проверка электронной почты
• Агент обработки данных: Формат JSON, CSV в JSON, XML в JSON, кодирование/декодирование Base64, HTML в Markdown, обнаружение PII
• Помощник разработчика: Декодирование JWT, генерация хеша, генерация UUID, анализ cron, проверка регулярных выражений, подсчет токенов

Начните с узкого. Добавляйте инструменты, когда пользователи вашего агента запрашивают возможности, с которыми он не может справиться. Отслеживайте, какие инструменты вызываются, и удаляйте те, которые никогда не срабатывают.

Ключевые моменты

• Причина магистратуры; инструменты действуют. Модель использования инструментов отделяет планирование LLM от выполнения реальных действий. Вашему агенту нужны надежные инструменты, чтобы преодолеть этот разрыв.
• Один API, один путь выполнения. Единый API с единообразной аутентификацией, форматом ответа и обработкой ошибок упрощает уровень выполнения инструментов, необходимый каждому агенту.
• Три архитектуры, один и тот же API. Использование инструментов Claude, вызов функций OpenAI и MCP работают с конечными точками botoi. Выберите тот, который соответствует вашей модели развертывания.
• Держите список инструментов небольшим. Зарегистрируйте 5–15 инструментов на каждого агента. Слишком большое количество опций снижает точность выбора инструмента LLM.
• MCP для интерактивного использования, вызов функций для автономных агентов. MCP обеспечивает обнаружение и выполнение инструментов за вас. Вызов функции дает вам полный контроль над циклом.

The Документация по API перечислите каждую конечную точку со схемами запросов/ответов. Спецификация OpenAPI позволяет программно создавать определения инструментов. Манифест инструмента MCP показывает 44 тщательно подобранных инструмента, доступных через MCP.