Workflows — from a Draft to a result

Use a Workflow when the same sequence of agent work, human decisions, and typed handoffs will run more than once. Dependencies determine when Steps become ready. For a one-off request, start a normal Session. To start a published Workflow at a future time or on a document condition, use a Trigger. Field details, the command list, and limits are in the definition reference.

Before you begin

To run a Workflow, or to create, publish, or archive a Project-owned Workflow, you need:

• An active Project where you are a collaborator or admin. Viewers can read Workflows and Runs but cannot create, publish, run, or record feedback.
• An active collaborator/admin agent in the Project for each Session Step.
• The aachat runtime running on the execution owner's machine, with the chosen coding-agent Runtime configured (Setup, Environment). Passing validation does not make an offline runtime able to start.

There are two ways to operate Workflows.

• WebUI (humans): list Workflows, view Draft files and the dependency diagram, publish, run, archive and restore, read Runs, answer decisions, retry and stop, record feedback, compare two Runs, and ask an agent to improve a Workflow. You can edit existing Session prompts and Decision bodies in the WebUI and save them to the Draft. Ask an agent to create files, change the Workflow structure, or make other Draft changes.
• chat workflow commands (agents): used inside a running aachat Session that can access the Project. They are not for an unauthenticated ordinary terminal. Replace <team>/<project>, agent names, and returned IDs with real values below. --project also accepts a bare Project slug; without it, the cwd's Project is used. Every output has the shape {"ok": true, "data": {...}}.

The server rechecks Project and execution authority on every change.

What is saved

In an Attempt, the Bundle of the exact executing Revision is placed read-only at $AA_WORKFLOW_DIR. Read it when the Step needs it, but do not edit it or copy it back over the Draft. Workflow Attempt Sessions do not receive editable Drafts. There is no _published directory; inspect published definitions with chat workflow list and show.

Find and operate Workflows in the WebUI

A Project's Workflows page is one list, without Workflows/Runs tabs or a state filter. Each row shows a name and a one-line description. Published, active Workflows have an outline Run button and no Active label. Unpublished and archived Workflows appear below them with Inactive · not published or Inactive · archived. Load more continues this same ordering across pages.

Team and Project Workflow lists have a copy button on each row; the detail page also has one immediately beside the title. These buttons copy the Workflow projection path (for example, aachat/teams/team/projects/project/workflows/release), including for read-only, unpublished, and archived Workflows. Opening a Workflow shows its name, description, primary Run button, and a menu with Copy path and Archive (or Restore). A one-line notice appears when the Draft has unpublished changes. The Publish link is also available for unchanged Drafts, so you can explicitly adopt the current published child versions. Publishing requires confirmation, a valid Draft, an active Project, and the appropriate authority; existing Runs keep their original Revision.

After publishing, Workflows using a different version lists published parent Workflows and their Steps in the same owner that pinned a different child Revision at publication. Each link opens the parent in a new tab, leaving the list available while you review other parents. Review the current Draft and confirm Publish to adopt current child versions; this publishes all Draft edits too. Team publication lists Team-owned parents only. An empty result shows no notice, and another publication replaces the result. Existing Runs keep their original Revision. The CLI returns this observation as stale_parent_steps; chat workflow publish takes the parent's Bundle path, not its slug.

The detail has four tabs:

• Flow: the Draft dependency diagram with Agent icons. Select a Step to read its instructions and Run result in place. In a Project Flow, select Input or Output to read the Run’s inputs or results, with arrays shown as lists and objects as key-value pairs.
• Runs: this Workflow's Run history and comparison entry, with Select two runs to compare.
• Files: Draft file contents and supported prompt/body editing. Ask an agent to improve prepares a Session draft for the selected file; it is disabled for viewers and archived Workflows.
• Triggers: active Triggers and Trigger to create one for a published Workflow.

For a Team Workflow that appears in a Project as team:<slug>, publish and archive it on the Team's page reached through Manage in Team.

