workflow_creation

Workflow Creation

A workflow is a single Rome action whose body is plain author-written code: one async function, runWorkflow(input, ctx), that transforms the value flowing in and implements its own control flow — sequencing, concurrency, conditionals, fan-out — directly in TypeScript. The run action calls runWorkflow directly, and the function reaches reusable work through ctx.runAction(canonicalId, args), which can invoke any registered action — system:send_message, a SaaS API via connector:connector_proxy, or system:summon (hand a piece of work to an LLM agent).

Each workflow is its own Rome app, scaffolded from the bundled workflow template. The template ships the entire shell — run action, trigger API, web page, run-history table — already wired and buildable. You write the one thing that differs per workflow: the body of runWorkflow().

Artifact identity — never use bare names

The scaffold is formatVersion: 2. Definitions use app-local names (name: run); every reference and runtime call uses <app-id>:<local-name>, even for an action owned by this workflow. Never emit a bare artifact name or self:<name>.

Use the real canonical ids for shared platform artifacts:

• LLM work: ctx.runAction("system:summon", { agentName: "assistant:assistant", prompt })
• Connected provider API: ctx.runAction("connector:connector_proxy", args)
• Messaging: ctx.runAction("system:send_message", args)
• Routine creation: ctx.runAction("system:create_routine", { actionName: "<workflow-app-id>:run", ... })
• Core orchestrator, only when the workflow explicitly needs it: core:main

Three principles that decide most of the design

These come up on nearly every workflow, so internalize them before writing anything — the rest of the skill assumes them.

1. Generative work is a system:summon call, never a bespoke agent or action. When the request is "write me a recap / draft replies / summarize these / decide what matters," the tempting move is to stand up a custom writer agent plus a generate action plus a DB of past results. Resist it — that whole apparatus collapses to one line: await ctx.runAction("system:summon", { agentName: "assistant:assistant", prompt }). Put the voice, persona, and instructions in the prompt, not a custom agent. A hand-written action.yaml/agent.yaml is also an error surface: one wrong field fails the whole app to load, and the run then throws "action not found." system:summon is the agent entry point.