Setup and Prerequisites

This guide covers the initial setup required to run Robota SDK examples.

Prerequisites

Node.js and Package Manager

Ensure you have the following installed:

• Node.js 18+
• pnpm (recommended) or npm
• bun (optional, for faster execution)

# Install pnpm if not already installed
npm install -g pnpm

# Install bun (optional, for faster TypeScript execution)
curl -fsSL https://bun.sh/install | bash

Install Dependencies

From the project root:

pnpm install

Environment Configuration

Required API Keys

Create a .env file in the project root with your API keys:

# Required for most examples
OPENAI_API_KEY=your_openai_api_key_here

# Optional - for multi-provider examples
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_API_KEY=your_google_api_key_here

Getting API Keys

OpenAI API Key

1. Visit OpenAI Platform
2. Sign up or log in to your account
3. Navigate to API Keys section
4. Create a new API key
5. Copy the key to your .env file

Anthropic API Key (Optional)

1. Visit Anthropic Console
2. Sign up or log in
3. Navigate to API Keys
4. Create a new key
5. Add to your .env file

Google AI API Key (Optional)

1. Visit Google AI Studio
2. Sign in with your Google account
3. Create a new API key
4. Add to your .env file

Directory Structure

Examples are distributed per package (SSOT ownership). There is no single shared apps/examples folder.

robota/
├── docs/examples/          # This documentation
└── packages/               # SDK packages
    ├── agents/
    │   └── examples/       # @robota-sdk/agent-core examples
    ├── openai/
    │   └── examples/       # @robota-sdk/agent-provider-openai examples
    ├── team/
    │   └── examples/       # @robota-sdk/agent-team examples

Running Examples

Method 1: Direct Execution (Recommended)

# Build packages first (recommended)
pnpm build

# Run a package-owned example from the repo root
pnpm tsx packages/agents/examples/basic-conversation.ts

Verification

Test your setup with the simplest example:

pnpm tsx packages/agents/examples/basic-conversation.ts

Expected output:

===== Simple Conversation Example =====
Response: [AI response about TypeScript]

===== Streaming Response Example =====
Response: [Streaming AI response about TypeScript advantages]

Troubleshooting Setup Issues

Common Problems

1. Missing Dependencies

# Reinstall dependencies
rm -rf node_modules package-lock.json
pnpm install

2. API Key Issues

• Verify API keys are correctly set in .env
• Check for extra spaces or quotes around keys
• Ensure .env is in the project root, not in examples directory

3. TypeScript Execution Errors

# Install tsx globally if needed
pnpm add -g tsx

# Or use npx
npx tsx 01-basic/01-simple-conversation.ts

4. Module Resolution Issues

# Build packages first
pnpm build

Getting Help

If you encounter issues:

1. Check the specific example documentation
2. Verify your environment configuration
3. Ensure all dependencies are installed
4. Check the console for specific error messages

Next Steps

Once setup is complete, explore the examples:

1. Start with Basic Conversation
2. Try AI with Tools
3. Explore Multi-Provider Setup

Environment Variables Reference

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI API key for GPT models
ANTHROPIC_API_KEY	No	Anthropic API key for Claude models
GOOGLE_API_KEY	No	Google AI API key for Gemini models

Examples should fail fast when required environment variables are missing.