🚀 AGI SDK (JavaScript/TypeScript)

📄 Paper • 📝 Blog • 🏢 AGI Inc • 🏆 Leaderboard • 📚 API Docs • 💡 Examples

Build, evaluate, and level up your AI agents for the real web.

---

✨ What is AGI SDK?

AGI SDK is a production-ready toolkit for building and evaluating AI browser agents in real-world environments.

It powers REAL Bench: a high-fidelity benchmark for AI agents navigating modern websites like Amazon, DoorDash, Airbnb, and more.

🔹 Train agents to browse and interact with real apps 🔹 Benchmark agents with robust, standardized tasks 🔹 Submit to the leaderboard and see how your agents stack up!

Features:

• ✅ Full TypeScript support with complete type definitions
• ✅ Built-in LLM agent (OpenAI, Anthropic, OpenRouter)
• ✅ 140+ bundled real-world tasks across 11 website clones
• ✅ Flexible custom agent API
• ✅ Production-ready with comprehensive documentation
• ✅ Leaderboard integration for benchmarking

🛠️ Installation

# Install the SDK
npm install @theagicompany/agisdk

# Install Playwright browser dependencies
npx playwright install --force

# Set your LLM API key (for LLM-based agents)
export OPENAI_API_KEY="your-api-key"   # or ANTHROPIC_API_KEY, etc.

✅ Supports OpenAI, Anthropic, OpenRouter, and custom models!

⚡ Quick Start

Using the Built-in Agent

import { REAL } from '@theagicompany/agisdk';

// Set your API key
process.env.OPENAI_API_KEY = 'your-api-key';

// Create agent with built-in LLM
const agent = new REAL.DemoAgent({
    modelName: 'gpt-4o',
    useAxtree: true,
    useScreenshot: true,
});

// Create harness
const harness = new REAL.Harness({
    agent,
    taskName: 'v2.omnizon-1',
    headless: false,
});

// Run task
const results = await harness.run();
console.log(results);

Building a Custom Agent

import { REAL } from '@theagicompany/agisdk';

class MyAgent implements REAL.Agent {
    async getAction(obs: REAL.Observation): Promise<string> {
        // Your custom logic here
        if (obs.url?.includes('product')) {
            return "click('add-to-cart')";
        }
        return "send_msg_to_user('Task complete')";
    }
}

const harness = new REAL.Harness({
    agent: new MyAgent(),
    taskName: 'v2.omnizon-1',
});

const results = await harness.run();

See examples/ for more detailed examples.

🔥 Features

• Full-stack web replicas of top real-world apps (Amazon, Uber, Gmail, Airbnb, etc.)
• Robust agent API: Observations, Actions, Memory, Errors
• Built-in LLM agent supporting OpenAI, Anthropic, and OpenRouter
• Customizable harness: plug your own agents
• TypeScript support: Full type definitions included
• Bundled tasks: All tasks included in package (no external dependencies)

🌐 Available Tasks

The AGI SDK includes high-fidelity, fully-deterministic websites for agents to explore:

App Clone	Task Prefix	Example Use Case
🛒 Amazon → Omnizon	v2.omnizon-*	Buy a laptop, find a gift
🍔 DoorDash → DashDish	v2.dashdish-*	Order dinner
✈️ United → FlyUnified	v2.flyunified-*	Book a flight
🏡 Airbnb → Staynb	v2.staynb-*	Reserve accommodation
📅 Google Calendar → GoCalendar	v2.gocalendar-*	Schedule a meeting
📬 Gmail → GoMail	v2.gomail-*	Compose an email
🍽️ OpenTable → OpenDining	v2.opendining-*	Book a restaurant
👔 LinkedIn → NetworkIn	v2.networkin-*	Accept a connection
🚗 Uber → Udriver	v2.udriver-*	Book a ride
💼 UpWork → TopWork	v2.topwork-*	Find a freelance gig
🏠 Zillow → Zilloft	v2.zilloft-*	Browse houses

📚 Documentation

Comprehensive documentation is available:

• API Reference - Complete API documentation for all classes and methods
• Task Guide - Understanding tasks, evaluation, and task configuration
• Agent Guide - Building custom agents and understanding DemoAgent
• Examples - Working examples with detailed explanations
• Contributing - Guidelines for contributing to the project
• Changelog - Version history and release notes

📖 Learning Resources

• New to the SDK? Start with example/starter.ts
• Building a custom agent? See example/custom.ts
• Want advanced features? Check out example/hackable.ts
• Submitting to leaderboard? Follow example/leaderboard.ts

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Ways to contribute:

• 📢 Feature requests and ideas
• 🐛 Bug reports and fixes
• 📝 Documentation improvements
• 💡 New examples and tutorials
• 🧪 Test coverage improvements

Development setup:

git clone https://github.com/agi-inc/agisdk-js.git
cd agisdk-js
npm install
npm run build

See CONTRIBUTING.md for detailed guidelines.

💬 Community & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: AGI Inc
• Leaderboard: REAL Bench

🌟 Show Your Support

If you find this project useful, please consider:

• ⭐ Starring the repository
• 🐦 Sharing on social media
• 📝 Writing about your experience
• 🤝 Contributing to the project

📄 License

Apache 2.0 - see LICENSE file for details.