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.

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)

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:

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 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:

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 15 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.

{
  "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.