Contributing to WebAgents

Thank you for your interest in contributing to WebAgents! This guide will help you get started.

Getting Started

Prerequisites

Node.js 20+ and pnpm 9.x (TypeScript SDK)

Python 3.10+ (Python SDK)

Git and a GitHub account

Development Environment Setup

Fork & clone

git clone https://github.com/YOUR_USERNAME/webagents.git
cd webagents

Install the SDK you're working on

corepack enable
cd webagents/typescript
pnpm install

Set up environment variables (.env in project root):

OPENAI_API_KEY=your-openai-api-key
ROBUTLER_API_KEY=rok_your-robutler-api-key

Verify the setup

pnpm test
pnpm run lint
pnpm run typecheck

Development Workflow

1. Create a Branch

Always create a new branch for your work:

git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

2. Make Your Changes

Write clean, readable code

Follow the existing code style

Add tests for new functionality

Update documentation as needed

3. Test Your Changes

pnpm test
pnpm test -- --coverage
pnpm test src/agents/__tests__/base-agent.test.ts
pnpm run lint
pnpm run typecheck

4. Commit Your Changes

We use conventional commits for clear commit messages:

git add .
git commit -m "feat: add new agent configuration option"
# or
git commit -m "fix: resolve payment processing error"
# or
git commit -m "docs: update API documentation"

Commit types:

feat: New features

fix: Bug fixes

docs: Documentation changes

style: Code style changes (formatting, etc.)

refactor: Code refactoring

test: Adding or updating tests

chore: Maintenance tasks

5. Push and Create a Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub with:

Clear title and description

Reference to any related issues

Screenshots or examples if applicable

Code Style Guidelines

// 2-space indent, ES modules, no `any` in public APIs.
// Public symbols carry TSDoc comments. Use Prettier + ESLint configs from the repo.
export interface ExampleConfig {
  /** Display name. */
  name: string;
  /** Optional runtime overrides. */
  options?: Record<string, unknown>;
}

export class ExampleClass {
  constructor(private readonly config: ExampleConfig) {}

  /**
   * Count occurrences of each item.
   * @throws if `items` is empty.
   */
  processItems(items: string[]): Record<string, number> {
    if (items.length === 0) {
      throw new Error('Items list cannot be empty');
    }
    return items.reduce<Record<string, number>>((acc, item) => {
      acc[item] = (acc[item] ?? 0) + 1;
      return acc;
    }, {});
  }
}

Documentation Style

TypeScript: TSDoc comments on public exports.

Python: Google-style docstrings with type hints.

Provide examples for non-trivial behavior.

Keep documentation up to date with code changes.

Testing Guidelines

Writing Tests

Write tests for all new functionality

Use descriptive test names

Follow the Arrange-Act-Assert pattern

Use fixtures for common test data

Example test:

import { describe, it, expect } from 'vitest';
import { BaseAgent, Skill, tool } from 'webagents';

class TestSkill extends Skill {
  readonly name = 'test';

  @tool({ description: 'Returns a fixed result' })
  async testTool(): Promise<string> {
    return 'test result';
  }
}

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

    expect(agent.name).toBe('test-agent');
    expect(agent.instructions).toBe('You are a helpful assistant.');
  });

  it('registers skill tools', () => {
    const agent = new BaseAgent({
      name: 'tool-agent',
      instructions: 'You have tools.',
      skills: [new TestSkill()],
    });

    expect(agent.skills.length).toBe(1);
  });
});

Running Tests

pnpm test
pnpm test src/agents/__tests__/base-agent.test.ts
pnpm test -- --coverage
pnpm test -- -t "agent"

Contributing Areas

Areas Where We Need Help

Agent Tools: New tools that extend agent capabilities

Documentation: Improving guides and API documentation

Testing: Adding test coverage for existing functionality

Bug Fixes: Resolving reported issues

Performance: Optimizing agent response times

Examples: Creating example applications and use cases

Feature Requests

Before implementing new features:

Check existing issues: See if the feature is already requested

Create an issue: Discuss the feature with maintainers first

Get approval: Wait for maintainer approval before starting work

Follow guidelines: Use this contributing guide for implementation

Getting Help

Issues: Check GitHub Issues for existing problems

Discussions: Use GitHub Discussions for questions

Discord: Join our community Discord for real-time help

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Thank you for contributing to WebAgents!

On this page