Workflows

Turn a good sequence into a reusable run

A workflow describes who or what should act, what each step receives, and which results unlock the next step. A run is one observable execution. An automation starts that workflow on a schedule.

Choose the right level of structure

Not every collaboration needs a workflow.

Use	When it fits
Conversation	The task is exploratory, the next step depends on judgment, or the team is still discovering the process.
Workflow	The sequence and handoffs are known, but a person starts each run when needed.
Scheduled automation	The same workflow should start on a cadence without a person initiating it.

A useful rule is to perform the work once in a document conversation, repeat it manually, and only then encode it. Automation should preserve a working contract, not disguise an unclear one.

Workflow definition. Reusable YAML stored in a workspace. It declares steps, parameters, and dependencies.

Run. One execution of that definition. The run has its own channel, tasks, progress, and step results. In the code and API a run is also called a journey.

Automation. A schedule connected to a workflow. Each firing creates a distinct run and records the automation that created it.

The execution model

Name the outcome and declare each step in YAML.
Create a run manually, or let a schedule create it.
Ready steps become tasks for agents, people, or built-in handlers.
Inspect progress, messages, results, and final artifacts in the run.

A step becomes ready only after all of its declared dependencies complete. Independent steps can become ready together. Before a task is stored, Dana4 resolves any references to completed step results. The task therefore records the exact input that was dispatched rather than an unresolved template.

If a reference is missing or invalid, the task fails with a template-resolution error instead of silently sending literal {{...}} text to the next agent.

The step vocabulary

Step	What it does
`!agent`	Dispatches a capability to one named agent.
`document_create`	Creates one or more explicit workspace documents.
`message`	Posts a message into the run conversation.
`wait_for_message`	Pauses until the run receives a reply.
`read_messages`	Starts a task for reading messages.
`!pipe`	Moves a declared resource into a named workflow value.
`!router`	Chooses a path from workflow state.
manual task	Waits for a workspace member to be assigned and complete the work.

Agent steps are capability calls, not personas inferred from prose. The named agent must exist, belong to the workspace, and advertise the requested capability. A capability schema declares the inputs it accepts; Dana4 adds the task and workspace identifiers required to execute it.

Results are contracts

Downstream steps read structured results with {{step_id.field}}. A general Arlo agent step with create_document: false currently returns:

output — the generated text;
document_path, document_url, and document_title — null because the workflow owns publication.

A document_create step returns both document (the first created document) and documents (the full array). Each contains id, title, path, and url.

That supports a clean three-step publishing pattern:

agent result → explicit document → announcement with document link

The agent does the reasoning. The workflow decides what becomes a durable artifact. The message step points people to that artifact rather than creating another copy.

Human work

A manual step is parked until a workspace member assigns it. Assigning it to a person keeps it out of the agent queue; the owner finds it in their open tasks and completes it explicitly. Assigning it to an agent rewrites it as a capability task for that agent.

Use a human step when the workflow truly requires judgment or authority: approving a claim, accepting risk, choosing a final concept, or authorizing external publication. Avoid adding a review gate only as a ritual. Low-risk internal briefs can often run end to end and be corrected in the resulting document.

Build and run one

Open Automations, follow the Workflows link, and choose Create workflow.
Give it a name and description, then paste a YAML definition.
Save the workflow. The backend validates duplicate IDs, missing dependencies, cycles, required document fields, message content, and result-reference ancestry.
Return to Automations and choose Run new automation.
Select the workflow, name the run, open it, and choose Start.
Watch its tasks and run conversation before adding a schedule.

Start with the complete example in Workflow definition.

Reliability boundaries

Give every final document a deterministic key. Within a run, retrying the document step then resolves to the same logical document instead of creating another sidebar entry.
Use {{run.date}} or {{run.id}} when the artifact identity should vary by scheduled day or run.
Set create_document: false on intermediate generic-agent steps. Publish only through an explicit document_create step.
Declare every referenced step as a dependency, directly or transitively.
Test the workflow manually before scheduling it.
Treat external publication and irreversible actions as separate integrations with an explicit owner; a Dana4 message step posts inside the run, not to an arbitrary external channel.

The run is the audit surface: it shows the task that ran, the materialized inputs, the result, the artifact created, and the conversation around it.