Robota SDK Guide

This is archived documentation for Robota SDK v2.0.0. For the latest version, see the current documentation.

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/agent-core
• ⚡ 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
• 🧰 assignTask Tool Collection: MCP-style task assignment tools (no team creation APIs)
• 🧠 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/agent-core (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
• assignTask Tool Collection - MCP-style task assignment tools

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

🧰 assignTask Tool Collection (team package)

import {
  createAssignTaskRelayTool,
  listTemplatesTool,
  getTemplateDetailTool,
} from '@robota-sdk/agent-team';
import { Robota } from '@robota-sdk/agent-core';
import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';

const openaiProvider = new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY });

const tools = [
  listTemplatesTool,
  getTemplateDetailTool,
  createAssignTaskRelayTool({ emit: () => undefined } as any), // caller must inject ownerPath-bound eventService in real flows
];

const agent = new Robota({
  name: 'Assistant',
  aiProviders: [openaiProvider],
  defaultModel: { provider: 'openai', model: 'gpt-4' },
  tools,
});

const result = await agent.run('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/agent-core
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