Como fornecer aos agentes de IA ferramentas do mundo real com uma única API

Você está construindo um agente de IA que ajuda os usuários em tarefas técnicas. O agente precisa consultar registros DNS, validar e-mails, gerar códigos QR e verificar certificados SSL. Os LLMs podem raciocinar sobre essas tarefas, mas não podem fazer chamadas de rede ou gerar imagens. Seu agente precisa de ferramentas.

O caminho típico é doloroso. Você conecta uma biblioteca para DNS, outra para validação de e-mail e uma terceira para códigos QR. Cada um tem sua própria autenticação, seu próprio formato de resposta, seu próprio tratamento de erros. A camada de execução de ferramentas do seu agente se torna uma colcha de retalhos de clientes de API.

Uma abordagem melhor: dar ao agente acesso a uma única API que cubra todos esses recursos. Um token de autenticação. Um formato de resposta. Um limite de taxa para rastrear. Esta postagem mostra como conectar o API botoi (mais de 150 endpoints de ferramentas de desenvolvedor) em três arquiteturas de agente: uso de ferramenta Claude, chamada de função OpenAI e MCP.

O padrão de uso da ferramenta em 30 segundos

Todos os principais provedores de LLM agora oferecem suporte ao uso de ferramentas (também chamado de chamada de função). O padrão é o mesmo em todos eles:

1. Você define um conjunto de ferramentas com nomes, descrições e esquemas de entrada.
2. Você envia uma mensagem do usuário ao LLM junto com as definições da ferramenta.
3. O LLM decide qual ferramenta chamar e com quais argumentos.
4. Seu código executa a chamada da ferramenta (uma solicitação HTTP, uma consulta ao banco de dados, uma leitura de arquivo).
5. Você envia o resultado da ferramenta de volta ao LLM.
6. O LLM usa o resultado para formular sua resposta final.

O loop fica assim em 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
  }
}

O LLM nunca executa a ferramenta sozinho. Produz saída estruturada (nome da ferramenta + argumentos) e seu código faz a execução. Isso significa que as ferramentas podem ser qualquer coisa: um comando shell, uma consulta de banco de dados ou uma chamada de API.

Por que a API do botoi mapeia bem o padrão de uso da ferramenta

Cada ponto final do botoi já tem o formato de uma definição de ferramenta. Cada endpoint recebe uma entrada JSON e retorna uma saída JSON com uma estrutura consistente. Esta é a aparência de uma definição de ferramenta de pesquisa 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"]
  }
}

Três coisas fazem com que isso funcione bem para os agentes:

• Esquemas de entrada claros. Cada endpoint aceita um corpo JSON pequeno e bem definido. LLMs são bons na produção de JSON estruturado quando o esquema é rígido.
• Formato de saída consistente. Todos os endpoints retornam {"{ success: true, data: { ... } }"} ou {"{ success: false, message: '...' }"}. O analisador de resultados da ferramenta do seu agente lida com todos os endpoints da mesma maneira.
• Especificação OpenAPI para descoberta automática. A especificação em api.botoi.com/openapi.json contém esquemas completos para todos os mais de 150 endpoints. Você pode gerar programaticamente definições de ferramentas a partir dele, em vez de escrevê-las manualmente.

Arquitetura 1: uso da ferramenta Claude com o Anthropic SDK

A API de uso de ferramentas do Claude permite que você passe definições de ferramentas junto com suas mensagens. Quando Claude decide chamar uma ferramenta, ela retorna um tool_use bloco de conteúdo com o nome da ferramenta e entrada. Você executa a chamada e envia o resultado de volta como um tool_result.

Aqui está um agente funcional que pode pesquisar registros DNS, verificar certificados SSL e validar e-mails 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);

Pergunte a este agente "Verifique os registros DNS e o certificado SSL de stripe.com" e Claude fará duas chamadas de ferramenta em sequência e, em seguida, sintetizará os resultados em um resumo legível. O agente lida automaticamente com o raciocínio em várias etapas; Claude escolhe quais ferramentas chamar, em que ordem, com base na pergunta do usuário.

Arquitetura 2: chamada de função OpenAI

A chamada de função do OpenAI segue o mesmo padrão com nomes de campos diferentes. As ferramentas são definidas em um tools matriz com type: "function". O modelo retorna tool_calls quando deseja executar uma função.

Uma diferença: a GPT pode solicitar várias chamadas de ferramenta em uma única resposta. O código abaixo lida com a execução paralela da ferramenta:

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 pode ligar para ambos dns_lookup e qr_generate em paralelo quando as tarefas são independentes. O loop processa todas as chamadas de ferramenta antes de enviar os resultados de volta ao modelo.

Arquitetura 3: Agentes baseados em MCP

O Model Context Protocol (MCP) é uma abordagem diferente. Em vez de definir ferramentas no seu código, o agente descobre ferramentas de um servidor MCP em tempo de execução. Botoi executa um servidor MCP em api.botoi.com/mcp com 44 ferramentas selecionadas.

Esta é a opção de código zero. Nenhuma definição de ferramenta para escrever. Nenhuma camada de execução para construir. O cliente MCP (Claude Desktop, Cursor, Claude Code, VS Code) se conecta ao servidor, descobre as ferramentas e cuida da execução.

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

Depois de adicionar esta configuração, seu assistente de IA pode chamar qualquer uma das 44 ferramentas pelo nome. Pergunte "procure os registros MX de github.com" e o assistente liga para o lookup_dns ferramenta, passa o domínio e o tipo de registro e retorna JSON estruturado.

O MCP é a escolha certa quando você usa um assistente de IA de forma interativa (em um IDE ou cliente de chat). A chamada de função é a escolha certa quando você está construindo um agente programático que funciona de forma autônoma.

Por que uma única API é importante para os agentes

Quando você conecta ferramentas para um agente, a camada de execução de ferramentas é a parte que interrompe a produção. Cada API externa adicionada introduz seu próprio modo de falha. Considere o que acontece quando seu agente usa cinco APIs diferentes:

• Cinco chaves de API para alternar e armazenar com segurança.
• Cinco limites de taxa para rastrear de forma independente.
• Cinco formatos de resposta para normalizar antes de enviar os resultados ao LLM.
• Cinco caminhos de tratamento de erros com diferentes códigos de status e formatos de erro.
• Cinco painéis de faturamento para monitorar.

Com uma única API, sua função de execução de ferramenta se reduz a um padrão:

// 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 chamada de ferramenta passa pelo mesmo cabeçalho de autenticação, pelo mesmo formato de erro e pelo mesmo limite de taxa. Adicionar uma nova ferramenta significa adicionar uma linha ao ENDPOINTS mapa. Sem novas dependências, sem novas credenciais.

Escolhendo as ferramentas certas para seu agente

Não registre todos os mais de 150 endpoints como ferramentas. Os LLMs têm pior desempenho quando a lista de ferramentas é longa porque eles precisam raciocinar sobre mais opções. Escolha de 5 a 15 ferramentas que seu agente precisa para seu caso de uso específico.

Alguns arquétipos de agentes e as ferramentas adequadas a eles:

• Agente de monitoramento de infraestrutura: Pesquisa de DNS, verificação de SSL, cabeçalhos HTTP, verificação de desempenho do site, verificação de tempo de atividade, pesquisa de IP
• Auditor de segurança de e-mail: Verificação SPF, verificação DMARC, verificação DKIM, verificação de registro MX, validação de e-mail, verificação de e-mail descartável
• Agente de processamento de dados: Formato JSON, CSV para JSON, XML para JSON, codificação/decodificação Base64, HTML para Markdown, detecção de PII
• Assistente de desenvolvedor: Decodificação JWT, geração de hash, geração de UUID, análise cron, teste regex, contagem de tokens

Comece estreito. Adicione ferramentas quando os usuários do seu agente solicitarem recursos que eles não conseguem atender. Monitore quais ferramentas são chamadas e remova aquelas que nunca são acionadas.

Pontos-chave

• Razão do LLM; as ferramentas agem. O padrão de uso de ferramentas separa o planejamento do LLM da execução de ações do mundo real. Seu agente precisa de ferramentas confiáveis ​​para preencher essa lacuna.
• Uma API, um caminho de execução. Uma única API com autenticação consistente, formato de resposta e tratamento de erros simplifica a camada de execução de ferramentas que todo agente precisa.
• Três arquiteturas, mesma API. O uso da ferramenta Claude, a chamada de função OpenAI e o MCP funcionam com endpoints botoi. Escolha aquele que corresponde ao seu modelo de implantação.
• Mantenha a lista de ferramentas pequena. Registre de 5 a 15 ferramentas por agente. Muitas opções prejudicam a precisão da seleção de ferramentas do LLM.
• MCP para uso interativo, chamada de função para agentes autônomos. O MCP cuida da descoberta e execução de ferramentas para você. A chamada de função oferece controle total sobre o loop.

O Documentos da API liste cada endpoint com esquemas de solicitação/resposta. O Especificação OpenAPI permite gerar definições de ferramentas programaticamente. O Manifesto da ferramenta MCP mostra as 44 ferramentas selecionadas disponíveis via MCP.