Multi-agent demo design

Status: Preview | Last reviewed: 2026-09-18

Studio's Multi-agent demo selection creates a saved project containing ordinary agent drafts. One design conversation owns its plan, components, connections and journey tests. This is an authoring feature; runtime agents retain their existing types. Selecting Voice still limits generation to one voice agent.

Roles and scope

Experience	Component
Customer self-service	Voice
Human oversight during self-service	Chat using native Human Supervision
Assistance during the human-to-human call	Copilot using native Agent Assist
Customer messaging	Chat
An asynchronous business task	Background workflow, when the author has workflow access

The common three-part demo uses Voice, supervisor Chat and representative Copilot. The Copilot can suggest answers, coach, populate forms and summarize; it does not speak to the caller. Several Copilot behaviors belong in one Copilot. Business topics within the same session remain procedures/internal subagents. Authentication and ending behavior belong in the owning agent. Generation discovers actual tenant-visible Agent Assist cards with search_copilot_cards. Native Copilot editor checks also gate completion: missing cards, missing knowledge sources, empty forms and unsupported transcription cannot be marked as a completed component.

The designer chooses the smallest suitable set within the selected demo mode. Automatic selection between single-agent and demo modes is not part of this release. The standalone Copilot selection uses the same native Agent Assist baseline and editor.

Specification and authorization

design_state.demo contains a fictional scenario, 2–8 keyed components, typed connections and journey_tests. Each component includes a complete ordinary overview. Validation rejects missing members, incompatible roles, disconnected components, duplicate keys, fake identity/approval variables and journey steps that omit either endpoint of a tested connection.

Only the author's Build demo action authorizes executable changes. The parent specification is frozen for that turn. The demo MCP catalog exposes:

• prepare_demo_components: create or resume stable member drafts.
• get_demo_component and save_demo_component: scope by an approved key, resolve the target on the server and use revision checks.
• save_demo_component_tests and complete_demo_component: persist native goldens/goals or workflow inputs and apply ordinary artifact validation.
• wire_demo_connections: configure native supervision bindings.
• complete_demo_build: check every member and connection before enabling Open demo.

Parent tools cannot save arbitrary agent IDs. Research of existing agents is read-only. Child sessions share the parent's authoring turn; they do not launch additional models. The parent releases child leases on completion/failure. Retries reuse existing IDs and preserve manual test edits. The completion gate compares each component's approved overview with the parent specification. Skipping preparation after a design change cannot reuse an old component receipt. Refining an already completed member during a parent build reopens that member's artifact gate. Component reads return exact build-reference paths and selected tools. Manifest pointers start inside the configuration, without a /config envelope prefix. The gate recognizes the native conversational-node tools, including supervisor message injection, and actual agent-wide settings such as silent monitoring.

The separate runner protocol is demo_designer_protocol.md. It uses the selected authoring engine and existing 30-minute turn budget, including GPT-6 Astra at low effort when configured. Shared research tools and bundled capability handbooks remain available. A fresh conversation is required to obtain a changed managed OpenAI tool catalog.

Native connections

For supervision, the server pins builtin_tool_configs.human_supervision.supervisor_agent_id to the supervisor draft and enables transcript streaming. The supervisor selects builtin:inject_message_to_conversation, binds its target to $var:related_conversation_id and enables settings.text_turns.allow_silence. Other configuration is preserved. The generator must still implement the business request, human decision policy, pending-action checks and any supported approval surface. AI reasoning cannot substitute for a human approval.

Supervision journey tests must include success, rejection, timeout and call end. A human_handoff edge connects Voice to the representative Copilot and requires a context-continuity test. The voice prompt uses native end_session with session_escalated:true and params.summary; the connected phone flow owns routing and context delivery to the human call. The edge does not provision a phone route or start a second voicebot. A background_task connection must have an actual saved workflow invocation in its source.

See Human Supervision, Copilots and live Copilot ingress for runtime contracts.

Preview and validation

The project has Journey, Agents, Connections, Preview and Validate tabs. Open demo releases its component editors after checking their saved drafts, native test artifacts and parent receipt under locks. Manual component changes invalidate project readiness; continuing the build resumes existing components.

Preview uses the native phone tester with shared fictional inputs. The supervisor conversation is created through the native supervisor-session endpoint only after checking the preview call's tenant, user, source agent and approved connection. Customer Chat can start its native conversation directly in Preview, with the same ownership checks for connecting a supervisor. Copilot preview opens its ordinary editor/tester; the existing voice stand-in can rehearse the representative segment. Verified conversation attachments let the project display its live assistance surface. The native Copilot tester forwards its template variables through X-Template-Variables, including the project's shared fictional inputs.

Preview does not provision channel routing or automatically bridge self-service audio/context into a new Copilot session. Validate real routing and summary continuity on the configured phone channel. The shared sample inputs never manufacture verification or an approval.

Component examples are saved tests, not executed calls. Journey results require a signed-in author to record evidence through the workspace; the model's MCP catalog cannot mark them passed. Results are bound to the design revision and component fingerprint. A stale browser cannot record a result against changed artifacts. No project action publishes agents or activates workflows. Draft references must be deliberately repinned when publishing individual agents.

Storage and API

Migration 063_studio_demo_projects.sql adds assistant_sessions.kind='demo', the multi_agent/copilot design selections, and tenant-scoped project, membership and observation tables. Membership points to ordinary designer sessions, which own the native drafts. Members are hidden from the top-level design list; the parent is the entry point. All three tables use forced tenant RLS in addition to application ownership checks.

Endpoint	Purpose
POST /api/studio/designs with type:multi_agent	Create the parent project
GET /api/studio/designs/{id}	Project overview, components and readiness
POST /api/studio/designs/{id}/handoff	Recheck and open the demo
GET /api/studio/designs/{id}/preview	Read authorized draft preview inputs
POST /api/studio/designs/{id}/preview	Attach a verified call or open its connected supervisor
POST /api/studio/designs/{id}/journey-checks	Record a human observation against current artifacts

Apply migration 063 before running the updated manager. Rebuild/restart an idle workspace-agent-runner after changing its protocol/reference files.

Verification

Run the focused lib/studio/demo.test.ts tests and the existing design tests. scripts/test-demo-design-local.ts exercises real database build authorization, idempotent component creation, tenant isolation, native wiring, saved tests, completion, editor handoff and invalidation after manual edits. It requires DESIGN_TEST_DATABASE_URL or DESIGN_TEST_DATABASE_FILE containing a JSON url, and rejects databases other than a localhost designer_* database.

Initialize disposable databases with baseline/reference data and migrations through 063. Do not point fixture setup at the application database. Browser checks cover type selection, the project tabs and recorded-result controls. Live audio, human approvals and channel routing require separate runtime tests.