The Work Panel on the right keeps Sessions and Workflow Runs tabs visible even when there are no Runs or a Session is open. A Run row shows its state mark, Workflow name, one Step/status line, and time. The open Run is selected. Open a row to read the Run; Load older loads older Runs. A Run that a Session started with chat workflow run also appears in the Sessions tab under that Session, linking to the Run detail.

Share a Team Workflow or make an independent copy

Human Team members can view, publish, and archive Team-owned Workflows on the Team sidebar's Workflows page, even without Project membership. Agents create them: an agent with write authority in an active Project of that Team can run chat workflow init team:<slug>. The Draft to edit is aachat/teams/<team>/workflows/<slug>/; every Team member and every agent working in one of the Team's Projects can read and edit it, and Draft edits also reach running Sessions. Validating and publishing that Bundle path makes it appear as team:<slug> in each Project's list. You start it from the executing Project; the Run, Sessions, Asks, feedback, and artifacts stay in that Project. A newly published Team version is used from the next new Run.

To customize it for one Project only, make an independent copy in this order:

1. Run chat workflow init <slug> --project <team>/<project> and wait for it to return.
2. Delete the starter files inside aachat/teams/<team>/projects/<project>/workflows/<slug>/, keeping the directory.
3. Copy the Team Bundle contents with cp -R aachat/teams/<team>/workflows/<x>/. aachat/teams/<team>/projects/<project>/workflows/<slug>/.
4. Validate with chat workflow validate aachat/teams/<team>/projects/<project>/workflows/<slug>, then edit and publish the Project copy.

The trailing /. copies the contents rather than the folder itself. Files placed before init are not picked up. The copy and the Team version have no link or automatic sync. In a Team Bundle, reference children as team:<slug> and do not hard-code a target Project in prompts or document targets, so that the copy works unchanged. A Project path such as aachat/teams/<team>/projects/<project>/… in a Team Bundle prompt triggers the project_path_not_available_here warning during validation.

Validation, publication, and Draft Runs return a non-blocking bundle_reference_missing warning when an initial Session prompt or follow-up names a literal $AA_WORKFLOW_DIR/<path> missing from the Bundle. The warning names the task file and missing path; add the file or correct the reference. Project and Team Bundles use the same check. Variable, placeholder, glob, and space-containing paths are not checked, nor are references inside scripts or other supporting files. Existing published Revisions and Runs are unchanged.

Validation, publication, and draft runs return an unused_workflow_input warning for each declared top-level input that no Step references. Required and optional inputs are both checked; publication is not blocked. Add a reference where needed or remove the unnecessary declaration. For example, pass keyword to a task by writing {{ inputs.keyword }} in its prompt. Descriptions and unreferenced files do not count as usage. A reference does not guarantee that the Step executes or uses the input in its result.

Create a small, complete Workflow

This example takes a reader's name and returns a greeting. From the workspace root, check the available agents and published names, then create the Draft.

chat project members <team>/<project> --runtime-profiles
chat workflow list --project <team>/<project>
chat workflow init greeting --project <team>/<project>

If greeting is taken, choose another slug. init returns once the starter Bundle is editable locally (up to one minute). If it fails with workflow_bundle_not_ready, rerun the recovery command in the response (with the same --client-nonce). Do not create another slug instead.

Replace the generated Draft's workflow.yaml with the following and change writer.yourname to a real member name.

schema_version: 2
name: greeting
description: Write a greeting for one named reader.
inputs:
  type: object
  additionalProperties: false
  properties:
    reader:
      type: string
      minLength: 1
  required: [reader]
outputs:
  greeting: "{{ steps.write.outputs.greeting }}"
steps:
  write:
    needs: []
    session:
      agent: writer.yourname
      prompt:
        file: prompts/write.md
    outputs:
      type: object
      additionalProperties: false
      properties:
        greeting:
          type: string
          minLength: 1
      required: [greeting]

When session.runtime is omitted, the Step starts with that agent's default Runtime and settings. Set it only on Steps that need a specific Runtime or model, for example runtime: {kind: codex-acp, config: {}}. Check the allowed values in the --runtime-profiles result (definition reference).

Create prompts/write.md in the same Draft.

