---
title: "Workstreams"
source: "https://docs.vertesiahq.com/agent-runner/workstreams"
markdown: "https://docs.vertesiahq.com/llms/agent-runner/workstreams.md"
---

# Workstreams

Workstreams are **non-blocking parallel sub-agents** that run independently alongside the parent agent. They enable agents to delegate research, analysis, computation, or authoring tasks to dedicated child agents that execute concurrently — dramatically speeding up complex multi-part work.

Workstreams replace the legacy `execute_parallel_work_streams` tool with a more flexible, non-blocking architecture. The parent agent continues working while children execute in the background.

## How It Works

```
Parent Agent
    |
    |-- launch_workstream("research_market")  --> Child Agent 1 (running)
    |-- launch_workstream("analyze_data")     --> Child Agent 2 (running)
    |-- launch_workstream("draft_report")     --> Child Agent 3 (running)
    |
    |   (parent continues working or waits)
    |
    |<-- workstream_completed signal <-- Child Agent 1 (done)
    |<-- workstream_completed signal <-- Child Agent 2 (done)
    |<-- workstream_completed signal <-- Child Agent 3 (done)
    |
    v
  Synthesize results
```

1. The parent calls `launch_workstream` — it returns **immediately** with a `launch_id`.
2. A child workflow starts in the background as a separate Temporal workflow.
3. The child communicates progress back to the parent via Temporal signals.
4. When the child completes, the parent receives a system message with the result summary.
5. Artifacts created by the child are automatically merged into the parent's workspace.

## When to Use Workstreams

**Use workstreams when:**
- The task can be decomposed into **independent subtasks** (e.g., research + analysis + drafting)
- You need **multiple perspectives** on the same topic (Expert Roundtable pattern)
- A subtask would be a **digression** from the main conversation flow
- You want to **parallelize** work that would otherwise be sequential

**Use sequential execution when:**
- Tasks have **strict dependencies** (output of A is input to B)
- The task is simple enough to complete **inline** in a single step
- You need **tight control** over every step of the process

## Workstream Lifecycle

Each workstream progresses through these states:

```
launched --> running --> completed
                    |-> failed
                    |-> timeout
                    |-> canceled (via terminate_workstream)
```

| State | Description |
|-------|-------------|
| `running` | Sub-agent is actively executing tools and reasoning |
| `canceling` | Termination requested; awaiting graceful shutdown (60-second grace period) |
| `completed` | Finished successfully — summary and artifacts available |
| `failed` | Encountered an unrecoverable error |
| `timeout` | Exceeded its deadline and was automatically terminated |
| `canceled` | Terminated by the parent via `terminate_workstream` |

## Progress Tracking

Workstreams report rich progress back to the parent, including:

- **Phase** — what the sub-agent is doing right now:
  - `planning` — analyzing the task and forming a plan
  - `executing_tool` — running a tool (tool name included)
  - `synthesizing` — combining results into a response
  - `blocked` — waiting for input or a dependency
  - `done` — finished processing
- **Current iteration** number (0-based)
- **Model message** — what the sub-agent is thinking about
- **Deadline percentage** — how much time has elapsed

Use `check_workstream` to query progress on demand, or `list_workstreams` for an overview of all workstreams.

## Deadline Management

Every workstream has a deadline to prevent runaway execution:

| Setting | Value |
|---------|-------|
| Default deadline | 5 minutes |
| Maximum deadline | 30 minutes |
| Minimum deadline | 30 seconds |

Configure the deadline via the `deadline_seconds` parameter on `launch_workstream`.

### Auto Wrap-Up

The system automatically manages deadlines:

1. At **75%** of the deadline, the parent receives a warning.
2. At **80%**, the child receives an automatic wrap-up steering directive telling it to finalize.
3. At **90%**, the parent receives a final warning.
4. At **100%**, the workstream is terminated and the parent receives a timeout notification with the last known progress.

## Interactive Workstreams

By default, workstreams run in **fire-and-forget** mode: the child executes its instruction and completes. For multi-turn conversations with a sub-agent, launch with `interactive: true`.

