> ## 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.

# Use Orchestrations intelligently

> Learn when to use Sofie Orchestrations, how to design reliable workflows, and how to test, publish, run, and maintain them.

An Orchestration turns a repeatable Sofie workflow into a reusable process. Use it when you want the same kind of work to happen with different inputs, consistent review points, and a predictable output.

Orchestrations are most useful when you treat them like a designed workflow, not a long prompt. A good Orchestration tells Sofie what to ask for, what sources to use, what each step should produce, where a person must review the work, and what the final result should look like.

<Note>
  Chat is still the main way to interact with Sofie. Use chat for one-off work and exploration. Use Orchestrations when the process itself should be reused.
</Note>

## Choose the right Sofie surface

Start by deciding whether you need an Orchestration at all.

| Need                                                                      | Use              |
| ------------------------------------------------------------------------- | ---------------- |
| One question or one analysis pass                                         | Chat             |
| A complex one-time task that should be planned first                      | **Plan Mode**    |
| A reusable instruction you paste into chat                                | **Saved prompt** |
| A document deliverable                                                    | CoDraft          |
| A spreadsheet, tracker, or analysis table                                 | CoSheet          |
| A shared source set                                                       | Workspace        |
| A repeatable workflow with inputs, steps, tools, tests, and review points | Orchestration    |

Good Orchestration candidates have three traits:

* The same workflow repeats for many projects, batches, documents, studies, products, or investigations.
* Users can provide a consistent set of inputs.
* The output can be reviewed against expectations.

Poor Orchestration candidates are usually broad, exploratory, or dependent on hidden context. Start those in chat, then convert the useful pattern into an Orchestration later.

## Define the workflow before you build

Before creating agents or tasks, write the workflow in plain language.

Use this structure:

```text theme={null}
Workflow name:
Who runs it:
When they run it:
Required inputs:
Optional inputs:
Source priority:
Steps:
Human review points:
Output:
Stop conditions:
What Sofie should not infer:
```

Example:

```text theme={null}
Workflow name: CAPA effectiveness check
Who runs it: QA owner or process SME
When they run it: After the observation window closes
Required inputs: CAPA plan, effectiveness criteria, observation window, evidence files, metrics CoSheet, Workspace
Optional inputs: related deviations, prior CAPAs, meeting notes
Source priority: CAPA plan and effectiveness criteria outweigh prior discussion
Steps: collect criteria, review evidence, analyze metrics, identify gaps, draft review table, pause for human review, draft final CoDraft section
Human review points: before effectiveness conclusion and before CoDraft creation
Output: CoDraft report section plus evidence table
Stop conditions: missing criteria, missing evidence, conflicting source dates, unclear metric ownership
What Sofie should not infer: acceptance criteria, thresholds, owner decisions, or final disposition
```

This blueprint makes the editor work easier. It also gives Sofie a better prompt if you build the Orchestration from chat.

## Understand the main settings

The Orchestration editor includes settings that change how a run behaves. Set these before you tune individual agents and tasks.

| Setting                                   | What it controls                                                                         | Use it intelligently                                                                                                                                        |
| ----------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Process Type**                          | Whether tasks run as a **Sequential** process or a **Hierarchical** process.             | Use **Sequential** when task order is fixed. Use **Hierarchical** when a manager-style planning step should coordinate agents and tasks.                    |
| **Enable Planning**                       | Whether a hierarchical Orchestration creates a plan before work is delegated.            | Turn it on for complex work with branching, source gathering, or multiple review points. It is not available in sequential mode.                            |
| **Short-Term Memory (Within Run)**        | Whether tasks can save and retrieve useful information from other tasks in the same run. | Use it when later tasks need findings from earlier tasks but should not receive a giant copied transcript.                                                  |
| **Long-Term Memory (Cross-Run Learning)** | Whether agents can save general lessons from prior runs and use them in future runs.     | Use it for stable workflow lessons, recurring reviewer preferences, and repeated process patterns. Do not use it as the source of record for project facts. |
| **Max Requests Per Minute**               | The run's request pacing.                                                                | Lower it when runs hit service limits or use many source/tool steps. Avoid increasing it unless your environment supports the load.                         |
| **Require Citations**                     | Whether responses should include citations.                                              | Use it for source-backed research, evidence review, and quality workflows. Still review the cited sources yourself.                                         |
| **Allow Parallel Task Execution**         | Whether independent tasks may run at the same time.                                      | Use it for independent source reviews or analyses. Turn it off when every task depends on the exact output of the previous task.                            |