Write one welcoming sentence for {{ inputs.reader }}.

End the task turn normally. The Workflow sends completion instructions in a separate turn after every task has finished. Do not put {{ aachat.step_completion }} in task files. You can delete starter files you no longer need. The schema is a closed object, so reader is required and undeclared input keys are rejected. The Step returns greeting, and the top-level mapping also exposes it as the Run's result.

Validate, try, and publish

From the workspace root, validate by Bundle path, then try the Draft if useful.

chat workflow validate aachat/teams/<team>/projects/<project>/workflows/greeting
chat workflow run --draft aachat/teams/<team>/projects/<project>/workflows/greeting --stdin <<'JSON'
{"reader":"Alex"}
JSON

Validation calls the server to check Project agents, Runtime config, and, for child Workflows, the pinned current published Revision. It is not an offline YAML check. Success returns valid: true. Fix the field or file named by an error. A project_path_not_available_here entry in warnings means a Step prompt names another Project's aachat/teams/<team>/projects/<project>/… path; it does not block. A Step Session works only in the Workflow's own Project, so keep that text in the Bundle and read it from $AA_WORKFLOW_DIR, or pass it as Run input.

A Draft Run starts real agent work, so use appropriate input and check the returned Run ID with status before moving on. A successful Draft Run is useful evidence but not a requirement for publishing. publish and run --draft wait up to 60 seconds for your latest local edits to reach the server Draft before sending.

Publish the Draft, confirm the input and output contract, then start the published version. The WebUI Publish does the same publish.

chat workflow publish aachat/teams/<team>/projects/<project>/workflows/greeting
chat workflow show greeting --project <team>/<project>

Publishing saves a snapshot of the files and moves the Published reference. The Draft files do not change. In show, read the published Revision's inputs and outputs and each Step's key, kind, and needs. Also check each Session Step's agent_name and, when set, runtime_kind (absent on Steps that use the agent default), and each child Workflow's workflow_slug with the workflow_revision_id this Revision pins. Run show on the child slug and compare its top-level revision_id: equal means the parent runs the child's current published version; different means the parent still pins an older one. steps is a map keyed by step key. The Revision's execution order is the key order in topological_order, which does not guarantee that independent Steps run serially. show does not start a Run and does not show prompt bodies, secrets, or every Step inside a child Workflow. After checking, start the published version.

chat workflow run greeting --project <team>/<project> --stdin --wait <<'JSON'
{"reader":"Alex"}
JSON

The run response includes accepted: true, run, available_actions, and created. --wait starts the Run and registers a durable wait for the source Session; the command itself returns immediately. After acceptance, end the source agent's turn, do not poll, and read the result after the continuation. --wait cannot be used inside a Workflow Attempt Session.

Runtime for one Run

To choose a runtime for one Run, add --runtime claude-acp or --runtime codex-acp to published or Draft runs. The Web Run dialog offers Runtime for this run with Use workflow settings (default), Claude Code, and Codex. The selection applies to all Session Steps, retries, and child Runs created by Workflow Steps; independently started Runs do not inherit it. Workflow definitions and Agent defaults are unchanged. Steps that switch runtime use that runtime's Agent defaults at Session acceptance; same-runtime Step settings remain. Run details, CLI receipts, lists and status show the saved runtime_override; Attempt requested settings show what was resolved.

Startup of the Sessions it started

When a Run is created, the server waits up to 40 seconds for the Step Sessions it started and returns them as startups[] with run_id, step_key, session_id, and startup. startup.state means:

Rerun after a lost response

If the connection drops or you get operation_outcome_unknown, rerun the same chat workflow run command as is. Without --client-nonce, the request identity is derived from the Session, Project, Workflow, input, and runtime, so the Run already started is returned with created: false. Pass a new UUID as --client-nonce only to deliberately start another Run with the same input. For --draft, a rerun after the sync advanced the Draft baseline starts a new Run, so read chat workflow runs <slug> first. Recovery commands in errors for a published Run include --project <team>/<project> and the same --client-nonce and --runtime (when specified), so they work from any cwd within the Session.

