> ## Documentation Index
> Fetch the complete documentation index at: https://sofiedocs.usetransfer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build and edit an Orchestration

> Create Orchestrations manually with inputs, agents, tasks, tools, output modes, review steps, versions, and test runs.

Use the Orchestration editor when you need detailed control over a reusable workflow. You can start from scratch, use the Library, upload an Orchestration file when available, or ask Sofie to draft the design from chat.

For design judgment before editing, see [Use Orchestrations intelligently](/orchestrate/use-orchestrations-intelligently).

## Create or open an Orchestration

<Steps>
  <Step title="Open Orchestrate">
    Click **Orchestrate** in the sidebar.
  </Step>

  <Step title="Choose a starting point">
    Click **Create**, start from the **Library**, or open an existing Orchestration.
  </Step>

  <Step title="Name the workflow">
    Use a name that describes the repeatable job, such as `Deviation investigation report draft`.
  </Step>

  <Step title="Add a description">
    Describe who should run it, what inputs it expects, and what it creates.
  </Step>

  <Step title="Keep it in draft">
    Build and test as a draft until the workflow behaves consistently with realistic inputs.
  </Step>
</Steps>

## Configure settings

Use the **Settings** tab to control how the Orchestration runs.

| Setting                                   | What to choose                                                                                           |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| **Name**                                  | A short workflow name users can recognize in chat and Orchestrate.                                       |
| **Description**                           | Who should run it, when to run it, required sources, and expected output.                                |
| **Process Type**                          | **Sequential** for fixed task order. **Hierarchical** when planning and delegation should guide the run. |
| **Max Requests Per Minute**               | The request pace for the run. Lower it when the workflow uses many source or tool steps.                 |
| **Enable Planning**                       | Available in hierarchical mode. Use it when Sofie should plan before delegating tasks.                   |
| **Short-Term Memory (Within Run)**        | Let tasks save and retrieve information from other tasks in the same run.                                |
| **Long-Term Memory (Cross-Run Learning)** | Let agents save general learnings across runs.                                                           |
| **Require Citations**                     | Ask tasks to cite sources where citations are available.                                                 |
| **Allow Parallel Task Execution**         | Let independent tasks run at the same time. Tasks with dependencies still run in order.                  |

For strategy guidance on these settings, see [Use Orchestrations intelligently](/orchestrate/use-orchestrations-intelligently). For testing guidance on parallel execution, long-term Memory, validation methods, and run history, see [Test Orchestrations](/orchestrate/test-orchestrations).

## Define inputs

Inputs are the information users provide when they run the Orchestration.

Input fields can describe artifacts, files, Workspace context, text values, dates, options, numbers, yes/no values, JSON, or tables. Depending on the workflow, you can allow a single value or multiple values.

For each input, write:

| Field            | How to use it                                                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Key              | A short identifier used by the Orchestration.                                                                                                                                |
| Label            | The user-facing name.                                                                                                                                                        |
| Description      | What the user should provide and why.                                                                                                                                        |
| Type             | The kind of input, such as **Text**, **Number**, **Yes/No**, **Dropdown**, **Date**, **Workspace**, **File**, **Orchestration**, **CoMeeting**, **CoDraft**, or **CoSheet**. |
| Multiplicity     | Use **Single** for one value or **Multiple** for several files, artifacts, or source items.                                                                                  |
| Required Mode    | Use **Required** when the workflow cannot run without it. Use **Optional** when the input improves the result but should not block the run.                                  |
| Default Value    | A fallback for optional inputs.                                                                                                                                              |
| Dropdown options | The allowed values for **Dropdown** inputs.                                                                                                                                  |

Good input labels:

* `Investigation Workspace`
* `Deviation description`
* `Evidence files`
* `CAPA plan`
* `Effectiveness criteria`
* `Observation window`
* `SME interview CoMeeting`
* `Metrics CoSheet`

<Tip>
  Define inputs before writing agents and tasks. You can insert inputs into task instructions so the workflow references the user’s exact sources and choices.
