vibex 0.30.1
VibeX - An Opinionated Multi-Agent Framework
Requires Python: >=3.11

<div align="center">
  <img src="https://dustland.github.io/vibex/logo.png" alt="VibeX Logo" width="120">
  <h1 align="center">VibeX</h1>
</div>

<p align="center">
  <b>An open-source framework for building autonomous AI agent teams.</b>
  <br />
  <a href="https://dustland.github.io/vibex"><strong>Explore the docs »</strong></a>
  <br />
  <br />
  <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg"/></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.11+-blue.svg" /></a>
  <a href="https://github.com/dustland/vibex/actions/workflows/pypi.yaml"><img src="https://github.com/dustland/vibex/actions/workflows/pypi.yaml/badge.svg"/></a>
  <a href="https://pypi.org/project/vibex/"><img src="https://img.shields.io/pypi/v/vibex.svg" alt="PyPI version" /></a>
</p>

VibeX provides the backbone for creating, orchestrating, and observing sophisticated multi-agent systems. It moves beyond simple agent-to-agent communication to a robust, task-driven framework where teams of specialized agents collaborate to achieve complex goals.

## ✨ Key Features

Based on a refined and modular architecture, VibeX is built around a few core concepts:

- **🤖 Multi-Agent Teams**: Define teams of specialized agents in simple YAML files. Each agent can have its own role, tools, and configuration.
- **🗣️ Natural Language Orchestration**: Agents hand off tasks to each other using natural language. A central `TaskExecutor` interprets these handoffs and routes work to the appropriate agent, enabling complex, dynamic workflows.
- **🛠️ Secure & Extensible Tools**: Tools are defined with Python decorators and their schemas are automatically generated. Shell commands are executed in a secure Docker sandbox, providing safety and isolation. A flexible `ToolExecutor` manages the entire lifecycle.
- **🧠 Stateful & Context-Aware Memory**: Agents maintain long-term memory, enabling them to recall past interactions and context. The memory system supports semantic search, ensuring agents have the information they need, when they need it.
- **📡 Streamable Communication**: The entire lifecycle of a task, from agent thoughts to tool calls and results, is available as a real-time stream of events. This allows you to build rich, observable UIs like the Vercel AI SDK.
- **🎯 Task-Centric API**: Interact with the system through a simple, powerful API. Kick off complex workflows with `execute_task()` or manage interactive sessions with `start_task()`.

## 🚀 Getting Started

