Workflows (Arazzo)

[!NOTE] ChooChoo can validate Arazzo workflow files. Workflow execution and governance gates are planned.

Workflows define multi-step sequences of API operations. ChooChoo adopts the Arazzo Specification 1.0 (from the OpenAPI Initiative) to describe how agents and API calls should be orchestrated. For all supported standards, see the Standards Reference.

Why Arazzo?

OpenAPI describes endpoints, but Arazzo describes how to use them together to achieve a goal. For AI agents, this is critical context — it provides the deterministic sequence of steps an agent must follow, rather than relying on the agent to figure out the correct order on its own.

ChooChoo Extensions

ChooChoo extends Arazzo with Governance Gates. You can specify steps that require human approval or specific quality checks before proceeding. These gates integrate with ChooChoo's risk scoring system.

Key Fields

• stepId: Unique identifier for the step.
• operationId: Reference to an OpenAPI operation.
• requiresApproval: (ChooChoo Extension) Boolean flag to pause for human intervention. Triggers the approval workflow.
• approvalPolicy: (ChooChoo Extension) Name of the policy to apply. Defined in .choochoo/approval-policies.yaml — see Configuration.
• successCriteria: Logic to validate the step's output. See Validation Rules for the quality rule grammar.

Example

arazzo: "1.0.0"
info:
  title: Customer Onboarding
  version: "1.0.0"

workflows:
  - workflowId: onboard-customer
    steps:
      - stepId: create-record
        operationId: createCustomer
        description: Create initial customer record in CRM.

      - stepId: verify-identity
        operationId: verifyIdentity
        outputs:
          contractRef: contracts/identity-verification.contract.yaml

      - stepId: approve-high-risk
        operationId: approveAccount
        requiresApproval: true
        approvalPolicy: "high-risk-accounts"
        successCriteria:
          - type: custom
            expression: "riskScore < 0.5"

Notice how contractRef links a workflow step to a Contract. This relationship is tracked in the Lineage Graph, allowing ChooChoo to calculate the impact of contract changes on downstream workflows.

Agent Execution

When an AI agent executes a workflow:

1. It reads the Arazzo definition to understand the sequence.
2. It pauses at requiresApproval steps, triggering the configured approval policy.
3. It generates a Decision Trace for each step taken, which is recorded in the Audit Trail.

The agent's System Card is referenced during execution to verify that the agent has the necessary capabilities for each step. Boundary violations will produce error E007 (Agent boundary violation).

Validation

When you run choochoo validate, workflows are checked for:

• Schema validity against the Arazzo spec
• Cross-reference resolution — do referenced contracts and operations exist?
• Approval policy references — does the named policy exist in your configuration?

Workflow files must follow the naming convention <name>.workflow.yaml and be placed in the workflows/ directory of your project structure.

Related