</Tip>

Reference inputs in agent goals, backstories, task descriptions, plan text, and expected outputs with curly braces, such as `{Investigation Workspace}` or `{Metrics CoSheet}`.

## Add agents

Agents are roles inside the Orchestration. Each agent should have a focused job.

Agent configuration can include:

| Field                  | Use it for                                                                               |
| ---------------------- | ---------------------------------------------------------------------------------------- |
| **Role**               | The persona or responsibility, such as investigator, reviewer, drafter, or data analyst. |
| **Goal**               | The outcome the agent is trying to produce.                                              |
| **Backstory**          | Context that helps the agent interpret the work.                                         |
| **Model**              | The AI model used by that agent when your organization offers choices.                   |
| **Max Steps**          | The amount of iterative work the agent can perform before stopping.                      |
| **Long-Term Memories** | Agent-specific memories learned across runs when long-term memory is enabled.            |

Keep agents specific. A `Deviation evidence reviewer` is easier to evaluate than a general `Quality expert`.

Open an agent's **Long-Term Memories** tab to inspect learned memories for that agent. Use long-term memory for general workflow lessons, not current-run source facts or final decisions.

## Add tasks

Tasks are the ordered work an agent performs.

For each task, define:

* **Name**
* **Description**
* **Output Mode**
* **Expected Output Description** for text output
* **Plan Text** when the task should explain or follow a plan
* **Require Human Review** when a person must confirm the result before the workflow continues

Write task descriptions as instructions, not goals.

Weak task:

```text theme={null}
Analyze the files.
```

Better task:

```text theme={null}
Review the evidence files for the deviation. Extract observed event details, immediate actions, affected batch or equipment identifiers, missing evidence, and direct source references. Do not conclude root cause.
```

## Choose an output mode

Tasks can produce different kinds of output.

| Output mode           | Use it when                                                                        |
| --------------------- | ---------------------------------------------------------------------------------- |
| **Text Output**       | The task should return prose, a list, or a table in the run result.                |
| **Structured Output** | Downstream tasks need named fields, typed values, or repeatable sections.          |
| **Fill Template**     | The result should populate a CoDraft template or defined deliverable structure.    |
| **Surface**           | The task should refresh a fixed or run-selected Surface with a structured payload. |

For **Structured Output**, click **Define Output** and define fields with clear names, types, descriptions, options, and formatting guidance. For deeper schema design guidance, see [Structured Outputs](/orchestrate/structured-outputs).

Structured output fields can include:

* Field name.
* Type.
* Description.
* Dropdown options when the type is **Dropdown**.
* Image prompt template when the type is **Image**.
* Chart type when the type is chart-oriented.
* Formatting guidance.
* Required setting.
* Allow multiple setting.

For **Fill Template**, choose the template and output location. Use **Run output only (no workspace)** while testing. Use **Save to workspace** only when the destination is clear.

For **Surface**, choose the target Surface, the part to update, and whether the task should replace, merge, or append data. Define the structured output the Surface expects. See [Refresh a Surface with an Orchestration](/surfaces/refresh-with-orchestrations).

<Warning>
  Do not make a task produce a final conclusion unless the input sources support it and the workflow includes a human review point where needed.
</Warning>

## Add tools

Tools give an Orchestration capabilities beyond text generation. Available tools depend on your organization and the workflow surface.

Use tools for tasks such as:

* Searching or reading provided context.
* Creating or updating artifacts.
* Requesting human input.
* Working with Workspace content.
* Producing structured files or documents.

Add only the tools the workflow needs. Too many tool choices can make runs harder to review.

## Add human review

Turn on **Require Human Review** for tasks that need confirmation before the workflow continues.

Use human review before:

* Drawing a root cause conclusion.
* Recommending CAPA effectiveness.
* Filling a final report section.
* Saving output to a shared Workspace.
* Using ambiguous source material.
* Continuing after missing or conflicting evidence.