<Tip>
  If you are not sure, start with hierarchical planning on, citations on for source-backed work, parallel execution on only for independent tasks, and memory off until you know what should be learned.
</Tip>

## Design around inputs

Inputs are the contract between the person running the Orchestration and the workflow.

Good inputs are specific:

| Weak input  | Better input                    |
| ----------- | ------------------------------- |
| `Files`     | `Deviation evidence files`      |
| `Info`      | `Deviation description`         |
| `Data`      | `Effectiveness metrics CoSheet` |
| `Document`  | `CAPA plan CoDraft`             |
| `Workspace` | `Investigation Workspace`       |
| `Date`      | `Observation window end date`   |

For each input, make the user-facing **Label** and **Description** do real work. Tell users what to provide, when to use the input, and what happens if it is missing.

Use required inputs for material that the workflow cannot evaluate without. Use optional inputs for helpful context that should not block the run.

Input types can include **Text**, **Number**, **Yes/No**, **Dropdown**, **Date**, **Workspace**, **File**, **Orchestration**, **CoMeeting**, **CoDraft**, and **CoSheet**. Use **Single** when the workflow needs one value. Use **Multiple** when the user may provide several files, documents, meetings, or sheets.

Reference inputs inside agent and task instructions with curly braces, such as `{Investigation Workspace}` or `{CAPA plan CoDraft}`. This keeps the workflow reusable because the instruction points to the run's selected input instead of today's example file.

Use dropdown inputs when you want users to choose from a controlled list, such as `Review focus`, `Product type`, `Investigation phase`, or `Output destination`.

<Tip>
  If users routinely ask, "What should I upload here?", the input description is not specific enough.
</Tip>

## Set source rules

Most weak Orchestration runs come from vague source handling. Tell the workflow what sources matter and what to do when they conflict.

Include source rules such as:

* Use the selected Workspace as the project source set.
* Use **Workspace search** for project files before using older chat assumptions.
* Treat attached files as the current run's evidence.
* Use CoDraft templates for structure, not as factual evidence unless the user says so.
* Use CoMeeting transcripts as discussion context, not final source decisions.
* If sources conflict, list the conflict instead of resolving it silently.
* If a required source is missing, pause and ask for it.

Good source instruction:

```text theme={null}
Use the CAPA plan and effectiveness criteria as the primary sources. Use the metrics CoSheet for observed results. Use meeting notes only to identify open questions. If the sources conflict, list the conflict and pause before drafting a conclusion.
```

## Use agents only when roles are different

Agents are useful when the workflow needs different responsibilities. They are not useful when they only split one task into more names.

Good agent roles:

* Evidence reviewer.
* Data analyst.
* Source gap reviewer.
* Report drafter.
* Quality reviewer.
* Researcher.

Avoid agents that overlap heavily:

* `Expert 1`, `Expert 2`, `Expert 3`.
* `Reviewer` and `Checker` with the same instructions.
* A general `Quality expert` expected to do every step.

Use one agent when the work is simple. Add more agents when you need different source handling, different outputs, or an independent review step.

## Use agent memory carefully

Agent memory is useful, but it can also make a workflow harder to reason about if you use it for the wrong information.

Use **Short-Term Memory (Within Run)** when tasks in the same run need to pass forward useful discoveries:

* The evidence reviewer finds a missing batch record page.
* The data analyst identifies outlier lots that the drafter must mention.
* The researcher finds a source conflict that the reviewer must resolve.

Use **Long-Term Memory (Cross-Run Learning)** when the agent should learn general patterns across runs:

* A QA reviewer repeatedly asks for facts, assumptions, gaps, and SME questions to be separated.
* A report drafter learns the preferred structure for a recurring CoDraft template.
* A data analyst learns that a specific metric should be explained with the same caveat.

Do not use long-term memory for project facts, batch-specific findings, source conclusions, acceptance criteria, or final decisions. Put those in the current inputs, Workspace, CoDraft, CoSheet, or reviewed source material.

You can inspect agent memories from the agent's **Long-Term Memories** tab. Review and delete stale memories when they no longer reflect how the workflow should behave.

<Warning>
  Long-term memory can influence future runs. Keep it for reusable workflow lessons, not regulated source facts or one-time project decisions.
</Warning>

## Make each task reviewable

A task should produce something a person can inspect before trusting the next step.

Weak task:

```text theme={null}
Analyze the investigation and write the report.
```

Better task sequence:

