Skip to content

Write your first workflow

At the end of this page you have a workflow you wrote yourself, with a parameter, two agent steps that pass work from one to the other, and one automatic step. You run it by hand and read its record. On the way, Realm catches a typing mistake in your file.

Before you start

Section titled “Before you start”

You need the realm command installed. See Install and first run.

1. Start the file

Section titled “1. Start the file”

Make a folder and create workflow.yaml in it:

Terminal window
mkdir article
cd article

Put this in workflow.yaml:

id: article
name: Write a short article
version: 1


params_schema:
  type: object
  additionalProperties: false
  required: [topic]
  properties:
    topic:
      type: string


steps:
  outline:
    description: List the points the article will make.
    execution: agent
    prompt: |
      List two to five points for a short article about {{ run.params.topic }}.
    input_schema:
      type: object
      additionalProperties: false
      required: [points]
      properties:
        points:
          type: array
          minItems: 2
          maxItems: 5
          items:
            type: string

Notice three parts:

  • params_schema says what a run must be given at the start. Here it is one piece of text, topic.
  • prompt is the task a model receives for this step. {{ run.params.topic }} is replaced with the run’s topic.
  • input_schema says what the step’s answer must look like: a list of two to five points.

2. Add a step that uses the first one

Section titled “2. Add a step that uses the first one”

Add two more steps under steps, after outline. Type the third line of write exactly as shown, mistake included:

steps:
  # outline: as above


  write:
    description: Write the article from the outline.
    execution: agent
    depend_on: [outline]
    prompt: |
      Write a short article about {{ run.params.topic }} that makes these points:


      {{ context.resources.outline.points | bullets }}
    input_schema:
      type: object
      additionalProperties: false
      required: [text]
      properties:
        text:
          type: string
          minLength: 40


  publish:
    description: Keep the article as the result of the run.
    execution: auto
    depends_on: [write]

{{ context.resources.outline.points | bullets }} puts the answer of the outline step into the prompt of write, as a bulleted list. That is how one step’s work reaches the next.

3. Check the file

Section titled “3. Check the file”

Ask Realm to check the file:

Terminal window
realm workflow validate ./

It prints:

⚠ step 'write': unknown key 'depend_on' (line 34) — ignored (did you mean 'depends_on'?)
Invalid: 1 warning, 1 escalated to an error by policy: UNKNOWN_STEP_KEY 'depend_on'

Notice that Realm refused the file and named the line. The key should be depends_on. Without it, write would not wait for outline. Fix the line:

depends_on: [outline]

Check again:

Terminal window
realm workflow validate ./

It prints:

Valid: article v1 (3 steps)
ℹ 2 steps ready for structured_output: strict (2 with caveats) — run 'realm workflow validate --explain' for detail (REALM_NO_NUDGE=1 to silence).

Notice Valid. The second line is a suggestion you can ignore here.

4. Register it

Section titled “4. Register it”

Save a copy of the workflow with Realm, so that other commands can find it by name:

Terminal window
realm workflow register ./

It prints:

Registered: article v1 (3 steps)

5. Run it

Section titled “5. Run it”

Start a run and give it a topic:

Terminal window
realm workflow run ./ --params '{"topic":"human gates"}'

Realm asks for the answer to outline. Type an outline with two points:

{"points":["Gates stop a run","Evidence is recorded"]}

It prints:

Realm — Write a short article v1
Run ID: faf114dc-0c5f-4d95-b310-d5d36b101b6d


→ [agent] outline: List the points the article will make.
  Agent output JSON (Enter for {}): {"points":["Gates stop a run","Evidence is recorded"]}
  ✓ → running | hash: 043e7f4b... | 0ms


→ [agent] write: Write the article from the outline.
  Agent output JSON (Enter for {}):

Notice that the run moved on to write. At this prompt you see each step’s description. A model would be sent the prompt text, with your two points filled in:

Write a short article about human gates that makes these points:


• Gates stop a run
• Evidence is recorded

Type the article:

{"text":"Realm stops a run at a gate until someone answers, and records every step."}

It prints:

  ✓ → completed | hash: 77d5900d... | 0ms


Run complete. Phase: completed

Notice that publish did not ask you anything. It is an auto step, so Realm ran it.

6. Read the record

Section titled “6. Read the record”

Print the record, using the run ID from step 5:

Terminal window
realm run inspect faf114dc-0c5f-4d95-b310-d5d36b101b6d

It prints the following. Some lines are left out here and marked ….

…
Phase: completed  ✓
…
Completed: outline, write, publish
…
Evidence (3 steps):


  1. outline                success   0ms   hash: 043e7f4b
     Taken by: ops@server-1 (from the OS user, via run)
     Input:  {"points":["Gates stop a run","Evidence is recorded"]}
     Output: {"points":["Gates stop a run","Evidence is recorded"]}
     …
  2. write                  success   0ms   hash: 77d5900d
     Taken by: ops@server-1 (from the OS user, via run)
     Input:  {"text":"Realm stops a run at a gate until someone answers, and records every step."}
     …
  3. publish                success   0ms   hash: 77d5900d
     Taken by: ops@server-1 (from the OS user, via run)
     …

Notice that all three steps are in the record, in the order they ran.

If you see something else

Section titled “If you see something else”
  • Error: Invalid params for workflow 'article': (root) must have required property 'topic' You started the run without --params, or without a topic in it. No run was created. Start it again with the topic.
  • ✗ error: Invalid input for step 'outline' Your answer did not fit the step’s input_schema, for example an outline with one point. Realm asks again; type an answer that fits.

What you did

Section titled “What you did”

You wrote a workflow with a parameter and three steps, and Realm caught a misspelt key before anything ran. You passed one step’s answer into the next step’s prompt, and the run’s record shows each step in order.

Next: