Workflow reference

Define a workflow in YAML

A workflow is a directed graph of typed steps. IDs make results addressable; dependencies make the execution order explicit; parameters become the task input recorded in the run.

Complete example

This workflow asks Arlo for an internal market brief, saves exactly one intended artifact, then posts the result and link into the run conversation.

name: Daily market brief
steps:
  - id: research
    title: Research today's signals
    type: !agent
      name: arlo.dana4
      capability: generic-agent
    params:
      about: Daily market intelligence for the product team
      query: |-
        Produce a concise dated brief with three to five findings,
        evidence notes, uncertainties, and a two-sentence summary.
      task_type: research
      create_document: false

  - id: publish
    title: Publish the brief
    type: document_create
    params:
      key: "market-brief-{{run.date}}"
      title: "Market brief — {{run.date}}"
      content: "{{research.output}}"
    dependencies: [research]

  - id: announce
    title: Announce the brief
    type: message
    params:
      message: |-
        {{research.output}}

        [Open the full brief]({{publish.document.url}})
      from: arlo.dana4
    dependencies: [publish]

The first step creates no document of its own. publish is the only publication boundary, and its date-based key makes a retry on the same UTC day resolve to the same logical artifact. The announcement depends on publish, so it can safely reference both the original agent result and the document result through transitive ancestry.

Top-level fields

The workflow editor also stores a separate name and description alongside the YAML. Keep the stored name and YAML name aligned so the list and run remain understandable.

Step fields

IDs must be unique. Every dependency must exist, and dependencies cannot form a cycle.

Agent steps

- id: draft
  title: Draft the internal update
  type: !agent
    name: arlo.dana4
    capability: generic-agent
  params:
    about: Weekly product update
    query: Turn the supplied findings into a clear internal update.
    task_type: documentation
    create_document: false

name is the exact registered username. capability must be present in that agent’s advertised schema. The agent must also be a member of the workflow’s workspace.

For generic-agent, keep create_document: false inside a workflow. Otherwise the agent creates an intermediate document and the later document step creates the final one, leaving duplicate or poorly named artifacts in the workspace.

Document steps

Create one document:

- id: publish
  type: document_create
  params:
    key: "weekly-update-{{run.date}}"
    title: "Weekly update — {{run.date}}"
    content: "{{draft.output}}"
    type: default
  dependencies: [draft]

key and title are required strings. content, type, and parent_id are optional. The key is the document’s stable workspace identity, not a display path. Reusing a key resolves the existing document; document_create does not overwrite its content.

Create several documents with one step by using list:

- id: scaffold
  type: document_create
  params:
    list:
      - key: launch-plan
        title: Launch plan
        content: "# Launch plan"
      - key: decision-log
        title: Decision log
        content: "# Decision log"

The result shape is:

{
  "document": { "id": "…", "title": "…", "path": "/…", "url": "dana4-doc://…" },
  "documents": [{ "id": "…", "title": "…", "path": "/…", "url": "dana4-doc://…" }]
}

Message steps

- id: share
  type: message
  params:
    message: |-
      The update is ready.

      [Open it]({{publish.document.url}})
    from: arlo.dana4
  dependencies: [publish]

message is required and must be a string. from is optional; when supplied it should be a valid workspace agent username. The message is posted to the run’s channel.

Do not hardcode content that should change on every run. Reference a completed step result instead.

Result references

Use double braces with a step ID and one or more fields:

content: "{{research.output}}"
message: "Created {{publish.document.title}} at {{publish.document.url}}"

References resolve recursively inside strings, arrays, and objects immediately before Dana4 creates the task. If the whole value is one reference, arrays and objects keep their JSON type. Embedded values are rendered as text.

The referenced step must be an ancestor of the consuming step. This is valid:

research → publish → announce
    └───────────────────┘ announce may reference research through transitive ancestry

This is rejected because research may not have completed:

dependencies: [some_other_step]
message: "{{research.output}}"

Run references

Dana4 makes a small run object available during materialization:

run.date is evaluated when a step becomes ready. Use run.id when two runs on the same day must never share an artifact. Use run.date when the intended identity is one document per UTC day.

Waiting and human review

wait_for_message pauses a workflow until someone replies in the run conversation:

- id: ask
  type: message
  params:
    message: Which audience should this brief prioritize?
    from: arlo.dana4

- id: wait_for_answer
  type: wait_for_message
  dependencies: [ask]

Manual tasks are intentionally different: they remain blocked until a workspace member assigns an owner, then the person or selected agent completes the task. Use them only where ownership is part of the process; use wait_for_message where the workflow simply needs conversational input.

Validation checklist

Before scheduling a workflow, verify:

• every step ID is unique;
• every dependency exists and the graph has no cycle;
• every result reference points to an ancestor step and a real output field;
• named agents are workspace members and expose the requested capability;
• generic-agent intermediates use create_document: false;
• every final artifact has one intentional, deterministic document key;
• message steps reference generated output instead of repeating it;
• the workflow completes once as a manual run.

Then attach the schedule. Inspect the first scheduled run just as you inspected the manual one.

Return to Workflow introduction →