botserver/docs/src/chapter-09-api

Chapter 09: APIs and Tools

General Bots transforms BASIC scripts into powerful tools that LLMs can discover and use automatically. This chapter explains how to create tools, integrate with external APIs, and build sophisticated AI capabilities without complex frameworks.

The Tool Revolution

In the LLM era, tools are not manually coded integrations - they're capabilities that AI can discover and use intelligently. General Bots makes this simple: write a BASIC script, it becomes a tool.

How Tools Work in General Bots

Traditional Approach (Complex)

// Define schema
const toolSchema = {
  name: "weather",
  description: "Get weather information",
  parameters: {
    type: "object",
    properties: {
      location: { type: "string" }
    }
  }
};

// Register with framework
framework.registerTool(toolSchema, async (params) => {
  // Implementation
});

General Bots Approach (Simple)

' weather.bas - This is a complete tool!
PARAM location AS STRING LIKE "New York" DESCRIPTION "City to get weather for"
DESCRIPTION "Gets current weather information"

weather = GET "api/weather/" + location
TALK "The weather in " + location + ": " + weather

That's it. The LLM can now use this tool whenever users ask about weather.

Core Concepts

Tools Are Just BASIC Files

Every .bas file in your .gbdialog folder is automatically a potential tool. No registration, no configuration, no boilerplate.

LLMs Orchestrate Everything

The AI decides when to use tools based on user intent. You don't write decision logic - you provide capabilities.

Parameters Drive Conversations

PARAM declarations tell the LLM what information to collect. The AI handles the conversation naturally.

What You'll Learn

Tool Creation

• Tool Definition - Creating tools from BASIC scripts
• PARAM Declaration - Defining tool parameters
• Tool Compilation - How tools are processed

API Integration

• External APIs - Calling web services
• GET Integration - Using GET for API calls
• Authentication - Handling API keys securely

Advanced Topics

• MCP Format - Model Context Protocol
• Tool Format - OpenAI-compatible functions
• Tool Discovery - How LLMs find tools
• Error Handling - Robust tool design

Quick Example: Complete API Integration

Here's a real-world tool that integrates with an external API:

' translate.bas - Translation tool using external API
PARAM text AS STRING DESCRIPTION "Text to translate"
PARAM target AS STRING LIKE "es" DESCRIPTION "Target language code (es, fr, de, etc)"

DESCRIPTION "Translates text to another language"

' Get API key from secure storage
api_key = GET BOT MEMORY "translation_api_key"

' Call external translation API
result = GET "https://api.translator.com/v1/translate" WITH {
  "text": text,
  "target": target,
  "key": api_key
}

IF result.error THEN
  TALK "Sorry, translation failed: " + result.error
ELSE
  TALK "Translation: " + result.translated_text
END IF

The LLM will:

1. Understand when translation is needed
2. Collect the text and target language through natural conversation
3. Call this tool with the right parameters
4. Present the results conversationally

Why This Approach Works

No Glue Code

Traditional systems require layers of integration code. In General Bots, BASIC scripts directly become AI capabilities.

Natural Conversations

Instead of forms and wizards, users have conversations. The AI handles all the complexity of gathering information.

Rapid Development

Create a new tool in minutes, not days. Change it instantly. No compilation, no deployment process.

Universal Compatibility

Tools automatically work with any LLM that supports function calling - Groq, OpenAI, Anthropic, or local models.

Tool Ecosystem

Built-in Tools

General Bots includes ready-to-use tools for common tasks:

• Email sending
• Database queries
• Web scraping
• File operations
• Calendar management

Custom Tools

Create your own tools for:

• Business processes
• API integrations
• Data transformations
• Workflow automation
• External services

Tool Libraries

Share and reuse tools across bots. Build a library of capabilities for your organization.

Best Practices

Keep Tools Focused

Each tool should do one thing well. Let the LLM compose them for complex tasks.

Use Clear Descriptions

The DESCRIPTION helps the LLM understand when to use your tool:

DESCRIPTION "Books a meeting room for the specified date and time"

Handle Errors Gracefully

Always provide meaningful feedback when things go wrong:

IF NOT result.success THEN
  TALK "I couldn't complete that: " + result.message
END IF

Secure API Keys

Never hardcode credentials. Use BOT MEMORY:

api_key = GET BOT MEMORY "service_api_key"

Real-World Use Cases

Customer Service

Tools for checking orders, processing returns, updating accounts - all through natural conversation.

Data Analysis

Connect to databases, generate reports, visualize data - the AI guides users through complex queries.

Business Automation

Approval workflows, document processing, notification systems - replacing traditional forms with conversation.

Integration Hub

Connect legacy systems, modern APIs, and cloud services - unified through conversational AI.

Getting Started

1. Create a simple tool - Start with a basic .bas file
2. Add parameters - Define what information the tool needs
3. Test with the LLM - See how the AI uses your tool
4. Iterate quickly - Refine based on real usage

Summary

APIs and tools in General Bots are refreshingly simple. Write BASIC scripts that become AI capabilities. No frameworks, no schemas, no complex integrations. Just describe what you want in simple code, and let the LLM handle the rest.

The future of API integration isn't about writing more code - it's about providing capabilities that AI can orchestrate intelligently.

Next Steps

• Tool Definition - Deep dive into creating tools
• External APIs - Connect to any web service
• PARAM Declaration - Master parameter definitions

---