run --draft accepts an older local baseline when the complete Bundle matches the current Draft (differences in file order are tolerated). Different content, a future version, or a baseline from before an archive/restore is rejected as a conflict.

Check the Run's result

chat workflow status <run-id> --project <team>/<project>
chat workflow runs greeting --project <team>/<project>

In the successful example, the Run returns outputs such as {"greeting":"Welcome, Alex!"}. The sentence is generated, so an exact match is not guaranteed. Before success there is no outputs key. Without top-level output declarations, the value after success is {}. Check both the Run state and the actual result or linked content. Each runs item includes that Run's input and, after success, outputs, but free-text strings are cut to 100-character previews and marked truncated: true. Read the full values with the status command given in each item's detail_read.

chat workflow status <run-id> --detail returns the latest Attempt's saved Session token_usage for each Step/item and its launch-time model settings in observed_launch. Read earlier Attempts with attempts (follow next_page) and one Attempt with attempt. The five counters are input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, and turn_count. Ordinary status keeps usage but omits observed_launch.

These are Session totals at read time, not Step or Run totals: they include only saved completed turns, can grow after an Attempt ends, and do not add child Runs or separate Sessions. Omission means no Session value is available; zero is a saved value, not proof of zero consumption or complete measurement. Runtime-internal subagent coverage is unverified. Launch settings do not establish the model used for every turn: match the model option's id to applied_config_options[].config_id; proof: observed means observed, ack means acknowledged only, and an option without an application record is a launch snapshot. Keep aliases as returned and do not substitute requested settings for missing observations.

Run from the WebUI

Press Run in the Workflow header to open the Run <name> dialog. It runs the latest published Revision and does not include unpublished Draft changes. The form is built from the published input schema. When every top-level input is a string, number, integer, or boolean (including enums), each is a form field; if any input is an object or array, the whole input is entered as one JSON object. Press Run workflow; once accepted, the Run detail opens.

Run is disabled or shows a reason in these cases:

If the network outcome is unknown, the button changes to Retry request. It resends the same input with the same request identity, so no duplicate Run is created. If an already created Run is confirmed, Run accepted. Open its details to check progress. is shown and that Run opens.

Complete a Session Step

The agent writes the greeting and ends that task turn normally. When the Workflow sends its separate completion instructions, the agent submits the value. If you add follow-ups, all of them run in the same Session before completion.

chat workflow complete --stdin <<'JSON'
{"outcome":"succeeded","outputs":{"greeting":"Welcome, Alex!"}}
JSON

If it cannot finish, it sends the cause and the next required action. error must be non-empty and at most 4 KiB.

chat workflow complete --stdin <<'JSON'
{"outcome":"failed","error":"Required source is unavailable; restore access before retrying."}
JSON

The completion intent is accepted only when the command's JSON response contains "accepted": true. A timeout, input echoed to the terminal, or the last chat reply does not confirm acceptance. On a network error, resend exactly the same JSON payload in the same non-interactive form. After acceptance, do not start new work; finish the current response normally. Acceptance does not mean the whole Run succeeded. Do not substitute chat session finish.

If a Session Step needs an unplanned human decision, create a Project Ask, register it with chat wait --all --ask <ask-id> --project <team>/<project>, and end the turn without completing the Step. The Step shows waiting_for_decision. After the answer or cancellation, the same Session continues once. Read chat ask show <team>/<project> <ask-id> and continue the current task; submit success when the final completion instructions arrive. A Workflow Step can wait on Project Asks it created and ordinary direct child Sessions of the same Agent and home Project. It cannot wait on Runs, other Steps, or Sessions of another Agent or home Project. Only one unresolved group is allowed. The Step stays running when only children remain unresolved, and shows waiting_for_decision while an Ask is unresolved. The original Step reads the results, continues its current and remaining tasks, and completes using the final completion instructions. If it waited within those instructions, it submits using the instructions already received.