<Note>
  Human review inside Sofie controls the Orchestration flow. It does not replace your organization’s review or approval process outside Sofie.
</Note>

## Use versions

Use version controls when changing a workflow that other people run.

Common version actions include:

* **Versions** to inspect prior saved versions.
* **Save Current Version** before a major edit.
* **Restore Revision** when a change should be undone.
* **Promote Draft to Live** when the draft is ready for others to run.
* **Discard Draft** when you do not want to keep draft changes.

Save a version before changing required inputs, output modes, or review points.

## Run a test

Run tests with realistic inputs before publishing.

<Steps>
  <Step title="Open the run panel">
    Start a run from the Orchestration editor or the Orchestrate page.
  </Step>

  <Step title="Provide required inputs">
    Select the Workspace, files, CoDraft, CoMeeting, CoSheet, text, dates, or options the workflow asks for.
  </Step>

  <Step title="Watch task progress">
    Review each task as it runs. Stop the run if the workflow starts using the wrong context.
  </Step>

  <Step title="Complete human review steps">
    Answer questions or confirm task results when the workflow pauses for review.
  </Step>

  <Step title="Inspect the output">
    Check source references, assumptions, missing evidence, formatting, and any artifacts shown in the run result.
  </Step>

  <Step title="Refine the draft">
    Edit inputs, agents, tasks, tools, or output mode based on the test run.
  </Step>
</Steps>

Use this test prompt after a run:

```text theme={null}
Review this Orchestration run. List unclear inputs, weak task instructions, missing review points, unsupported conclusions, and output fields that should be more structured.
```

## Inspect run artifacts

After a completed run, check the **Artifacts** section before you decide whether the workflow is ready.

The section shows artifacts the run created, modified, opened, reviewed, imported, or exported. It can appear in chat results, the run panel, and run history when artifacts are available.

Use it to confirm:

* The run created the expected artifact type.
* The title and destination are correct.
* Existing artifacts were modified only when intended.
* The task that touched the artifact was the right task.
* The artifact content matches the run output.
* Human review happened before important edits or saved outputs.

Good review prompt:

```text theme={null}
Review the artifacts from this run. Tell me which artifacts were created or modified, whether each one matches the expected output, and what I should inspect before publishing this Orchestration.
```

If the wrong artifact was created or changed, update the Orchestration before publishing. Usually that means tightening input labels, task instructions, output mode, destination rules, or human review steps.

When creating tests, match the validation method to the expected output:

| Validation method | Use it for                                                                                    |
| ----------------- | --------------------------------------------------------------------------------------------- |
| **Exact**         | Fixed values that should match exactly.                                                       |
| **Semantic**      | Meaning that can be correct with different wording.                                           |
| **Contains**      | Required terms, source names, warnings, or headings.                                          |
| **Regex**         | IDs, dates, batch numbers, or other patterns.                                                 |
| **Length**        | Guardrails on output size.                                                                    |
| **AI Judge**      | Qualitative checks such as accuracy, completeness, tone, missing support, or custom criteria. |

Use **Run All Tests** after major edits. Use **Validate Against Past Run** when you want to compare expected behavior with a prior run. If **Drift Detected** appears, review the drift before running the test again.

For detailed instructions on manual tests, saving successful runs as tests, structured validation, AI Judge criteria, drift repair, run history, and deterministic test design, see [Test Orchestrations](/orchestrate/test-orchestrations).

## Publish and share

Publish when:

* The required inputs are clear.
* The workflow handles missing information.
* Review points occur before conclusions or saves.
* The output is specific enough to review.
* A realistic test run produced useful results.
* The description tells users when to run it.

Share or publish only with the people who should run or edit the Orchestration. Keep drafts private or limited while the workflow is still changing.

## Build with Sofie chat

If you prefer to describe the workflow in plain language first, use [Build an Orchestration with Sofie chat](/orchestrate/build-with-chat). Chat is best for brainstorming the design. The editor is best for precise input, task, output, version, and publishing control.