Interactive workstreams:
- Complete their initial task, then **wait** for follow-up messages
- Receive messages via `message_workstream`
- Support multi-round exchanges (e.g., asking follow-up questions, requesting refinements)
- **Never complete on their own** — the parent must call `terminate_workstream` to close the session

Interactive mode is the foundation of the [Expert Roundtable](#expert-roundtable-pattern) pattern.

## Artifact Merging

When `merge_child_artifacts` is `true` (the default), artifacts created by the child in its `out/` and `files/` directories are automatically copied back to the parent's artifact workspace after completion. Artifacts are **namespaced by child run ID** to avoid conflicts:

```
Parent workspace:
  files/{child_run_id}/output.json
  out/{child_run_id}/report.pdf
```

Set `merge_child_artifacts: false` to disable this behavior for workstreams that produce intermediate artifacts you don't need.

## Steering

The parent can send directives to a running workstream via `steer_workstream` without terminating it:

| Command | Use Case |
|---------|----------|
| `add_instruction` | "Also include pricing information in your analysis" |
| `set_priority` | "Focus on the security aspects first" |
| `add_constraint` | "Limit your analysis to the last 3 years" |
| `pause_requested` | Request the sub-agent to pause |
| `resume_requested` | Resume a paused sub-agent |

Steering directives are delivered as system messages that the child processes in its next reasoning turn.

## Best Practices

1. **Decompose clearly** — each workstream should have a single, well-defined objective. Vague instructions produce vague results.

2. **Provide rich context** — the sub-agent does **not** see the parent's conversation history. Include all relevant information in the `instruction` and `context` parameters.

3. **Scope tools carefully** — limit `allowed_tools` to what the task actually needs. A research task might only need `think` and `learn_web_search`, while a data analysis task might need `execute_shell` and artifact tools.

4. **Use meaningful IDs** — the `id` parameter appears in logs, progress messages, and the UI. Use descriptive names like `research_competitors` instead of `ws1`.

5. **Don't duplicate work** — avoid launching workstreams for tasks you can do faster inline. Workstreams have overhead (workflow startup, signal communication).

6. **Set appropriate deadlines** — use longer deadlines (up to 30 minutes) for complex tasks, shorter ones for simple research.

7. **Synthesize results** — when workstreams complete, review and combine their outputs into a coherent response rather than forwarding raw results.

8. **Don't poll** — results are delivered automatically via system messages. Simply end your turn and wait; the system handles notification.

## Expert Roundtable Pattern

The Expert Roundtable is an advanced multi-agent pattern where specialist sub-agents with distinct personalities and optionally different models debate a topic from multiple perspectives. This produces richer, less biased analysis than a single-agent approach.

### How It Works

1. **Decompose** the topic into 2-5 specialist perspectives (e.g., security architect, business strategist, technical lead).
2. **Launch** each specialist as an interactive workstream with a specific personality, model, and instructions.
3. **Collect** opening statements using `analyze_conversation` on the running child workflows.
4. **Cross-pollinate** — use `message_workstream` to pass opposing arguments between specialists for multi-round debate.
5. **Synthesize** — after convergence (or max 3 rounds), write a final synthesis that reconciles all perspectives.
6. **Terminate** all interactive workstreams when done.

```json
{
  "id": "security_expert",
  "name": "Security Architect",
  "instruction": "You are a skeptical security architect. Analyze this proposal from a security perspective...",
  "context": { "topic": "..." },
  "allowed_tools": ["think", "write_artifact"],
  "interactive": true,
  "model": "claude-sonnet-4-20250514",
  "deadline_seconds": 600
}
```

The Expert Roundtable pattern is available as the `learn_expert_roundtable` system skill, which provides detailed step-by-step instructions.

## Tools Reference

For detailed parameter documentation of all workstream tools, see [Built-in Tools — Workstream Tools](/agent-runner/tools#workstream-tools).

| Tool | Description |
|------|-------------|
| `launch_workstream` | Launch a non-blocking child sub-agent |
| `check_workstream` | Query status and progress |
| `list_workstreams` | List all workstreams with filtering |
| `terminate_workstream` | Cancel a running workstream |
| `steer_workstream` | Send mid-execution directives |
| `message_workstream` | Send messages to interactive workstreams |
| `get_workstream_result` | Retrieve completed workstream results |