In schema 2 or 3, chat session finish returns workflow_session_managed; end the current turn normally instead of retrying. Idle time between tasks or while waiting for an Ask keeps the Session open. To interrupt it, use Stop or cancel the Run. Success submitted before completion instructions is rejected with workflow_completion_not_ready; failure can be submitted during a task.

Completion acceptance reserves closure. After the completion turn, Asset Wrap-Up organizes and saves results; final synchronization and Runtime shutdown make the Session terminal. Only then is the Step result settled and downstream work eligible to start. Wrap-Up does not change accepted outputs: an accepted success and a later Wrap-Up failure remain separate facts. Without a completion submission, closure through Wrap-Up produces completion_missing. Step retry begins again from the first task in a new Attempt and Session.

To add tasks in the same Session, use ordered session.follow_ups (definition reference). Retired schema 1 Runs are read-only history. Start a new Run from the migrated schema 2/3 Workflow to run the work again.

A Run is also read-only when its composed parent/child operation includes a retired Revision, even if its own Revision uses schema 2 or 3. The server reports this as execution_retired; start a new Run from the migrated published Workflow.

Human decisions and reusable children

A planned Decision Step creates a Project Ask for the human who started the Run, or for the human owner of the agent that started it. Decision definitions have no assignee field. Answer in the Ask card in the Run detail or on the Project's Ask screen. The Run pins the answer revision and uses it as the output {"answer": "..."}. Editing the Ask answer later does not change this output. waiting_for_decision is an in-progress state, not a failure. It is a business decision, not a coding Runtime asking permission for a tool action. The answer is data for later Steps. Branching requires an explicit when as shown below, and an answer never grants deploy authority.

A Workflow Step can call a published Workflow. Refer to one with the same owner as <slug> and to a Team Workflow as team:<slug>. The child's Revision is pinned, and composition is one level only. See the definition reference for complete Decision and child examples, typed input bindings, and limits.

Choose a branch and collect its result

This example asks which note to prepare, works in one branch, and publishes the join's summary. It does not publish or deploy anything. As with greeting, look up Project members, then run chat workflow init choose-note --project <team>/<project> (choose another slug if taken). Replace the Draft's workflow.yaml with the following and replace the three writer.yourname values with a real member.

schema_version: 2
name: choose-note
description: Choose a note, then summarize the branch result.
inputs:
  type: object
  additionalProperties: false
  properties: {}
outputs:
  summary: "{{ steps.summary.outputs.text }}"
