Robota SDK Guide

Comprehensive guide to building AI agents with the Robota SDK.

What is Robota SDK?

Robota SDK is a TypeScript-first library for building sophisticated AI agents with:

• 🔥 Unified Architecture: Everything you need in @robota-sdk/agents
• ⚡ Type-Safe: Zero any types, complete TypeScript safety
• 🔌 Multi-Provider: OpenAI, Anthropic, Google AI with seamless switching
• 🛠️ Advanced Tools: Type-safe function calling and tool integration
• 📊 Built-in Analytics: Performance monitoring and usage tracking
• 🌊 Real-time Streaming: Streaming responses across all providers
• 🤝 Team Collaboration: Multi-agent workflows and task assignment
• 🧠 Future Planning: Advanced planning strategies on the roadmap

Architecture Overview

The Robota SDK v2.0 is built around a unified agents package that includes:

@robota-sdk/agents (Core Package)
├── 🤖 BaseAgent           # Foundation for all agents
├── 🔌 BaseAIProvider      # Multi-provider abstraction
├── 🛠️ BaseTool            # Tool system foundation
├── 📊 Plugin System       # Extensible plugin architecture
├── 🏭 AgentFactory        # Agent creation and templates
├── 📈 Analytics           # Performance and usage tracking
└── 🔧 Utilities           # Type-safe utilities

Learning Path

1. 🚀 Getting Started

Perfect for: First-time users, quick prototypes

Start here to create your first AI agent and understand basic concepts.

• Getting Started - Installation, setup, and first agent
• Basic Examples - Simple conversation patterns

2. 🧠 Core Concepts

Perfect for: Understanding the architecture, building robust applications

Learn the fundamental concepts and architecture patterns.

• Core Concepts - Architecture and design patterns
• Architecture Guide - Complete architecture overview and extension guide
• Building Agents - Agent development best practices

3. 🛠️ Advanced Features

Perfect for: Complex applications, production deployments

Master advanced features like tools, streaming, and analytics.

• Function Calling - Tool integration and custom functions
• Multi-Provider - Provider switching and management
• Team Collaboration - Multi-agent workflows

4. 🏗️ Production Ready

Perfect for: Production deployments, enterprise applications

Learn about monitoring, error handling, and deployment strategies.

• Performance Monitoring - Analytics and monitoring
• Error Handling - Robust error handling
• Development Guidelines - Best practices and standards

Key Features Deep Dive

Type-Safe Architecture

// Zero 'any' types - complete TypeScript safety
const agent = new Robota({
    name: 'TypeSafeAgent',
    aiProviders: [openaiProvider],
    defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo',
        systemMessage: 'You are a helpful assistant.'
    }
});

Multi-Provider Support

// Switch between providers seamlessly
agent.setModel({ provider: 'anthropic', model: 'claude-3-haiku-20240307' });
agent.setModel({ provider: 'openai', model: 'gpt-4' });
agent.setModel({ provider: 'google', model: 'gemini-1.5-flash' });

Advanced Plugin System

// Extensible plugin architecture
const agent = new Robota({
    name: 'PluginAgent',
    aiProviders: [openaiProvider],
    defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo'
    },
    plugins: [
        new ExecutionAnalyticsPlugin(),
        new ConversationHistoryPlugin(),
        new LoggingPlugin()
    ]
});

Real-time Streaming

// Streaming responses with full type safety
const stream = agent.runStream('Explain quantum computing');
for await (const chunk of stream) {
    process.stdout.write(chunk); // Type-safe streaming
}

Quick Reference

Essential Classes

• Robota - Main agent class
• AgentFactory - Create agents from templates
• ExecutionAnalyticsPlugin - Performance monitoring
• ConversationHistoryPlugin - Conversation management

AI Providers

• OpenAIProvider - GPT models (3.5, 4, 4o-mini)
• AnthropicProvider - Claude models (Haiku, Sonnet, Opus)
• GoogleProvider - Gemini models (1.5 Flash, Pro)

Tool System

• createFunctionTool - Create type-safe tools
• ToolRegistry - Manage and organize tools
• MCP Integration - Model Context Protocol support

Examples by Use Case

🤖 Simple AI Assistant

const assistant = new Robota({
    name: 'Assistant',
    aiProviders: [openaiProvider],
    defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo',
        systemMessage: 'You are a helpful assistant.'
    }
});

🔧 AI with Tools

const toolAgent = new Robota({
    name: 'ToolAgent',
    aiProviders: [openaiProvider],
    defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo',
        systemMessage: 'You have access to calculation and weather tools.'
    },
    tools: [calculatorTool, weatherTool]
});

📊 Monitored AI Agent

const monitoredAgent = new Robota({
    name: 'MonitoredAgent',
    aiProviders: [openaiProvider],
    defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo',
        systemMessage: 'You are monitored for performance.'
    },
    plugins: [new ExecutionAnalyticsPlugin()]
});

🤝 Team of Agents

import { createTeam } from '@robota-sdk/team';

const team = await createTeam({
    aiProviders: [openaiProvider, anthropicProvider],
    maxMembers: 5,
    debug: true
});

// Team intelligently delegates to specialist agents
const result = await team.execute(
    'Research and write about renewable energy trends'
);

🧠 Future: Advanced Planning

Coming soon - sophisticated planning strategies for complex autonomous workflows:

// Future roadmap - Advanced Planning System
import { createPlanner } from '@robota-sdk/planning';
import { ReActPlanner, CAMELPlanner } from '@robota-sdk/planner-strategies';

// This is planned for future releases
const planner = createPlanner({
    strategies: [new ReActPlanner(), new CAMELPlanner()],
    executionMode: 'adaptive'
});

await planner.execute('Build a complete web application');

Best Practices

✅ Do

• Use TypeScript for full type safety
• Implement proper error handling with try/catch
• Monitor performance with analytics plugins
• Clean up resources with agent.destroy()
• Use specific models for specific tasks

❌ Don't

• Ignore TypeScript errors or use any types
• Forget to handle API rate limits
• Skip error handling in production
• Leave agents running without cleanup
• Use overpowered models for simple tasks

Migration Guide

From v1.x to v2.0

The major changes in v2.0:

1. Unified Package: Everything moved to @robota-sdk/agents
2. API Changes: systemPrompt → systemMessage, close() → destroy()
3. Type Safety: Complete removal of any types
4. Plugin System: New extensible architecture

See Migration Guide for detailed upgrade steps.

Next Steps

Ready to build your first agent? Start with:

1. Getting Started - Set up your development environment
2. Basic Examples - Follow along with working code
3. API Reference - Explore the complete API

Need help? Check out our Development Guide for contributing and advanced development topics.

Documentation Sections

• Getting Started - Quick setup and basic usage
• Core Concepts - Understanding the Manager pattern architecture
• Function Calling - Tool integration and function calling
• Building Agents - Advanced agent development patterns

Quick Navigation

Use the navigation on the left to explore the complete documentation or jump straight to:

• Getting Started - Begin with basic setup
• Architecture Overview - Understand the Manager pattern
• Examples - See real-world usage patterns