The best way to get started is by following our **[Getting Started](https://dustland.github.io/vibex/docs/getting-started/)**, which will walk you through building a simple chat application and a multi-agent writer/reviewer team.

### 1. Installation

Install VibeX from PyPI:

```sh
pip install vibex
```

Or for development, clone the repository:

```sh
git clone https://github.com/dustland/vibex.git
cd vibex
uv sync
```

### 2. Usage Examples

VibeX can be run directly from the command line or via its Python API. You can find complete, working examples in the `examples/` directory.

#### Running an Example

This demonstrates a basic multi-agent collaboration:

```bash
# Navigate to an example directory
cd examples/simple_team

# Run the main script
python main.py
```

#### Using the CLI

The framework includes a powerful CLI for managing your agent system:

```bash
# Bootstrap a new project with interactive wizard
vibex init

# Monitor tasks and events in your terminal
vibex monitor

# Launch the web dashboard for rich observability
vibex monitor --web

# List available tools
vibex tools list
```

#### Using the Python API

Here is a simple example of an autonomous run:

```python
import asyncio
from vibex import execute_task

async def main():
    # Execute a task with a simple prompt (completes when done)
    await execute_task(
        prompt="Write a brief report on renewable energy trends",
        config_path="config/team.yaml"
    )
    print("Task completed!")

asyncio.run(main())
```

_The script above shows a simple autonomous run. For more advanced patterns like message streaming and interactive sessions, please see the complete scripts in the `/examples` directory._

### Example Projects

- **[simple_writer](examples/simple_writer/)** - Single intelligent agent for both creative writing and market research
- **[simple_team](examples/simple_team/)** - Multi-agent writer/reviewer collaboration
- **[simple_chat](examples/simple_chat/)** - Interactive chat with an AI assistant
- **[auto_writer](examples/auto_writer/)** - Advanced multi-agent writing system

## 🔧 Development Workflow

VibeX includes a comprehensive development setup with automated tooling to ensure code quality and documentation consistency.

### Pre-commit Hooks

The project uses pre-commit hooks to automatically maintain code quality and keep documentation up-to-date:

```bash
# Set up pre-commit hooks (one-time setup)
uv run setup-hooks

# Now every commit will automatically:
# - Generate API documentation when Python files change
# - Format code and fix whitespace issues
# - Validate YAML and TOML files
# - Check for merge conflicts and large files
```

### Development Commands

```bash
# Generate API documentation
uv run docs

# Build documentation site
uv run build-docs

# Run tests
uv run test

# Run development server with auto-reload
uv run dev

# Run development server with automatic cleanup (recommended)
./scripts/dev.sh

# Monitor tasks and events
uv run monitor
```

> **💡 Tip**: Use `./scripts/dev.sh` instead of `uv run dev` to automatically kill any existing processes on port 7770 before starting the development server. This prevents "Address already in use" errors.

### API Documentation

The API documentation is automatically generated from docstrings and kept in sync with the code:

- **Source**: Python docstrings in `src/vibex/`
- **Output**: Markdown files in `docs/content/api/`
- **Automation**: Generated on every commit via pre-commit hooks

To manually regenerate API docs:

```bash
uv run docs
```

## 📊 Observability & Monitoring

VibeX includes a comprehensive observability system for monitoring and debugging multi-agent workflows.

Launch a modern web dashboard built with FastAPI and Preline UI:

```bash
# Start web dashboard
vibex monitor --web
```

- **Dashboard**: System overview with metrics and recent activity.
- **Tasks**: Task conversation history viewer with export.
- **Events**: Real-time event monitoring with filtering.
- **Memory**: Memory browser with search and categories.
- **Messages**: Agent conversation history during execution.
- **Configuration**: System configuration and status viewer.

You can also use the observability features in CLI mode without the option `--web`.

## 🛠️ Tech Stack

VibeX is built on a robust foundation of modern Python technologies:

- **[LiteLLM](https://github.com/BerriAI/litellm)** - Unified interface for 100+ LLM providers
- **[Mem0](https://github.com/mem0ai/mem0)** - Intelligent memory layer for long-term context
- **[SerpAPI](https://serpapi.com/)** - Web search capabilities for agents
- **[Crawl4AI](https://github.com/unclecode/crawl4ai)** - Open-source web content extraction with JavaScript support
- **[Browser-use](https://browser-use.com/)** - Browser automation

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## 🙏 Acknowledgments

This project was initially inspired by and built upon concepts from [AG2 (AutoGen)](https://github.com/ag2ai/ag2), an excellent multi-agent conversation framework. While VibeX has evolved into its own distinct architecture and approach, we're grateful for the foundational ideas and patterns that AG2 provided to the multi-agent AI community.

Our message system and conversation architecture draws inspiration from [Vercel AI SDK](https://github.com/vercel/ai), particularly its elegant message format with role-based structure and parts array for handling complex content types. This design pattern has proven invaluable for building robust, extensible AI applications.

This project also referred to other open-source projects such as [OpenManus](https://github.com/FoundationAgents/OpenManus), [Suna](https://github.com/Kortix-ai/Suna) and [Magic](https://github.com/dtyq/magic/) etc.

## 📄 License

Licensed under the Apache License 2.0 - see [LICENSE](LICENSE) for details.

---

**Built with ❤️ by [Dustland](https://github.com/dustland)**