agents-playground/README.md

Interactive web UI for testing and developing AI agents built with agents-js

# 🎮 agents-playground

Interactive web UI for testing and developing AI agents built with [agents-js](https://github.com/vgulerianb/agents-js).

## Installation

```bash
npm install -g agents-playground
```

Or use directly with npx:

```bash
npx agents-playground ./my-agents.js
```

## Usage

### Basic Usage

```bash
agents-playground ./path/to/your/agents.js
```

### Your Agent File

Your agent file must export agents via `module.exports`:

```javascript
const { Agent } = require('agents-js');

const myAgent = new Agent({
  name: "MyAgent",
  model: "gpt-4o-mini",
  instructions: "You are a helpful assistant.",
  functions: [/* your tools */],
});

// Export for playground
module.exports = { myAgent };
```

### With Multiple Agents

```javascript
const coordinator = new Agent({
  name: "Coordinator",
  instructions: "Route requests to specialists",
  subAgents: [specialist1, specialist2],
});

module.exports = { coordinator, specialist1, specialist2 };
```

## Features

### 🎨 Modern UI
- Clean, professional interface inspired by leading developer tools
- Responsive design that works on desktop and mobile
- Real-time updates and smooth animations

### 🤖 Agent Management
- **Smart Selection**: Automatically selects the agent with most sub-agents
- **Easy Switching**: Change agents mid-conversation
- **Agent Details**: View tools, sub-agents, and configuration

### 📊 Development Tools
- **Detailed Logs**: Track which agents and tools were used
- **Token Tracking**: Monitor costs and usage in real-time
- **Session Management**: Persistent chat history
- **Environment Management**: Set API keys on-the-fly

### 🔧 Developer Features
- Hot reload support
- Environment variable configuration
- Cost calculation
- Performance metrics

## Examples

### Basic Agent

```bash
# Create a simple agent file
cat > my-agent.js << 'EOF'
const { Agent } = require('agents-js');
const { serperSearch, calculate } = require('agents-js/tools');

const agent = new Agent({
  name: "Assistant",
  model: "gpt-4o-mini",
  instructions: "You are a helpful assistant with web search and calculation capabilities.",
  functions: [serperSearch, calculate],
});

module.exports = { agent };
EOF

# Launch playground
npx agents-playground my-agent.js
```

### Multi-Agent System

```bash
npx agents-playground node_modules/agents-js/examples/multi-agent-system.js
```

## Configuration

### Environment Variables

Set these in your `.env` file or via the UI:

```env
OPENAI_API_KEY=your-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
SERPER_API_KEY=your-serper-key
FIRECRAWL_API_KEY=your-firecrawl-key
```

### Custom Port

```bash
PORT=8080 agents-playground ./my-agents.js
```

## Requirements

- Node.js >= 14.0.0
- agents-js >= 0.1.0

## License

MIT © Vikrant Guleria

## Links

- [agents-js](https://github.com/vgulerianb/agents-js) - Core library
- [Documentation](https://github.com/vgulerianb/agents-js#readme)
- [Issues](https://github.com/vgulerianb/agents-js/issues)