Development Documentation

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

Comprehensive development guides for the Robota SDK v2.0.

Project Overview

The Robota SDK v2.0 is a unified TypeScript library for building AI agents with:

• 🔥 Unified Architecture: Everything consolidated in @robota-sdk/agent-core
• ⚡ Type-Safe Design: Zero any types, complete TypeScript safety
• 🔌 Multi-Provider Support: OpenAI, Anthropic, Google AI with seamless switching
• 📊 Built-in Analytics: Performance monitoring and usage tracking
• 🛠️ Advanced Tools: Type-safe function calling and tool integration

Quick Navigation

🚀 Getting Started

• Development Principles - Core principles and architecture
• TypeScript Standards - Type safety standards and zero any policy

🏗️ Development Process

• Development Workflow - Code quality processes and guidelines
• Testing Guidelines - Testing strategies and best practices
• Build and Deployment - Build configuration and deployment

📚 Standards & Guidelines

• Documentation Guidelines - Documentation standards
• Error Handling Guidelines - Error handling strategies
• Logging Configuration - Logging setup and practices

⚡ Performance & Architecture

• Performance Optimization - Performance best practices
• Code Improvements - Architecture patterns and refactoring

🚢 Infrastructure

• Package Publishing - Release workflow and guidelines
• Documentation Site Setup - Documentation site management

🧪 SSOT Tooling

• Duplicate Declaration Scanner: scripts/audit/output/ssot-duplicate-declarations-v3.json
• Alias Cleanup: Policy enforcement for type A = B and same-shape redefinitions
• Scanner Classification: Same-kind vs contract+implementation pair grouping (v3)
• Naming Hygiene: Removal of redundant Interface/Type/TypeSafe naming patterns

📚 API Reference Generation

• Generation Command Header: Auto-generated API docs include the generating command.

✅ Process Updates

• Rules-to-skills migration completed; guidance is now consolidated under .agents/skills/.

Development Workflow

1. Setup Development Environment

# Clone the repository
git clone https://github.com/jungyoun-organisation/robota.git
cd robota

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

2. Development Commands

# Development mode (watch for changes)
pnpm dev

# Type checking
pnpm type-check

# Linting
pnpm lint

# Format code
pnpm format

# Run examples
npx tsx packages/agents/examples/basic-conversation.ts

3. Testing

# Run all tests
pnpm test

# Run tests with coverage
pnpm test:coverage

# Run specific package tests
cd packages/agents
pnpm test

Architecture Overview

Unified Package Structure

@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

Supporting Packages

@robota-sdk/agent-provider-openai         # OpenAI provider implementation
@robota-sdk/agent-provider-anthropic      # Anthropic provider implementation
@robota-sdk/agent-provider-google         # Google AI provider implementation
@robota-sdk/agent-team           # assignTask MCP tool collection (team creation removed)
@robota-sdk/agent-sessions       # Session management

Key Development Principles

1. Type Safety First

Zero Any/Unknown Policy: Complete elimination of any and unsafe unknown types

// ✅ Good: Fully typed
interface AgentConfig {
  name: string;
  model: string;
  provider: 'openai' | 'anthropic' | 'google';
  aiProviders: Record<string, BaseAIProvider>;
}

// ❌ Bad: Any types (forbidden)
interface BadConfig {
  providers: any; // Never allowed
  options: any; // Always type explicitly
}

2. Plugin-First Architecture

// Extensible through plugins
const agent = new Robota({
  plugins: [new ExecutionAnalyticsPlugin(), new ConversationHistoryPlugin(), new LoggingPlugin()],
});

3. Provider Agnostic Design

// Seamless provider switching
agent.setModel({ provider: 'openai', model: 'gpt-4' });
agent.setModel({ provider: 'anthropic', model: 'claude-3-sonnet' });
agent.setModel({ provider: 'google', model: 'gemini-1.5-flash' });

Contribution Guidelines

1. Code Quality Standards

• TypeScript: Use strict TypeScript configuration
• No Any Types: Zero any types policy enforced
• Testing: Comprehensive test coverage required
• Documentation: Document all public APIs

2. Pull Request Process

1. Fork the repository
2. Create feature branch from main
3. Implement changes with tests
4. Update documentation if needed
5. Submit pull request with clear description

3. Commit Message Format

type(scope): description

feat(agents): add streaming support to BaseAgent
fix(openai): resolve token count calculation
docs(examples): update getting started guide
test(agents): add unit tests for plugin system

Testing Strategy

Unit Tests

// Example test structure
describe('Robota Agent', () => {
  let agent: Robota;

  beforeEach(() => {
    agent = createTestAgent();
  });

  afterEach(async () => {
    await agent.destroy();
  });

  it('should handle basic conversation', async () => {
    const response = await agent.run('Hello');
    expect(response).toBeDefined();
    expect(typeof response).toBe('string');
  });
});

Integration Tests

// Test real provider integration
describe('Provider Integration', () => {
  it('should work with OpenAI provider', async () => {
    const provider = new OpenAIProvider({ apiKey: 'test-key' });
    const agent = new Robota({
      name: 'TestAgent',
      aiProviders: [provider],
      defaultModel: {
        provider: 'openai',
        model: 'gpt-3.5-turbo',
      },
    });

    const response = await agent.run('Test message');
    expect(response).toBeTruthy();
  });
});

Release Process

1. Version Bumping

# Create changeset
pnpm changeset

# Version packages
pnpm changeset version

# Publish packages
pnpm changeset publish

2. Documentation Updates

• Update API documentation
• Update examples
• Update migration guides
• Test documentation site

Troubleshooting

Common Issues

1. Build Failures: Check TypeScript configuration
2. Test Failures: Verify mock setup and cleanup
3. Type Errors: Ensure no any types used
4. Package Conflicts: Clear node_modules and reinstall

Debug Commands

# Clean build
pnpm clean && pnpm build

# Verbose test output
pnpm test --verbose

# Type check specific package
cd packages/agents && pnpm type-check

Resources

Documentation

• Getting Started - User-facing quick start
• Core Concepts - Architecture overview
• API Reference - Complete API documentation

Development Tools

• TypeScript: Type safety and IntelliSense
• Vitest: Fast unit test runner
• ESLint: Code quality and style enforcement
• Prettier: Code formatting
• Changeset: Version management and changelogs

Community

• GitHub Issues: Bug reports and feature requests
• Discussions: Community support and questions
• Examples: Package-owned usage patterns in packages/*/examples

Migration from v1.x

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 Code Improvements for detailed migration guide.