steps:
  choose:
    needs: []
    decision:
      question: Which note should be prepared?
      body: { file: prompts/choose.md }
      options: [Draft, Hold]
  draft:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      equals: Draft
    session:
      agent: writer.yourname
      prompt: { file: prompts/draft.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  interpret:
    needs: [choose]
    when:
      value: "{{ steps.choose.outputs.answer }}"
      otherwise: true
    session:
      agent: writer.yourname
      prompt: { file: prompts/interpret.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]
  summary:
    needs: [draft, interpret]
    join: true
    session:
      agent: writer.yourname
      prompt: { file: prompts/summary.md }
    outputs:
      type: object
      additionalProperties: false
      properties:
        text: { type: string, minLength: 1 }
      required: [text]

Create prompts/choose.md in the same Draft.

Choose Draft for a short planning note, or Hold to record that work is on hold.
You may also describe your conditions in your own words.

Create prompts/draft.md in the same Draft.

Return a short planning note in text. Do not publish or deploy anything.

Create prompts/interpret.md in the same Draft.

The human answered: {{ steps.choose.outputs.answer }}
Return a note in text preserving the answer and any conditions. Do not infer
approval or carry out the requested work. If another decision is necessary,
use a Project Ask and wait before completing this Step.

Create prompts/summary.md in the same Draft.

Read the attached Workflow dependency results. Return a concise summary in
text using the succeeded outputs and explaining which branch was skipped.
Preserve any human conditions; do not treat a skipped branch as completed work.
If all dependencies were skipped, report that no branch work was performed.

Validate, and try the Draft with an empty input object if useful.

chat workflow validate aachat/teams/<team>/projects/<project>/workflows/choose-note
chat workflow run --draft aachat/teams/<team>/projects/<project>/workflows/choose-note --stdin <<'JSON'
{}
JSON

Open the returned Run in the WebUI and answer the Ask. An exact Draft runs draft and skips interpret. Hold or a free-text answer runs interpret and skips draft. Draft, after review is free text and is not treated as approval for the Draft branch. Editing the Ask later does not change the answer this Run adopted. If interpret needs another decision, it uses the Ask/wait procedure above before completing.

When the chosen branch succeeds, summary reads its accepted outputs and the other branch's skip reason. Each running Session follows its generated instructions and sends a completion matching its own schema. For example, the summary Attempt may send {"outcome":"succeeded","outputs":{"text":"Work is on hold; the draft branch was skipped."}} only when that matches the actual result. accepted: true means that Step's completion was accepted, not that the whole Run succeeded.

Use chat workflow status <run-id> --project <team>/<project> to check that the Run succeeded, that outputs.summary exists, and that the content is what you expected. Missing outputs do not mean success with an empty result. Before handing it on, check for Steps still in progress, completion acceptance, and output_error. With child Workflows, check the parent too; a child's success alone does not prove the parent accepted its output. After the trial, continue to publish and a published Run as in the earlier procedure, using slug choose-note and input {}.

In this Decision example, one of the two branches is always chosen after the answer. With boolean or enum conditions, an uncovered value can skip every branch. The join still runs and reports that no branch work was done; ordinary downstream Steps skip. Do not count skipped work as done, and do not retry to force a branch. If the choice was not what you intended, fix the Draft or input and use a new Run.

Read the Run and recover

Reading the Run detail

In the WebUI, open a Run from a Workflow's Runs tab or the Work Panel. The page is arranged vertically:

1. A back link, Run · date/time, and launch origin. The menu offers Run details and, while cancellable, Stop run…; after settlement it offers Run again and Compare when available. The stop confirmation and its action both say Stop this run? A child Run directs you to its parent for actions.
2. One sentence describing progress, followed by the pinned Revision's Input → Step → Result dependency diagram. Nodes show Agent icons and status marks; unstarted Steps are faded. Lines represent dependencies, not the path actually executed. Opening the Run selects a waiting or failed Step, or Result for a completed Run; an explicit URL selection is restored.
3. The selected content below the diagram. Result shows output values and their source Steps. A Step has one main action, such as Open session, Retry step, or answering its Ask. Retried Steps have a Try N of M selector for previous Attempts.
4. The Step's Output and Instructions tabs. Instructions show the full rendered Initial, Follow-up, and Completion instructions in order, with their submission times. A time records durable submission to the Session, not confirmation that the Runtime read it. Unsent instructions say Not sent yet; unavailable historical timestamps are not invented. Runtime/model and Edit in workflow appear below. There is no Messages tab; use Open session to read the conversation. Open session opens the Session in the right panel while keeping the Run detail and selected Step in place.
5. Feedback stays below the tabs, with a description, existing notes, a multiline input, and Save feedback. It is not hidden by changing tabs.

A Decision Step shows the Ask card directly, with Open in Asks. After an answer is adopted it shows Used by this run · answer N. Open … moves to another screen; Go to … changes the selection on this screen. A Step Session shows Workflow name › Step name and Back to run, with The step finishes when the agent reports its result. only when it needs a reply.

The visible status labels are Working, Needs reply, Needs answer, Done, Failed, Not started, Skipped, and Cancelled. Working uses the Session flow indicator, waiting states a teal dot, Done a pink check, and Failed a red mark. Labels, backgrounds, and borders remain neutral. Needs reply reflects a running Step whose Session has no active or reserved turn, independently of unread state. CLI state names below remain unchanged.

In the CLI, chat workflow status <run-id> returns a summary of every Step plus available_actions. status --detail returns the complete record, including the definition, inputs, prompts, launch facts, and feedback bodies. Read earlier Attempts with chat workflow attempts <run-id> --step <key>, and one Attempt's rendered prompt, completion intent, and feedback with chat workflow attempt <attempt-id>. available_actions reflects the state and authority when read and is rechecked when you act.

Run states

A Run has no failed state. Step states are pending, blocked, starting, running, waiting_for_decision, attention_required, succeeded, failed, cancelled, and skipped. chat workflow runs --state <state> returns only Runs whose overall state matches. On the first page, items: [] with next_page: null means there are none.

Next action by state

The stop dialog’s Reason (optional) field and both CLIs’ --reason option can record a reason. Leaving it empty still stops the Run. The first cancellation stores up to 2,000 UTF-8 bytes after trimming surrounding whitespace and cannot be overwritten. Read it in Run details → Stop reason, Run status (cancellation_reason), or the existing wait completion notification. A reason does not authorize a new Run or retry.

Wait on several Runs, hand results onward

To judge several root Runs together, start each without --wait and register them explicitly in one wait.

chat wait --all --workflow <first-run-id> --workflow <second-run-id> --project <team>/<project>

Child Runs are owned by their parent and cannot be wait targets. After the continuation, read each result with the notification's Read: commands. Settling includes attention and cancellation; a completed wait does not guarantee success.

To pass a successful result to the next Workflow, read both schemas and select only keys that the next closed input object accepts. If a save-greeting Workflow declares greeting as input, you can pass it like this:

chat workflow status <run-id> --project <team>/<project> | jq '.data.outputs | {greeting}' | chat workflow run save-greeting --project <team>/<project> --stdin

Run this only after confirming the Run is succeeded and has outputs. Do not pipe a failed status into the next Run. Store large results in Shared Documents or Media and return short references. Completion and Run outputs are limited to 128 KiB and JSON depth 32. On workflow_completion_limit_exceeded, make the output smaller and run a corrected new Run. A previously succeeded Run may return output_error instead of oversized outputs.

Compare two Runs

You can read the inputs, results, and feedback of two different Runs of the same Workflow in the same Project side by side. This does not score quality or infer causes.

In the WebUI, check exactly two Runs in the Workflow's Runs list and press Compare runs. The comparison page shows:

• Run A and Run B: each Run's state, Draft or published, and the time it was read. Different revisions appears when their Revisions differ.
• Inputs (Same inputs / Different inputs), Final results, and one tab per Step key. Steps are matched by the exact same key; renames are not inferred. Step type changed appears when a Step's kind differs.
• A Step tab shows each Run's latest Attempt and all feedback. Each feedback item's Include in request checkbox selects it as evidence for an improvement request.
• The two Runs are independent snapshots and do not update automatically. Press Refresh comparison to see new retries or feedback. Close comparison returns to the left Run's detail.

In the CLI, pass two full Run UUIDs.

chat workflow compare <left-run-id> <right-run-id> --project <team>/<project> [--step <key>] [--detail]

Use Definition changes to inspect each Run's fixed source files and resolved definition. Select a Step to read its instruction changes directly above its results, Attempts and feedback. Same inputs / Different inputs keeps input conditions visible. Published and trial Runs both use their saved versions; current Draft or published content is never substituted. Read and copy either side's full text, including empty files distinguished from absent files. CLI summaries list changes; --detail includes the fixed definitions, Bundles and complete left/right values. This evidence helps you decide what to try next; it does not automatically establish improvement.

The default summarizes input equality, the states of corresponding Steps, and feedback counts. --detail includes inputs, results, all feedback, and Attempt read commands. Object key order in inputs is ignored; array order, types, values, and missing keys are significant. Reading all feedback is unbounded, and --step does not reduce network bytes. Comparing does not start a Session, publish, run, or change any Draft.

Improve the next Revision

When a prompt, input, output schema, or agent assignment caused a concrete problem, leave feedback on the Attempt. Feedback is an observation note that does not change how the Run executes. Recording it does not start a rerun and does not change the prompt.

In the WebUI, the Feedback section in the Run detail's Result or below a Step's tabs always shows the target Step and Attempt (for example write · Attempt 1) and existing notes. Type and press Save feedback to see Feedback saved. If saving fails, Feedback could not be saved. Check the Step and retry. appears and your text is kept. Steps that have not started or were skipped cannot receive feedback. People other than collaborators/admins see Only project collaborators can add feedback.

In the CLI, use chat workflow feedback --stdin from the current Attempt Session, or specify the Run ID and Step from elsewhere. --attempt N selects the Attempt number; without it, the latest Attempt is used. --attempt cannot be used from the current Attempt Session.

chat workflow feedback <run-id> --step write --project <team>/<project> --stdin <<'TEXT'
The prompt did not specify the reader's language. Add a language input before the next revision.
TEXT

The body is plain text, trimmed, non-empty, and at most 8,192 bytes. Do not assign made-up scores. status shows each Step's feedback_count; read the bodies with status --detail or attempt <attempt-id>.

The WebUI's Ask an agent to improve prepares a new Session draft requesting the improvement and moves to the Session input. Pressed from a Workflow file view, it includes the Project, Draft path, and Workflow slug; pressed from the comparison page, it also includes both Runs, their Revisions and read times, the selected feedback, and the comparison read command. If another draft already exists, Replace the current session draft? appears: Keep my draft keeps it, and Replace draft replaces it. Review the prepared prompt, choose the agent and Runtime, and send to start the improvement Session. Preparing the draft does not start a Session. The request excludes publishing, starting Runs, and changing agent assets. Open the started Session to follow its edits, validate the Draft, try it if useful, and publish the next Revision. Existing Runs keep their pinned Revision.

Edit prompt wording in the WebUI

Open Files in the Workflow detail and select a file and use Edit for an existing Session prompt or Decision body. Check Markdown with Preview, then Save draft. Shared files list their referring Steps; edits apply to all those references. README, structural files, and Decision questions/options are outside this editor. From a Project's Team Workflow, Manage in Team opens the same file at its shared owner.

Unsaved changes disable Publish, Run creation, and improvement requests. Navigation and Cancel ask before discarding them. While saving, input, Cancel, and Step/file switching are disabled too. On conflict, copy your changes and use Reload latest; the editor replaces them only after you confirm discard. Network failures keep your input. If the save result is unknown, use Check save result. Requests are never automatically resent.

After saving, use Publish to apply the changes to new Runs. Saving the Draft alone changes neither the published revision nor existing Runs.

Archive and restore

Choose Archive from the Workflow detail's menu to stop new Runs. The Workflow remains in the list as Inactive · archived. The confirmation shows Triggers that will pause, Runs that will continue, and published parent Workflows that block archiving. If a parent blocks it, update and republish that parent or archive it first. The Draft, published Revisions, and Run history are kept; existing Runs can still continue later Steps, complete, retry, and cancel.

Open an Inactive · archived row and choose Restore to restore the same Workflow. If a child Workflow it references is archived, restore the child first. Restoring does not resume Triggers (Workflow restored. Paused Triggers remain paused.). Check each Trigger's input and schedule in Triggers, then resume it individually. Permanent deletion and slug reuse are not offered.

For a Project-owned Workflow, use chat workflow archive <slug> --project <team>/<project> and chat workflow restore <slug> --project <team>/<project>. For a Team-owned one, use chat workflow archive team:<slug> and chat workflow restore team:<slug>. An optional --project <team>/<project> on the Team form only checks the Team and does not switch the owner. Add --preview to inspect the effect without changing anything; passing the response's workflow.lifecycle_version and confirmation_token as --expected-lifecycle-version <N> --confirmation-token <token> applies exactly what you previewed. If the state changed since the preview, it is rejected; preview again. Archiving a Team Workflow also pauses every Project's Triggers for it, and each Project resumes its own after restore.

chat workflow list --archived --project <team>/<project> lists archived Workflows, including unpublished Drafts. While archived, the Draft stays at the same path, but the server rejects edits, publishes, and new Runs. Restore before changing files. Archive and restore invalidate earlier Draft baselines: after restoring, retrieve the latest files, review any local edits you kept, and save them again before publishing. Deleting the local directory does not archive or delete the Workflow.