```text theme={null}
Extract confirmed facts from the deviation description, batch record, and evidence files. Return a table with source, fact, date, and uncertainty.
```

```text theme={null}
Identify source gaps and SME questions. Do not propose root cause.
```

```text theme={null}
Draft the investigation report background section from the confirmed facts table. Include placeholders where evidence is missing.
```

Good task outputs are:

* Specific.
* Source-aware.
* Limited to one kind of work.
* Easy to compare against the expected output.
* Clear about what Sofie should not decide.

Use **Plan Text** when a task needs to expose or follow a specific plan. This helps reviewers understand why the task is doing the work in that order.

## Choose output modes deliberately

Use the output mode that matches how the result will be reviewed or reused.

| Output mode           | Use it when                                                          | Example                                                            |
| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Text Output**       | A person will read a narrative, list, or table in the run result.    | Investigation summary, source gaps, review notes.                  |
| **Structured Output** | Later tasks or tests need named fields and repeatable sections.      | Findings array, metric assessment fields, risk table rows.         |
| **Fill Template**     | The workflow should populate a CoDraft template.                     | Validation protocol section, CAPA report, URS draft.               |
| **Surface**           | The task should refresh a reusable visual or interactive experience. | Monthly metrics dashboard, program tracker, recurring review deck. |

Use **Structured Output** when the answer must be checked field by field or handed to another agent. Use **Fill Template** when you already know the document structure and want the Orchestration to fill defined placeholders. Use **Surface** when a task should update a defined Surface part and leave a traceable source record. For detailed schema patterns, see [Structured Outputs](/orchestrate/structured-outputs). For Surface mapping, see [Refresh a Surface with an Orchestration](/surfaces/refresh-with-orchestrations).

Structured outputs can include fields such as text, numbers, yes/no values, dropdown choices, images, charts, objects, and lists. For each field, write a clear name, description, formatting guidance, and whether it is required or may appear multiple times.

When you use **Fill Template**, also decide whether the output should stay in the run result or save to a Workspace. Save to a Workspace only when the destination is clear and the user has reviewed the workflow behavior.

<Warning>
  Do not ask for a final conclusion as the first output. Build intermediate outputs that show evidence, gaps, assumptions, and questions before any final draft.
</Warning>

## Add tools with intent

Tools let an Orchestration do work beyond plain text generation. Add tools because a task needs a capability, not because the workflow might use it someday.

Use tools when the workflow needs to:

* Search selected Workspace content.
* Read or create CoDraft content.
* Analyze CoSheet data.
* Use CoMeeting context.
* Request human input.
* Create or update an artifact.
* Use connected app context when your organization enables it.

Fewer tools usually make the run easier to understand. If a task should only review a source table, do not give it artifact-creation responsibilities. If a task should only draft a CoDraft section, do not make it search broadly unless it needs new sources.

## Put human review before risk

Use **Require Human Review** when the workflow should pause before continuing.

Add review before:

* Drawing a root cause conclusion.
* Recommending CAPA effectiveness.
* Interpreting conflicting evidence.
* Creating a final CoDraft.
* Saving output to a shared Workspace.
* Sending or changing content in a connected app.
* Continuing after missing required sources.

Human review is a workflow control. It helps the person running the Orchestration check the intermediate result, answer questions, and decide whether the run should continue.

<Warning>
  A human review step in Sofie does not replace your organization's required review process. Use it to control the workflow and prepare work for the right reviewers.
</Warning>

## Build small, then expand

The first version should be the smallest useful Orchestration.

<Steps>
  <Step title="Create the core path">
    Build the required inputs, one or two agents, and the smallest task sequence that creates a useful output.
  </Step>

  <Step title="Run it with realistic inputs">
    Use a real Workspace, representative files, and a source set similar to what users will provide later.
  </Step>

  <Step title="Inspect the first failure">
    Look for vague inputs, missing source rules, unsupported conclusions, weak output shape, or late human review.
  </Step>

  <Step title="Fix one layer at a time">
    Improve inputs first, then task instructions, then tools, then output shape, then tests.
  </Step>

  <Step title="Save a version">
    Use **Save Current Version** before major changes so you can restore a known-good state.
  </Step>
</Steps>

Do not start by building the full future workflow. Start with the part users can run and review today.

## Test like a user will run it

Use tests to check whether the workflow still behaves the way you expect.

In the editor, use **Create Test** to define test inputs and expected task outputs. Use **Run Test** or **Run All Tests** after changes. If your workspace shows **Drift Detected**, review the drift before running the test again.

