Act Editor & Runtime

Model multi-performer collaboration with participants and relations.

If a Performer is one runnable role, an Act is the scene where several roles work together.

Key concept: Acts are participant-first. Collaboration is described through participants (who?) and relations (how do they interact?).

What an Act Represents#

An Act groups performers into one shared collaboration space. It answers:

Acts are best for workflows where a single performer isn't enough:

• Lead + Worker
• Planner + Implementer + Reviewer
• Incident commander + Specialist

The Core Parts of an Act#

Participants#

Participants are the performers inside the Act. Each participant has:

Think of participants as Act-local roles built from real Performer assets.

Subscriptions#

Subscriptions let a participant react to specific signals inside the Act:

Subscriptions are wake-up filters, not permission rules. They control when a participant gets activated, not what it's allowed to do.

Relations#

Relations describe how participants interact — the choreography.

Relations turn a set of performers into a real choreography.

Tip: For one-way relations, order matters — the first participant in between is the caller. Two opposite one-way relations between the same participants are valid and expected when you need asymmetric communication.

Act Rules#

Acts can carry shared actRules for scene-level coordination:

• Who owns final approval
• When escalation is required
• Whether one participant must review another's work

Building an Act in Studio#

Step 1 — Add an Act to the Workspace#

Create a new Act from the Workspace view. This gives you an Act workspace on the canvas.

Step 2 — Add Participants#

Bring performers into the Act as participants. Each participant gets a unique key that identifies it within the Act.

Good practice:

• Start with two participants
• Make each role easy to understand
• Avoid duplicating responsibilities between participants

Step 3 — Define Relations#

Add relations between participants. Typical examples:

Lead ── delegates ──→ Worker        (one-way)
Reviewer ── inspects ──→ Implementer  (one-way)
Planner ←── discusses ──→ Coder       (both)

Step 4 — Configure Subscriptions (optional)#

Set up subscriptions if you want participants to react to specific signals:

Lead subscribes to callboardKeys: ["shared/*"]
  → Wakes up whenever a shared callboard entry is posted.

Reviewer subscribes to eventTypes: ["runtime.idle"]
  → Wakes up when the Act has no active participants.

Step 5 — Add Scene Rules (if needed)#

Use actRules for coordination that applies to the whole scene. Keep them short and operational.

A Good First Act#

A useful first Act is just two participants and one relation:

┌─────────────────────────────────────────┐
│              My First Act               │
│                                         │
│  Lead ────── delegates ────→ Worker     │
│                (one-way)                │
│                                         │
│  Rule: "Lead owns final approval."      │
└─────────────────────────────────────────┘

That's enough to prove the model before you add more structure.

Example Shape#

{
  "$schema": "https://schemas.danceoftal.com/assets/act.v1.json",
  "kind": "act",
  "urn": "act/@acme-platform/workflows/incident-response",
  "description": "Lead and worker collaboration for incidents.",
  "tags": ["incident", "workflow"],
  "payload": {
    "actRules": [
      "Lead owns final approval."
    ],
    "participants": [
      {
        "key": "lead",
        "performer": "performer/@acme-platform/agent-presets/incident-lead",
        "subscriptions": {
          "callboardKeys": ["shared/*"]
        }
      },
      {
        "key": "worker",
        "performer": "performer/@acme-platform/agent-presets/incident-worker"
      }
    ],
    "relations": [
      {
        "between": ["lead", "worker"],
        "direction": "one-way",
        "name": "review_request",
        "description": "Lead coordinates, worker executes."
      }
    ]
  }
}

Running an Act#

After configuration, open the Act's thread view and send a message.

From the user's point of view:

1. Your prompt starts the conversation
2. Participating performers collaborate according to relations
3. Subscriptions control which participants wake up and when
4. Results accumulate inside the Act thread

Live Editing#

You can update an Act while it's running. Studio syncs your changes to active threads:

• Relation changes — apply immediately
• Subscription changes — apply immediately
• Rule and safety changes — apply immediately
• Participant performer change — retires the old session and creates a new one on next use
• Participant key rename — treated as removing the old participant and adding a new one

Safe Mode and Direct Mode in Acts#

Acts support both execution modes:

When to Use an Act vs a Performer#

Common Patterns#

Lead and Implementer#

Lead ── decides ──→ Worker
  • Lead sets direction
  • Worker executes
  • One-way relation

Planner, Coder, Reviewer#

Planner ── breaks down ──→ Coder
                           Coder ── submits ──→ Reviewer

Incident Response#

Lead ── triages & approves ──→ Specialist
  • Lead subscribes to callboardKeys: ["shared/*"]
  • Specialist investigates or patches
  • Safe mode recommended

Tips for Better Acts#

• Start with the smallest useful collaboration
• Keep participant roles clear and distinct
• Use relations intentionally — don't connect everything to everything
• Prefer one or two strong act rules over a long policy list
• Use subscriptions to let participants react to signals rather than polling
• Move scene-wide identity into performers, not into relation descriptions