Process Definition Files

A process definition is one text file, in YAML or JSON, that describes a whole process: its instructions and standing rules, the team and its agents, the procedure, the tools it may use and the triggers that start it. You can import a file to create or update a process, and export any process into a file.

Only organization owners and admins can import and export.

What It Is For

• Review before it goes live. A colleague reads one file instead of clicking through a dozen screens.
• Keep versions. Store the file with your other documents, and compare this month's version with last month's line by line.
• Move a process. Export it from one organization and import it into another. You get the same process, without rebuilding it by hand.
• Change many things at once. Edit the file and import it over the process.

What a File Looks Like

# yaml-language-server: $schema=https://smartstaff.io/api/schemas/process-definition/v1.json
schemaVersion: 1
slug: enquiry-summary      # the file's identity in your organization
version: "1.2"             # your own label; SmartStaff stores it and never reads it

process:
  title: Enquiry summary
  instructions: |-
    Every enquiry that arrives gets a one-page summary for the sales desk:
    who is asking, what they want, by when, and what the request leaves out.
  rules:                   # standing rules: every run follows them
    - Quote the sentence each fact came from.
    - If no deadline is given, write "no deadline given" instead of guessing one.

team:
  name: Enquiry desk

agents:
  - key: reader            # how the steps below refer to this agent
    name: Lena Park
    role: Enquiry reader
    instructions: |-
      You read enquiries and their attachments and list the facts in them,
      each with the sentence it came from.
  - key: writer
    name: Oskar Hale
    role: Summary writer
    instructions: |-
      You turn the reader's list into a one-page summary. You add nothing
      the reader did not find.

steps:                     # the procedure, in order
  - title: Read the enquiry
    agent: reader
    instruction: Read the message and every attachment. List the facts with their sources.
    tools: [list_files, read_file]
  - title: Write the summary
    agent: writer
    instruction: Write the one-page summary from the reader's list.
    expectedOutput: summary.md
    requiresReview: true   # every run stops for your approval first
    tools: [save_file]

triggers:
  - key: intake
    kind: webhook          # another system starts a run by calling a URL
    label: Enquiry intake

A few things worth knowing about the parts:

• slug is how SmartStaff recognises the process. Import a file with the same slug again and that process is updated. Change the slug and you get a different process.
• rules are standing rules, written by whoever defined the process. Every run follows them. When a rule learned from feedback on a run says otherwise, the learned rule wins: it is newer, and it comes from a person who saw the work.
• agents are described by name, role and instructions. To use an agent from the library as published, write marketplace: with its identifier instead of those three. Steps refer to agents by their key.
• steps are the procedure. A step without agent is assigned during each run. requiresReview: true makes every run whose plan includes the step wait for your approval, even when plans are otherwise approved automatically.
• tools lists tools from the catalogue by their identifier. The built-in ones need no listing and a step can name them directly: read_file, list_files, save_file, calculator, web_search, web_scrape and search_knowledge.
• triggers are webhooks or e-mail addresses that start a run. An e-mail trigger must say who may use it: list addresses or whole domains, or write [] for anyone who knows the address.

triggers:
  - key: inbox
    kind: email
    allowedSenders: ["@example.com", "anna@example.com"]

• An agent can also carry knowledge: documents it can search, given as text in the file or as a public web address SmartStaff downloads the document from. A file from your computer cannot be embedded. Knowledge needs a plan that includes agent knowledge.

A file can be up to 2 MB, with at most 12 agents, 12 steps, 12 standing rules and 10 triggers.

Importing a File

What the Warnings Mean

A warning does not stop the import. It tells you something you should know before you confirm:

• An agent, trigger or knowledge document is not in the file. It stays. Remove it in the app if you want it gone.
• The team also runs other processes, or an agent also works in other teams. The change reaches them too.
• A run is in progress. It finishes by the plan it has; later runs follow the new steps.
• Anyone who knows the address can start the process, or a sender is not a member of your organization. Check that this is what you mean: that person or address can start runs.
• A document replaces a file someone uploaded under the same name on the same agent.
• A document's web address contains a query (?…). It is written into every export of the process, so it must not be a private or signed link.

When the Import Will Not Run

Some problems stop the import until you fix them. For example: a tool the catalogue does not have, a library agent that does not exist, knowledge on a plan without it, two agents with the same name, a team that would grow past 12 agents, an agent that would switch between the library and your own description, or a trigger that would switch between webhook and e-mail. While a run whose plan includes a step is still open, that step cannot be removed and its requiresReview cannot be switched; finish or cancel the run first. The preview names each problem and where it is in the file.

What an Import Never Does

• It never deletes what the file leaves out. Agents, triggers and knowledge documents that are not in the file stay where they are. Three lists work differently: the steps, the standing rules and the set of tools become exactly what the file says, so a step you delete from the file is deleted from the process.
• It never starts a run. A new process is created as a draft.
• It never rewrites a library agent. Those are used as published.
• The same file twice changes nothing. The second preview shows no changes.

After the Import

• Knowledge is queued for processing. An agent can search a document only once processing has finished.
• Steps the process has no tool for are listed. A run will stop at such a step — for example one that asks to send an e-mail when the process has no mail tool — so add the tool or change the step.

Export and Update From File

Export any process as YAML or JSON. The file contains no internal identifiers, no trigger addresses or tokens, and no tool settings such as API keys. Files you uploaded to agents are not included, and SmartStaff tells you what was left out. If the process holds something a file cannot describe, such as more steps than a file allows, the export is refused with the reason.

You can also include the rules the process has learned from feedback, written into the file as standing rules. They come from reviewers' comments on real runs and may name your customers, so read them before you share the file.

Update from file is the round trip: export a process, edit the file, and import it back over the same process. The preview then shows exactly your edits and nothing else. The process takes the file's slug; if another process in your organization already uses it, the import stops until you change the slug.

Completion in Your Editor

SmartStaff publishes the format as a JSON Schema at:

https://smartstaff.io/api/schemas/process-definition/v1.json

With the first line of the example above in a YAML file, or with "$schema" set to that address in a JSON file, an editor with YAML or JSON Schema support (for example VS Code with its YAML extension) suggests field names and marks mistakes while you type. Some checks only happen on import, for example that every step names an agent the file defines.

An AI client connected to SmartStaff over MCP can preview and import files as well. There too the import previews first, and a file that creates a webhook has to be imported in the app, so the token never passes through the AI client.