Skip to main content
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.

​
Create or open an Orchestration

1

Open Orchestrate

Click Orchestrate in the sidebar.
2

Choose a starting point

Click Create, start from the Library, or open an existing Orchestration.
3

Name the workflow

Use a name that describes the repeatable job, such as Deviation investigation report draft.
4

Add a description

Describe who should run it, what inputs it expects, and what it creates.
5

Keep it in draft

Build and test as a draft until the workflow behaves consistently with realistic inputs.

​
Configure settings

Use the Settings tab to control how the Orchestration runs. For strategy guidance on these settings, see Use Orchestrations intelligently. For testing guidance on parallel execution, long-term Memory, validation methods, and run history, see 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: Good input labels:
  • Investigation Workspace
  • Deviation description
  • Evidence files
  • CAPA plan
  • Effectiveness criteria
  • Observation window
  • SME interview CoMeeting
  • Metrics CoSheet
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.
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: 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:
Better task:

​
Choose an output mode

Tasks can produce different kinds of output. 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. 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.
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.

​
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.
Human review inside Sofie controls the Orchestration flow. It does not replace your organization’s review or approval process outside Sofie.

​
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.
1

Open the run panel

Start a run from the Orchestration editor or the Orchestrate page.
2

Provide required inputs

Select the Workspace, files, CoDraft, CoMeeting, CoSheet, text, dates, or options the workflow asks for.
3

Watch task progress

Review each task as it runs. Stop the run if the workflow starts using the wrong context.
4

Complete human review steps

Answer questions or confirm task results when the workflow pauses for review.
5

Inspect the output

Check source references, assumptions, missing evidence, formatting, and any artifacts shown in the run result.
6

Refine the draft

Edit inputs, agents, tasks, tools, or output mode based on the test run.
Use this test prompt after a run:

​
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:
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: 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.

​
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. Chat is best for brainstorming the design. The editor is best for precise input, task, output, version, and publishing control.