Quickstart

This guide writes an expense approval: an agent checks a claim against its receipt, the employee's manager approves, and a claim that does not match goes back to the employee. It is one file of about 45 lines.

#Write the file

A process lives in a folder with the same name as the process. Create expense-approval/PROCESS.md:

---
name: expense-approval
description: Check an expense claim against its receipt and the travel policy, then get the manager's approval.
inputs:
  employee: person
  amount: { type: number, description: Claimed amount in USD }
  receiptUrl: string
requires:
  systems: [expense-tool]
steps:
  - id: check_claim
    agent: |
      Open the receipt at inputs.receiptUrl. Check that its amount, date and
      merchant match the claim, and that the expense is allowed by the travel
      policy. Say in your summary what you checked and what you found.
    output:
      matches: boolean
      category: { type: string, one_of: [travel, meals, equipment, other] }
    evidence: [link]
    next:
      - { to: approve, when: The receipt matches the claim and the policy allows it }
      - { to: return_to_employee, when: Anything does not match }

  - id: approve
    person: manager
    approve: Approve when the receipt matches and the expense is within policy.
    due: 2d
    on_reject: check_claim
    next: approved

  - id: return_to_employee
    task: Tell the employee what does not match and ask for a corrected claim.
    person: inputs.employee
    next: returned

  - id: approved
    finish: approved

  - id: returned
    finish: returned
---

# Expense approval

Start this when an employee submits an expense claim with a receipt. The agent
checks the claim and the employee's manager approves it. Payment is a separate
process in finance. A claim that does not match goes back to the employee to
correct.

#What each part does

The body is plain language for agents and people. A server shows it with every claim.

#Check it

A server refuses a file that breaks the rules in §2 of the specification, and reports every issue at once. The ones that catch most first drafts:

• Every step has an id and exactly one kind key.
• Every next, on_reject and on_timeout names a step that exists.
• Every step is reachable from the first one, and a non-finish step that is last in the list names its next.
• Following next never visits a step twice. Only on_reject goes back.
• A person path names an input or output field declared as person.
• Unknown keys are refused anywhere in the frontmatter.

#Publish and run it

On a conforming server:

1. Import the folder. The server creates a draft and asks you to map each role name, here manager, to a group of people in your organization.
2. Publish. The server checks the file and creates version 1 with a content hash. That version never changes.
3. Start a test run with mode: test and inputs such as { "employee": "sam@example.com", "amount": 84.5, "receiptUrl": "https://…" }. In a test run, agents must cause no real external effects and the server sends no real notifications.

Then watch it move:

• The agent calls get_work, sees check_claim, and claims it. The claim carries the instructions, this body, the run's inputs and the output it must return.
• The agent opens the receipt, then calls submit with output: { "matches": true, "category": "travel" }, a link as evidence, a summary, next: "approve" and a reason.
• The server checks the output against the declared fields. If anything is missing or mistyped, it refuses with every issue and nothing changes. Otherwise the run moves to approve, and a work item appears for the manager group.
• A manager calls decide with approved, and the run ends with outcome approved. Had they rejected it with a note, the run would have returned to check_claim, and the next agent would read that note first.

#Next steps

• Best practices: write steps that agents and people can act on without asking.
• Specification: every key, type and rule.