dispatch-agent

# Dispatch — Autonomous AI Task Engine

> **Dispatch tasks. AI handles the rest.**

Dispatch is a production-grade autonomous AI agent built on [LangGraph](https://langchain-ai.github.io/langgraph/). It accepts a natural-language task and a success criteria, then autonomously browses the web, executes code, searches, and manages files — looping until an evaluator agent confirms the work is done.

---

## Features

- **Autonomous worker–evaluator loop** — the worker executes the task; a separate evaluator scores the result against your criteria and either accepts or sends feedback for another attempt
- **Rich tool suite** — Playwright web browsing, Python REPL, file management, Google Serper web search, Wikipedia
- **Multi-session** — each browser tab gets its own isolated agent session
- **Config-driven tool toggles** — enable or disable any tool via environment variables; no code changes needed
- **Push notifications** via [Pushover](https://pushover.net) when a long task completes
- **Structured logging** — rotating file + stderr, DEBUG level to file
- **Retry logic** — automatic exponential backoff on transient LLM API failures
- **Async throughout** — fully `async/await` from UI to LLM calls

---

## Architecture

```
Gradio UI
    │
    └── SessionManager (one DispatchAgent per user session)
            │
            └── DispatchAgent
                    │
                    └── LangGraph workflow
                            ┌───────────────────────────────┐
                            │  START → worker               │
                            │     ↓ (tool calls?)           │
                            │  tools → worker (loop)        │
                            │     ↓ (text reply)            │
                            │  evaluator                    │
                            │     ↓ (criteria met?)         │
                            │  END  ──or──  worker (retry)  │
                            └───────────────────────────────┘
```

---

## Quickstart

### 1. Clone and install

```bash
git clone https://github.com/neerajaanil/dispatch-agent.git
cd dispatch
pip install -r requirements.txt
playwright install chromium
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env — at minimum set OPENAI_API_KEY
```

### 3. Run

```bash
python app.py
# or
dispatch run
```

Open `http://localhost:7860` in your browser.

---

## Configuration

All settings use the `DISPATCH_` prefix and can be set in `.env` or as environment variables.

| Variable | Default | Description |
|---|---|---|
| `OPENAI_API_KEY` | *(required)* | OpenAI API key |
| `DISPATCH_WORKER_MODEL` | `gpt-4o-mini` | LLM for the worker agent |
| `DISPATCH_EVALUATOR_MODEL` | `gpt-4o-mini` | LLM for the evaluator |
| `DISPATCH_MAX_ITERATIONS` | `10` | Max worker iterations before forcing a stop |
| `DISPATCH_ENABLE_BROWSER` | `true` | Playwright web browsing |
| `DISPATCH_HEADLESS_BROWSER` | `true` | Run browser headlessly |
| `DISPATCH_ENABLE_FILE_TOOLS` | `true` | Read/write files in `sandbox/` |
| `DISPATCH_ENABLE_CODE_EXECUTION` | `true` | Python REPL |
| `DISPATCH_ENABLE_SEARCH` | `false` | Google Serper + Wikipedia (requires `SERPER_API_KEY`) |
| `DISPATCH_ENABLE_NOTIFICATIONS` | `false` | Pushover push notifications |
| `SERPER_API_KEY` | — | [Serper](https://serper.dev) API key |
| `DISPATCH_PUSHOVER_USER` | — | Pushover user key |
| `DISPATCH_PUSHOVER_TOKEN` | — | Pushover app token |

---

## Programmatic usage

```python
import asyncio
from dispatch import DispatchAgent

async def main():
    async with DispatchAgent() as agent:
        history = await agent.run(
            message="What are the top 3 trending Python repos on GitHub today?",
            success_criteria="Include repo name, stars, and a one-line description for each.",
            history=[],
        )
    for msg in history:
        print(f"[{msg['role']}] {msg['content']}\n")

asyncio.run(main())
```

---

## Development

```bash
pip install -e ".[dev]"
pytest
```

---

## Commercial Applications

| Use case | How |
|---|---|
| Research automation | Dispatch long-running web research tasks; get a push notification when done |
| Code generation & testing | Describe requirements; agent writes, validates, and saves to `sandbox/` |
| Data gathering pipelines | Browse + scrape + summarise across many pages autonomously |
| Internal tooling | Wrap with your own tools for domain-specific automation |
| SaaS wrapper | `SessionManager` already supports multi-user; add auth and billing |

---

## License

MIT