GeneralBots/botserver

Fork 0

Rodrigo Rodriguez (Pragmatismo) fdf74903ad fix(server): update security modules and TODOs

2026-01-25 08:42:36 -03:00

9.1 KiB

Raw Blame History

Tools vs Bots: When to Use Each

Chapter 4: Understanding the Difference Between Function Calls and AI Agents

Overview

General Bots provides two ways to extend your bot's capabilities:

TOOLs - Simple functions with input/output
BOTs - Intelligent AI agents that can reason and remember

Understanding when to use each is crucial for building efficient, cost-effective automation.

Quick Comparison

Feature	TOOL	BOT
Purpose	Data operations	Decision making
Intelligence	None (function)	Full LLM reasoning
Speed	Fast (10-100ms)	Slower (1-5 seconds)
Cost	Free	LLM tokens ($0.001-0.01)
Input	Structured data	Natural language
Output	Structured data	Conversational response
Memory	Stateless	Remembers context

Tools: The Function Approach

What Are Tools?

Tools are stateless functions that perform specific operations:

' Tool usage - direct function call
USE TOOL "check-order"
result = CALL TOOL "check-order" WITH order_id="12345"
' Returns: {"status": "delivered", "amount": 899}

When to Use Tools

✅ Perfect for:

Database queries
API calls
Calculations
Data transformations
Real-time operations

' Examples of good tool usage
USE TOOL "get-weather"
weather = CALL TOOL "get-weather" WITH city="São Paulo"

USE TOOL "calculate-tax"
tax = CALL TOOL "calculate-tax" WITH amount=100, region="BR"

USE TOOL "send-email"
CALL TOOL "send-email" WITH to="user@example.com", subject="Order Confirmed"

Tool Limitations

❌ Cannot:

Make decisions
Understand context
Remember previous calls
Handle ambiguous input
Provide explanations

Bots: The AI Agent Approach

What Are Bots?

Bots are intelligent agents that can reason, remember, and make decisions:

' Bot usage - conversational interaction
ADD BOT "order-specialist"
response = ASK BOT "order-specialist" ABOUT "Customer says order 12345 arrived damaged. What should we do?"
' Returns: Detailed analysis with reasoning and recommendation

When to Use Bots

✅ Perfect for:

Complex decision making
Natural language understanding
Multi-step reasoning
Context-aware responses
Customer service scenarios

' Examples of good bot usage
ADD BOT "financial-advisor"
advice = ASK BOT "financial-advisor" ABOUT "Customer wants refund after 60 days but threatens legal action"

ADD BOT "technical-support"  
solution = ASK BOT "technical-support" ABOUT "User can't login, tried password reset twice"

ADD BOT "content-moderator"
decision = ASK BOT "content-moderator" ABOUT "Review this user comment for policy violations"

Bot Capabilities

✅ Can:

Analyze complex situations
Remember conversation history
Use multiple tools internally
Provide detailed explanations
Handle edge cases

Real-World Example: Order Processing

Scenario

Customer contacts support: "My laptop order #12345 arrived broken. I need this fixed immediately as I have a presentation tomorrow."

Tool-Only Approach (Limited)

' Simple but inflexible
USE TOOL "check-order"
order = CALL TOOL "check-order" WITH order_id="12345"

USE TOOL "check-warranty"  
warranty = CALL TOOL "check-warranty" WITH order_id="12345"

IF order.status = "delivered" AND warranty.valid = true THEN
  TALK "You're eligible for replacement"
ELSE
  TALK "Please contact manager"
END IF

Problems:

No understanding of urgency ("presentation tomorrow")
No consideration of customer history
Rigid, rule-based responses
Cannot handle edge cases

Bot Approach (Intelligent)

' Intelligent and flexible
ADD BOT "support-specialist"
response = ASK BOT "support-specialist" ABOUT "Customer says laptop order #12345 arrived broken. They have presentation tomorrow and need immediate help."

Bot's internal reasoning:

Uses check-order tool → Order delivered 2 days ago, $1,299 laptop
Uses check-warranty tool → Premium warranty valid
Uses customer-history tool → VIP customer, 8 previous orders
Analyzes urgency → Presentation tomorrow = time-sensitive
Considers options → Replacement (2-day shipping) vs immediate refund for local purchase
Makes recommendation → "Given urgency and VIP status, authorize immediate refund so customer can buy locally, plus expedited replacement as backup"

Hybrid Approach: Best of Both Worlds

Recommended pattern: Bots use Tools internally

' support-specialist.bas - Bot implementation
USE TOOL "check-order"
USE TOOL "check-warranty"
USE TOOL "customer-history"
USE TOOL "inventory-check"
USE KB "support-policies"

