Skip to content
SWEny Workflow Specification

SWEny Workflow Specification v1.0

Abstract

Section titled “Abstract”

The SWEny Workflow Specification defines a YAML-based format for describing AI agent orchestration as a directed graph. Each node in the graph contains a natural language instruction executed by an AI model, with access to a declared set of skills (tool bundles). Edges define execution flow, with optional natural language conditions evaluated at runtime by the AI model.

This specification defines the format and its execution semantics. It is independent of any particular AI model, runtime, or hosting environment.

Status

Section titled “Status”

Version: 1.0
Status: Draft
License: Apache 2.0

Conformance Language

Section titled “Conformance Language”

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this specification are to be interpreted as described in RFC 2119.

  • MUST / REQUIRED / SHALL — absolute requirement.
  • MUST NOT / SHALL NOT — absolute prohibition.
  • SHOULD / RECOMMENDED — valid reasons may exist to deviate, but implications must be understood.
  • MAY / OPTIONAL — truly optional; implementations may or may not include the feature.

Specification

Section titled “Specification”
Section Description
Workflow Top-level document structure: id, name, nodes, edges, entry.
Nodes The Node object: instruction, skills, output schema.
Edges & Routing The Edge object: when conditions, max_iterations, routing algorithm.
Skills & Tools Skill and Tool interfaces: config resolution, tool invocation contract.
Execution Model Context accumulation, node execution, events, trace, dry-run semantics.

Machine-Readable Schemas

Section titled “Machine-Readable Schemas”

Canonical JSON Schemas for use with IDE autocomplete, CI validation, and alternative implementations:

Reference a schema from a YAML workflow file:

# $schema: https://spec.sweny.ai/schemas/workflow.json
id: my-workflow
name: My Workflow
entry: start
nodes:
  start:
    name: Start
    instruction: Do the thing.
edges: []

Reference Implementation

Section titled “Reference Implementation”

The reference implementation is @sweny-ai/core, published on npm. Source code, built-in workflows, and tests are available in the SWEny monorepo.

Versioning

Section titled “Versioning”

Every workflow file declares the spec version it was written against with a top-level spec_version field, a positive integer string such as "1". A file without the field is version 1. This document describes version 1.

  • Non-breaking additions (new optional fields, new event types) are additive to the current version and do not change spec_version.
  • Breaking changes (field removals, semantic changes) bump spec_version and ship with a migration from the previous version.

A conforming implementation migrates older versions in memory when it loads a file, and MUST refuse a file whose spec_version is newer than it supports. In the reference implementation, sweny workflow upgrade <file> rewrites a file at the current version.

This site always documents the current version.