Test cases should cover:

* A normal source set.
* Missing optional inputs.
* Missing required evidence.
* Conflicting sources.
* A larger Workspace with irrelevant files.
* A CoSheet with unexpected blank values.
* A template output with required placeholders.
* A run that should pause for human review.

Good test expectation:

```text theme={null}
The evidence review task returns a table with one row per finding. Each row includes source, observation, source date, uncertainty, and follow-up question. The task must not include a final disposition.
```

Use **Validate Against Past Run** when you want to compare a test against prior run behavior. Use **Fix Drift Issues** when the Orchestration changed enough that the saved test no longer matches the current workflow.

For a full testing workflow, including saved-run baselines, validation methods, structured output checks, run history, drift, parallel execution, and long-term Memory behavior, see [Test Orchestrations](/orchestrate/test-orchestrations).

Choose validation strategies based on the output:

| Validation strategy | Use it for                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------- |
| **Exact**           | Stable labels, fixed statuses, and values that should not vary.                               |
| **Semantic**        | Wording that may vary while meaning should stay the same.                                     |
| **Contains**        | Required phrases, source names, warnings, or section headings.                                |
| **Regex**           | IDs, dates, codes, or formats that follow a pattern.                                          |
| **Length**          | Outputs that should stay within a reviewable size.                                            |
| **AI Judge**        | Qualitative checks such as accuracy, completeness, tone, missing support, or custom criteria. |

<Tip>
  Treat a failed test as workflow feedback. The fix might be a clearer input label, a narrower task, a stronger source rule, or an earlier review point.
</Tip>

## Publish only after users can run it

Keep an Orchestration private or shared with a small group while it is changing.

Publish to the organization when:

* The name and description tell users when to run it.
* Required inputs are clear.
* Optional inputs are helpful but not confusing.
* Source priority is explicit.
* Each task has a reviewable output.
* Human review happens before key decisions or shared outputs.
* Tests cover realistic inputs.
* A person other than the builder can run it without hidden context.

When you use **Publish to Organization**, organization members can view and run the Orchestration. Only owners and editors can modify it. If the workflow is no longer ready for broad use, use **Unpublish** and continue working with explicit collaborators.

## Share editing carefully

Use sharing to bring in people who can improve or review the workflow.

Suggested roles:

| Collaborator   | Useful contribution                                            |
| -------------- | -------------------------------------------------------------- |
| Process owner  | Confirms when the workflow should run and what outputs matter. |
| SME            | Checks source interpretation and missing evidence handling.    |
| QA reviewer    | Reviews assumptions, review points, and output structure.      |
| Data owner     | Checks CoSheet inputs and metric interpretation.               |
| Template owner | Confirms CoDraft template fields and placeholder meaning.      |

Give edit access to people who should change the workflow. Give view or run access to people who only need to use it.

## Run Orchestrations from chat intelligently

When you run an Orchestration from chat, Sofie starts by asking for required information if it is missing.

Good run request:

```text theme={null}
Run the CAPA effectiveness check Orchestration. Use the selected Workspace, the CAPA plan CoDraft, the metrics CoSheet, and the observation window from January 1, 2026 through March 31, 2026. Ask me before drafting the final conclusion.
```

Weak run request:

```text theme={null}
Run the CAPA one.
```

Before running, check:

* The Orchestration name is the one you intend to use.
* The Workspace and artifacts are the correct project.
* Attached files are current.
* Dates and options are unambiguous.
* Sofie should pause before any conclusion or artifact creation that needs review.

After the run completes, review the **Artifacts** section. It shows artifacts created or modified during the run when Sofie can track them. Open each artifact from the run result and confirm the right item was created, updated, or referenced.

Ask Sofie:

```text theme={null}
Review the artifacts from this Orchestration run. For each artifact, tell me whether it was created or modified, which task touched it, and what I should inspect before using it.
```

## Maintain Orchestrations over time

An Orchestration can become stale when source patterns, templates, team expectations, or review needs change.

Review important Orchestrations when:

* A template changes.
* The expected output changes.
* A new source type becomes common.
* Users report confusing inputs.
* Tests start failing.
* **Drift Detected** appears.
* A workflow produces unsupported or hard-to-review output.
* A published workflow should be limited again.

Use **Revision History** to inspect prior versions. Use **Save Current Version** before major edits. Use **Restore Revision** when a change made the workflow worse.

## Common problems and fixes

