agentprism-workflow-authoring

Writing AgentPrism workflow scripts

A workflow script is plain JavaScript, passed around as a string, not a module. The engine runs it in a deterministic sandboxed realm. Each agent() call opens a session on an Agent Client Protocol (ACP) backend — Claude Code, OpenAI Codex, OpenCode, pi, or a custom ACP agent server. The backend runs its own tool loop to completion and returns final text or a schema-validated object. One script can mix backends per call.

reference.md (same directory) holds the exhaustive option tables, routing grammar, and error codes.

The guide, by task

Read the section your task needs — each is a separate document in this skill directory:

1. Running workflows — register @automatalabs/mcp-server; the workflow tool's run/await/inspect/stop actions; background runs; execution logs through the events resource.
2. Backends and structured output — per-call model routing, configOptions, and schema-validated outputs on every backend.
3. Composition and failure — the meta header, parallel and pipeline, null semantics, and phases.
4. Quality helpers and checkpoints — gate, retry, verify, judgePanel, loopUntilDry, completenessCheck, and the human checkpoint() gate.
5. Execution environment — working directories, worktree isolation, session modes, per-call MCP servers, custom ACP backends.
6. Determinism and resume — what is identity-hashed, content-addressed replay, and how to keep a script resumable.
7. Examples and validation — worked examples, the full scripts in examples/, and the zero-token validator.

The mental model

• The script is the orchestrator; agents are workers. All control flow — loops, fan-out, dedup, aggregation, conditionals — lives in script code. Agents cannot spawn agents and cannot see each other. Give each agent one self-contained task.
• Each agent() call opens a fresh session with no memory. Interpolate everything a later call needs into its prompt. (Sole exception: resume can continue the same usage/auth-interrupted occurrence — see Determinism and resume.)
• Agents are real coding agents, not chat completions. They have file access, shells, and tools, rooted at the run's working directory. "Read the failing test and fix it" is a valid prompt; the agent will edit files.
• The DSL primitives are realm globals, not imports. There is nothing to import — agent, parallel, pipeline, gate, checkpoint, args, … are injected. Top-level await and a top-level return are valid. The script's return value becomes the run's result.
• Scripts are plain JavaScript, not TypeScript. Type annotations fail to parse. The realm has no Node APIs (no require, import, fs, fetch, timers). All side effects happen through agents.
• Live observability needs no script annotations. Journaling runs publish redacted progress and transcript upserts at workflow://runs/{runId}/events. Author labels for human correlation, not to enable this behavior.