WHEN ASKED ABOUT order_issue DO
  ' Gather data using tools (fast, cheap)
  order = CALL TOOL "check-order" WITH order_id
  warranty = CALL TOOL "check-warranty" WITH order_id
  customer = CALL TOOL "customer-history" WITH customer_id
  
  ' Apply AI reasoning (intelligent, contextual)
  urgency = ANALYZE urgency FROM user_message
  customer_value = CALCULATE value FROM customer.total_orders
  
  IF urgency = "high" AND customer_value = "vip" THEN
    recommendation = "Expedited resolution with manager approval"
  ELSE IF warranty.type = "premium" THEN
    recommendation = "Standard replacement process"
  ELSE
    recommendation = "Store credit or repair option"
  END IF
  
  RETURN detailed_response WITH reasoning AND next_steps
END WHEN

Performance Guidelines

Tool Performance

Latency: 10-100ms
Cost: $0 (no LLM calls)
Throughput: 1000+ operations/second
Use for: High-frequency, simple operations

Bot Performance

Latency: 1-5 seconds
Cost: $0.001-0.01 per interaction
Throughput: 10-100 interactions/second
Use for: Complex, high-value decisions

Decision Framework

Use TOOL when:

Operation is deterministic - Same input always produces same output
Speed is critical - Real-time responses needed
Cost matters - High-frequency operations
Data is structured - Clear input/output format

Use BOT when:

Context matters - Previous conversation affects response
Reasoning required - Multiple factors to consider
Natural language input - Ambiguous or conversational requests
Edge cases exist - Situations requiring judgment

Use HYBRID when:

Complex workflows - Multiple steps with decision points
Data + Intelligence - Need both fast data access and smart reasoning
Scalability important - Balance cost and capability

Common Patterns

Pattern 1: Data Retrieval

' TOOL: Simple lookup
price = CALL TOOL "get-price" WITH product_id="laptop-123"

' BOT: Contextual pricing
ADD BOT "pricing-advisor"
quote = ASK BOT "pricing-advisor" ABOUT "Customer wants bulk discount for 50 laptops, they're a returning enterprise client"

Pattern 2: Validation

' TOOL: Rule-based validation  
valid = CALL TOOL "validate-email" WITH email="user@domain.com"

' BOT: Contextual validation
ADD BOT "content-reviewer"
assessment = ASK BOT "content-reviewer" ABOUT "Is this product review appropriate for our family-friendly site?"

Pattern 3: Workflow Orchestration

' Hybrid: Bot coordinates, tools execute
ORCHESTRATE WORKFLOW "order-processing"
  STEP 1: CALL TOOL "validate-payment" WITH payment_info
  STEP 2: BOT "fraud-detector" ANALYZES transaction_pattern  
  STEP 3: CALL TOOL "reserve-inventory" WITH product_id
  STEP 4: BOT "shipping-optimizer" SELECTS best_carrier
  STEP 5: CALL TOOL "send-confirmation" WITH order_details
END WORKFLOW

Best Practices

1. Start Simple, Add Intelligence

' Phase 1: Tool-based (fast to implement)
result = CALL TOOL "process-refund" WITH order_id, amount

' Phase 2: Add bot intelligence (when complexity grows)
ADD BOT "refund-specialist"
decision = ASK BOT "refund-specialist" ABOUT "Customer wants refund but policy expired, they're threatening bad review"

2. Cache Bot Responses

' Expensive bot call
ADD BOT "product-recommender"
recommendations = ASK BOT "product-recommender" ABOUT "Best laptop for gaming under $1000"

' Cache result for similar queries
REMEMBER "gaming-laptop-under-1000" AS recommendations

3. Fallback Patterns

' Try bot first, fallback to tool
TRY
  response = ASK BOT "smart-assistant" ABOUT user_query
CATCH bot_error
  ' Fallback to simple tool
  response = CALL TOOL "keyword-search" WITH query=user_query
END TRY

Summary

Tools are your workhorses - fast, reliable, cost-effective for data operations.

Bots are your brain trust - intelligent, contextual, perfect for complex decisions.

Hybrid approach gives you the best of both: use tools for speed and bots for intelligence.

Choose based on your specific needs:

Need speed? → Tool
Need intelligence? → Bot
Need both? → Bot that uses tools

The key is understanding that tools and bots complement each other - they're not competing solutions, but different tools for different jobs in your AI automation toolkit.

Next: Chapter 5: Building Multi-Agent Workflows

9.1 KiB Raw Blame History