Multi-Role Collaboration and Sub-Flow Playbook

Languages: English · 中文

Multi-role collaboration is useful when one task needs several specialist views. It is not a reason to let agents freely chat until something useful appears.

The stable shape is: role-specific agents produce structured outputs, Sub-Flows isolate each role's process, Workspace controls evidence and artifacts, and the parent TriggerFlow aggregates results.

When to Use It

Scenario	Recommendation
One classification, summary, or form extraction	One AgentExecution + output schema
One input needs risk, facts, compliance, editing, or execution views	Parent TriggerFlow dispatches multiple role Sub-Flows
Each role creates its own evidence, artifacts, or review records	Bind each Sub-Flow to an isolated Workspace or collection
Roles need waiting, approval, rerun, or merging	Parent flow owns lifecycle and aggregation
The only goal is "make it smarter"	Do not start with multi-agent; first define output contract and acceptance rules

Recommended Structure

text

parent TriggerFlow execution
  -> prepare shared input and artifact refs
  -> risk_review sub-flow
  -> fact_check sub-flow
  -> editor sub-flow
  -> deterministic aggregation
  -> approval or final delivery

Each role returns structured data:

json

{
  "risk_level": "high",
  "findings": ["missing approval record"],
  "requires_approval": true,
  "evidence_refs": ["workspace://evidence/approval-log"]
}

The parent flow can apply hard rules before asking a model to summarize. For example, if any role requires approval, pause.

Workspace Topologies

Topology	When to use	Notes
One shared Workspace	Roles inspect the same material and reuse evidence	Agree on collection names to avoid overwrites
One Workspace per role	Roles need isolation, e.g. compliance review and editor draft	Parent reads structured summaries and artifact refs
Isolated collections + shared artifacts	Common enterprise case	Original material is shared; each role writes its own observations and decisions

How to Split Sub-Flows

A role Sub-Flow should own a coherent responsibility:

input schema,
visible Actions / MCP tools / Skills,
Workspace collection,
output schema,
failure semantics,
product stream events.

It should not decide final delivery on its own unless it is the whole task.

Aggregation

Do not aggregate from a free-form chat transcript. Aggregate from role outputs:

json

{
  "risk_review": {
    "risk_level": "high",
    "findings": ["missing approval record"],
    "requires_approval": true
  },
  "fact_check": {
    "verified": false,
    "missing_evidence": ["vendor payment proof"]
  },
  "editor": {
    "draft_artifact_ref": "workspace://artifacts/report-draft.md"
  }
}

Deterministic rules handle hard constraints first; a model can then write the final explanation or recommendation from those structured fields.

Runtime Stream for Users

Sub-Flows can emit product-friendly events into the parent execution stream:

python

await data.async_put_into_stream({
    "type": "role_status",
    "role": "risk_review",
    "stage": "done",
    "summary": "Found 2 high-risk items; approval is required.",
})

The UI does not need to know internal chunk names. It consumes stable fields such as role, stage, summary, and artifact_ref.

Avoid

Misuse	Why it is unstable
Start 5 agents and let them freely chat	No handoff contract, no reviewable result, hard to replay
Every role sees every tool	More roles increase the chance of wrong or privileged calls
Use shared global state for everything	Concurrent executions can pollute each other and recovery becomes fragile
Pass role output as natural-language paragraphs	Downstream aggregation cannot enforce hard rules
Let a Sub-Flow decide final delivery	Parent flow loses business line and acceptance boundary

Acceptance Checklist

Check	Passing standard
Role boundary	Each role has responsibility, input, output, and failure semantics
Handoff contract	Parent/child flows exchange structured fields, artifact refs, and state keys
State topology	Shared vs isolated Workspace / collection choices are explicit
Action permission	Roles only see Actions / MCP / Skills required for their job
Process output	Parent execution stream can show role progress
Recovery	Pause/resume, checkpoints, and human approval are managed by parent execution
Quality evidence	Aggregated result has business rules, model judge, or human confirmation

Multi-Role Collaboration and Sub-Flow Playbook ​

When to Use It ​

Recommended Structure ​

Workspace Topologies ​

How to Split Sub-Flows ​

Aggregation ​

Runtime Stream for Users ​

Avoid ​

Acceptance Checklist ​

Continue Reading ​