| Problem                                    | Likely cause                                            | Fix                                                                                                     |
| ------------------------------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Users provide the wrong files              | Input labels are too vague                              | Rename inputs and add specific descriptions.                                                            |
| Output mixes facts and assumptions         | Task instructions do not separate them                  | Require separate sections for facts, assumptions, gaps, and questions.                                  |
| Sofie reaches a conclusion too early       | Review point is too late or missing                     | Add **Require Human Review** before conclusion tasks.                                                   |
| Run searches unrelated material            | Source rules are too broad                              | Limit the Workspace, file set, or search scope.                                                         |
| Output is hard to test                     | Output shape is loose                                   | Use tables or **Structured Output** fields.                                                             |
| Run created or modified the wrong artifact | Output destination or artifact instruction is too loose | Tighten the task instruction, require a destination input, or add human review before artifact changes. |
| Workflow is too slow or noisy              | Too many agents or tools                                | Remove overlapping agents and unused tools.                                                             |
| Published workflow confuses users          | It assumes builder knowledge                            | Add a clearer description, required inputs, and example run guidance.                                   |
| Tests fail after edits                     | Workflow changed but test stayed old                    | Update the test or use drift repair after confirming the new behavior.                                  |

## Useful Orchestration prompts

Use these in chat before or after editing an Orchestration.

<Accordion title="Design before building">
  ```text theme={null}
  Design an Orchestration for this workflow before creating it. Return the workflow trigger, required inputs, optional inputs, source priority, agents, tasks, tools, output mode, human review points, tests, and stop conditions. Ask questions where the workflow is ambiguous.
  ```
</Accordion>

<Accordion title="Review an existing Orchestration">
  ```text theme={null}
  Review this Orchestration design. Identify vague inputs, overlapping agents, tasks that are too broad, missing source rules, missing human review points, and outputs that should be structured.
  ```
</Accordion>

<Accordion title="Create a test plan">
  ```text theme={null}
  Create a test plan for this Orchestration. Include normal inputs, missing-input cases, conflicting-source cases, large Workspace cases, and expected outputs for each task.
  ```
</Accordion>

<Accordion title="Improve a failed run">
  ```text theme={null}
  Review this Orchestration run. List where the run used the wrong context, skipped a source check, produced unsupported output, needed human review earlier, or created an output that was hard to review. Suggest exact edits to inputs, tasks, tools, and output mode.
  ```
</Accordion>

<Accordion title="Prepare for publishing">
  ```text theme={null}
  Check whether this Orchestration is ready to publish. Review the name, description, inputs, source rules, tasks, output modes, human review points, tests, and whether a new user could run it without hidden context.
  ```
</Accordion>

## Life sciences patterns

### Deviation investigation

Use the Orchestration to separate evidence collection from interpretation.

Recommended structure:

* Required inputs: deviation description, investigation Workspace, evidence files, batch or equipment references.
* Early task: confirmed facts and timeline.
* Middle task: source gaps and SME questions.
* Review point: before root cause analysis.
* Output: CoDraft investigation section with placeholders for unresolved evidence.

### CAPA effectiveness check

Use the Orchestration to make evidence and criteria visible before drafting.

Recommended structure:

* Required inputs: CAPA plan, effectiveness criteria, observation window, metrics CoSheet, evidence files.
* Early task: criteria extraction.
* Middle task: metric review and evidence table.
* Review point: before conclusion.
* Output: CoDraft section plus evidence table.

### Validation protocol generation

Use the Orchestration to move from source comparison to controlled drafting.

Recommended structure:

* Required inputs: URS, risk assessment, equipment or process description, protocol template, Workspace.
* Early task: source map and gaps.
* Middle task: protocol outline and test section plan.
* Review point: before acceptance criteria or final section generation.
* Output: filled CoDraft template with placeholders for SME confirmation.

### Batch record review

Use the Orchestration to keep exceptions, source references, and follow-up questions traceable.

Recommended structure:

* Required inputs: batch record file, product, batch number, review focus, Workspace.
* Early task: section inventory and missing pages.
* Middle task: exception table.
* Review point: before disposition language.
* Output: CoSheet tracker or CoDraft review summary.

## The standard to aim for

A strong Orchestration can be explained in one sentence:

```text theme={null}
When a user provides these inputs, Sofie follows these steps, uses these sources, pauses at these review points, and produces this reviewable output.
```

If you cannot fill in that sentence, keep designing in chat or **Plan Mode** before publishing the workflow.