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

Open a Registry Act directly in Studio:

dot-studio . --act act/@acme/workflows/incident-response

Studio imports the Act and its Performer dependencies when needed, then focuses the Act on the canvas.

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.

At runtime, Studio also uses the linked Performer's authoring description as that participant's focus in collaboration prompts when one is available.

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.

If you want better runtime coordination, also give each linked Performer a short description in its editor. Studio uses that description as the participant's focus in Act collaboration prompts.

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 matching shared note key is posted or updated.

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#

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

What participants see at runtime#

Each participant gets a stable collaboration context that includes:

• the Act goal and rules
• the participant's own role and focus
• only its directly connected participants
• the connected participants' focus descriptions when available
• the four collaboration tools for coordination

This keeps prompts smaller and more relevant than showing every participant the full scene.

Runtime collaboration tools#

Participants coordinate with four tools:

• message_teammate for direct coordination with one participant
• update_shared_board for durable shared notes, task status, findings, and handoffs
• read_shared_board for reading the relevant shared note key
• wait_until for saving a self-wake when blocked on future input

Good runtime habits:

• prefer a specific shared note key instead of reading the full board
• treat the shared board as compact durable state, not a transcript
• prefer replace with a fresh summary over long incremental append logs
• use wait_until when waiting on a teammate message, a shared note key, a timeout, or a combined condition

The timeout above is a runtime waiting condition, not a canonical relation field. Canonical relations only store between, direction, name, and description.

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
• Linked performer description change — updates the participant's prompt focus for attached live Acts
• 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
• Write a short Performer description for every participant-facing role
• Use relations intentionally — don't connect everything to everything
• Prefer one or two strong act rules over a long policy list
• Use subscriptions and wait_until to let participants react to signals rather than polling
• Keep shared board entries compact and keyed by durable topics
• Move scene-wide identity into performers, not into relation descriptions