Development Setup

This guide covers setting up a development environment for working on the WebAgents SDKs.

Prerequisites

Node.js: 20 LTS or higher (TypeScript SDK)

pnpm: 9.x — used by the monorepo (TypeScript SDK)

Python: 3.10 or higher (Python SDK)

Git: Latest version

OpenAI API Key (or another LLM provider key): For agent functionality

Environment Setup

1. Clone the Repository

# Clone the repository
git clone https://github.com/robutlerai/robutler.git
cd robutler-proxy

# Or clone your fork
git clone https://github.com/YOUR_USERNAME/robutler.git
cd robutler-proxy

2. Set up the toolchain

# Install pnpm if missing
corepack enable
corepack prepare pnpm@latest --activate

cd webagents/typescript
pnpm install

3. Environment Variables

Create a .env file in the project root:

# Required for agent functionality
OPENAI_API_KEY=your-openai-api-key

# Optional Robutler platform configuration
ROBUTLER_API_KEY=rok_your-robutler-api-key
ROBUTLER_API_URL=https://robutler.ai

# Development settings
WEBAGENTS_DEBUG=true

Development Tools

Lint & Format

pnpm run lint
pnpm run format
pnpm run typecheck

Testing

# Run unit tests
pnpm test

# Watch mode
pnpm test -- --watch

# Coverage
pnpm test -- --coverage

Documentation

# Fumadocs (Next.js portal)
pnpm --filter portal dev

# MkDocs (external publishing)
cd webagents
mkdocs serve

Running the Development Server

import { BaseAgent } from 'webagents';
import { serve } from 'webagents/server/node';

const agent = new BaseAgent({
  name: 'test-agent',
  instructions: 'You are a helpful test assistant.',
  model: 'openai/gpt-4o-mini',
});

await serve(agent, { host: '127.0.0.1', port: 8000 });

Common Development Tasks

Adding a New Tool

import { Skill, tool, pricing } from 'webagents';

class MySkill extends Skill {
  readonly name = 'my-skill';

  @pricing({ creditsPerCall: 0.001 })
  @tool({ description: 'Process input text' })
  async myNewTool(params: { inputText: string }): Promise<string> {
    return `Processed: ${params.inputText}`;
  }
}

Testing the Endpoint

curl -X POST http://localhost:8000/test-agent/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "test-agent", "messages": [{"role": "user", "content": "Hello"}]}'

Debugging

Enable Debug Logging

process.env.WEBAGENTS_DEBUG = 'true';
process.env.DEBUG = 'webagents:*';

Or set the environment variable globally:

export WEBAGENTS_DEBUG=true

This covers the essential development setup for contributing to the WebAgents SDKs.

On this page