See your agents built, governed and running in a 30-minute walkthrough. Book a demo →
← All posts

CNCF Workflow DSL, Explained

The whole CNCF Serverless Workflow schema as one expanding tree. Open document, use, do, call, try and the rest, layer by layer, each with an explanation and an example.

Sriram 1 min read
The CNCF Serverless Workflow schema tree drawn as a floor plan, from workflow at the front to document, use, do and the task types behind it, under the title CNCF Workflow DSL, explained.

A3T describes agents and processes in the CNCF Serverless Workflow DSL: an open, vendor-neutral workflow language written in YAML. The project, still in the CNCF, now goes by the Open Workflow Specification.

Below is the whole 1.0 schema as one tree. Click + on any key to see what it is for and an example, and to open the layer inside it. New to YAML? Read How to Read and Write YAML first.

objectfixed keysmapkeys you namearraylist of - itemsstring …a single value
workflow.yaml
  • document object required

    workflow › document

    The identity card of the workflow: who owns it, what it is called and which version this is. namespace + name + version identify a workflow in a runtime.

    document:
      dsl: '1.0.0'
      namespace: shop
      name: process-order
      version: '1.0.0'
      title: Process an order
    • dsl string required

      workflow › document › dsl

      Version of the DSL the file is written in. Quote it: unquoted, 1.0 would be read as a number.

      dsl: '1.0.0'
    • namespace string required

      workflow › document › namespace

      The group the workflow belongs to, like a folder or a team.

      namespace: shop
    • name string required

      workflow › document › name

      Name of the workflow, unique within its namespace. Lowercase with hyphens by convention.

      name: process-order
    • version string required

      workflow › document › version

      Semantic version (major.minor.patch) of this definition. Bump it when the workflow changes.

      version: '1.2.0'
    • title string

      workflow › document › title

      A short, human-readable title for catalogs and dashboards.

      title: Process an order
    • summary string

      workflow › document › summary

      A longer description, in Markdown. A block scalar (|) keeps the line breaks.

      summary: |
        Validates an order, charges the card
        and waits for the shipment.
    • tags map · string: string

      workflow › document › tags

      Free key/value labels for search and grouping. You choose the keys; keys and values are strings.

      tags:
        team: payments
        tier: gold
    • metadata map

      workflow › document › metadata

      Anything else you want to attach. The runtime keeps it but does not act on it.

      metadata:
        owner: payments-team
        runbook: https://wiki.example.com/orders
  • input object

    workflow › input

    Checks and shapes the data the workflow is started with. Bad input fails the run before any task starts.

    input:
      schema:
        format: json
        document:
          type: object
          required: [order]
      from: ${ .order }
    • schema object

      workflow › input › schema

      A JSON Schema that the raw input must match. Give it inline (document) or load it from a URL (resource).

      schema:
        format: json
        resource:
          endpoint: https://schemas.example.com/order.json
      • format string required

        workflow › input › schema › format

        The schema language. The spec defines json, for JSON Schema.

        format: json
      • document object

        workflow › input › schema › document

        The schema itself, written inline. Use this or resource.

        document:
          type: object
          required: [order]
          properties:
            order:
              type: object
      • resource object

        workflow › input › schema › resource

        Where to fetch the schema from: an object with an endpoint (a URI, or { uri, authentication }).

        resource:
          endpoint: https://schemas.example.com/order.json
    • from expression

      workflow › input › from

      A jq expression that picks, or reshapes, what the first task sees as ".". Without it, tasks see the whole input.

      from: ${ .payload.order }
  • use object

    workflow › use

    Reusable building blocks. Declare a policy, function, error or secret here once, then refer to it by name from any task.

    use:
      secrets: [paymentKey]
      retries:
        threeTimes:
          delay: { seconds: 2 }
          limit:
            attempt: { count: 3 }
    • authentications map · name: auth

      workflow › use › authentications

      Named authentication policies. A call refers to one with authentication: { use: <name> }. Each policy uses exactly one scheme.

      authentications:
        shopApi:
          bearer:
            token: ${ $secrets.shopToken }
      • basic object

        workflow › use › authentications › basic

        HTTP basic auth: username and password.

        basic:
          username: admin
          password: ${ $secrets.adminPassword }
      • bearer object

        workflow › use › authentications › bearer

        A bearer token sent in the Authorization header.

        bearer:
          token: ${ $secrets.apiToken }
      • digest object

        workflow › use › authentications › digest

        HTTP digest auth: username and password, sent as a digest.

        digest:
          username: admin
          password: ${ $secrets.adminPassword }
      • oauth2 object

        workflow › use › authentications › oauth2

        OAuth 2.0: the authority to get a token from, the grant type, the client and the scopes.

        oauth2:
          authority: https://auth.example.com
          grant: client_credentials
          client:
            id: workflow-runtime
            secret: ${ $secrets.clientSecret }
          scopes: [orders.write]
      • oidc object

        workflow › use › authentications › oidc

        OpenID Connect: the same fields as oauth2, with endpoints discovered from the authority.

        oidc:
          authority: https://auth.example.com
          grant: client_credentials
          client:
            id: workflow-runtime
            secret: ${ $secrets.clientSecret }
    • catalogs map · name: catalog

      workflow › use › catalogs

      Named function catalogs: shared libraries of functions. A task calls one as call: <function>:<version>@<catalog>.

      catalogs:
        shared:
          endpoint: https://github.com/acme/functions
      # used as:  call: sendEmail:1.0.0@shared
      • endpoint string | object required

        workflow › use › catalogs › endpoint

        Where the catalog lives: a URI, or { uri, authentication }.

        endpoint: https://github.com/acme/functions
    • errors map · name: error

      workflow › use › errors

      Named error definitions. raise: { error: <name> } raises one without repeating its fields.

      errors:
        outOfStock:
          type: https://example.com/errors/out-of-stock
          status: 409
          title: Item is out of stock
    • extensions array · name: extension

      workflow › use › extensions

      Hooks that run tasks before or after every task of a given type: logging, policy checks, mocks. Order matters, so it is a list.

      extensions:
        - logCalls:
            extend: call
            before:
              - log:
                  call: http
                  with:
                    method: post
                    endpoint: https://log.example.com
                    body: ${ $task }
      • extend string required

        workflow › use › extensions › extend

        The task type to extend: call, composite, emit, for, listen, raise, run, set, switch, try, wait, or all.

        extend: call
      • when expression

        workflow › use › extensions › when

        Apply the extension only when this is true.

        when: '${ $task.reference | startswith("/do/0") }'
      • before array · name: task

        workflow › use › extensions › before

        Tasks to run before the extended task.

        before:
          - audit:
              set: { started: true }
      • after array · name: task

        workflow › use › extensions › after

        Tasks to run after the extended task.

        after:
          - audit:
              set: { finished: true }
    • functions map · name: task

      workflow › use › functions

      Named reusable tasks, usually calls. Any task runs one with call: <name> and passes arguments in with.

      functions:
        getWeather:
          call: http
          with:
            method: get
            endpoint: https://api.example.com/weather
      # used as:  call: getWeather
    • retries map · name: retryPolicy

      workflow › use › retries

      Named retry policies. A try refers to one with retry: <name>.

      retries:
        threeTimes:
          delay: { seconds: 2 }
          backoff:
            exponential: {}
          limit:
            attempt: { count: 3 }
      • delay duration

        workflow › use › retries › delay

        How long to wait between attempts. A duration: an object such as { minutes: 5, seconds: 30 } (days, hours, minutes, seconds, milliseconds), or an ISO 8601 string such as PT5M30S.

        delay: { seconds: 2 }
      • backoff object

        workflow › use › retries › backoff

        How the delay grows: constant, exponential or linear. Set exactly one; the value is an object, often empty.

        backoff:
          exponential: {}
      • limit object

        workflow › use › retries › limit

        When to give up: attempt.count (maximum attempts), attempt.duration (per attempt) or duration (in total).

        limit:
          attempt:
            count: 5
          duration: { minutes: 2 }
      • jitter object

        workflow › use › retries › jitter

        A random extra delay between from and to, so many retries do not all hit a service at once.

        jitter:
          from: { milliseconds: 100 }
          to: { seconds: 1 }
      • when expression

        workflow › use › retries › when

        Retry only when this is true.

        when: ${ $error.status >= 500 }
      • exceptWhen expression

        workflow › use › retries › exceptWhen

        Do not retry when this is true.

        exceptWhen: ${ $error.status == 400 }
    • secrets array · string

      workflow › use › secrets

      The names of secrets the workflow may read. Values come from the runtime, never from the file; read them as $secrets.<name>.

      secrets:
        - paymentKey
        - shopToken
    • timeouts map · name: timeout

      workflow › use › timeouts

      Named timeouts. A workflow or task refers to one with timeout: <name>.

      timeouts:
        short:
          after: { seconds: 30 }
  • do array · name: task required

    workflow › do

    The tasks, run top to bottom. Each list item is a map with one key: the key is the task name, the value is the task. The task type is the key inside it (call, set, switch and so on), next to the fields every task can have.

    do:
      - greet:
          set:
            message: Hello
      - send:
          call: http
          with:
            method: post
            endpoint: https://hooks.example.com/hello
            body: ${ . }
    • (any task) object

      workflow › do › (any task)

      Fields every task can have, whatever its type. They sit next to the type key, at the same indentation.

      - charge:
          if: ${ .total > 0 }
          call: http
          with:
            method: post
            endpoint: https://pay.example.com/charges
          timeout:
            after: { seconds: 30 }
          then: ship
      • if expression

        workflow › do › (any task) › if

        Run the task only when this is true. Otherwise it is skipped and its input passes through unchanged.

        if: ${ .amount > 1000 }
      • input object

        workflow › do › (any task) › input

        Same as the workflow input, for one task: schema to check, and from to choose what the task sees as ".".

        input:
          from: ${ .order }
      • output object

        workflow › do › (any task) › output

        Reshapes what the task passes to the next task. as is a jq expression; schema checks the result.

        output:
          as: ${ .body.id }
      • export object

        workflow › do › (any task) › export

        Saves data in $context, which later tasks can read wherever they are. as builds the new context.

        export:
          as: '${ $context + { orderId: .id } }'
      • timeout string | object

        workflow › do › (any task) › timeout

        Fail the task if it runs longer than after. A string names a timeout from use.timeouts.

        timeout:
          after: { seconds: 30 }
      • then flow directive

        workflow › do › (any task) › then

        Where to go next: continue (the next task, the default), exit (leave the current task list), end (finish the workflow), or the name of a task.

        then: notifyCustomer
      • metadata map

        workflow › do › (any task) › metadata

        Free information about the task. The runtime keeps it but does not act on it.

        metadata:
          owner: payments-team
    • call string

      workflow › do › call

      Calls something outside the workflow and returns its result. call says what to call; with holds the arguments, and their shape depends on the kind of call.

      - getUser:
          call: http
          with:
            method: get
            endpoint: https://api.example.com/users/42
      • call string required

        workflow › do › call › call

        What to call: http, grpc, openapi, asyncapi, a2a, mcp, or the name of a function from use.functions or a catalog. A3T adds adb (agent memory) and a3t:agent.

        call: openapi
      • with map

        workflow › do › call › with

        The arguments. The children below show what each built-in call expects.

        with:
          method: get
          endpoint: https://api.example.com/users/42
      • call: http object

        workflow › do › call › call: http

        An HTTP request. Returns the response body by default.

        call: http
        with:
          method: post
          endpoint: https://api.example.com/orders
          headers:
            content-type: application/json
          body:
            id: ${ .id }
        • method string required

          workflow › do › call › call: http › method

          The HTTP method: get, post, put, patch, delete…

          method: post
        • endpoint string | object required

          workflow › do › call › call: http › endpoint

          The URL, or { uri, authentication } when the call needs credentials.

          endpoint:
            uri: https://api.example.com/orders
            authentication:
              use: shopApi
        • headers map

          workflow › do › call › call: http › headers

          Request headers, name: value.

          headers:
            accept: application/json
        • body any

          workflow › do › call › call: http › body

          The request body: an object, a string or an expression.

          body: ${ .order }
        • query map

          workflow › do › call › call: http › query

          Query parameters added to the URL.

          query:
            page: 2
            size: 50
        • output string

          workflow › do › call › call: http › output

          What the task returns: content (the body, the default), response (status, headers and body) or raw (base64).

          output: response
        • redirect boolean

          workflow › do › call › call: http › redirect

          Accept 3xx redirects instead of treating them as errors. Defaults to false.

          redirect: true
      • call: grpc object

        workflow › do › call › call: grpc

        Calls a gRPC method, described by a .proto file.

        call: grpc
        with:
          proto:
            endpoint: https://example.com/greeter.proto
          service:
            name: GreeterApi.Greeter
            host: localhost
            port: 5011
          method: SayHello
          arguments:
            name: ${ .user.name }
        • proto object required

          workflow › do › call › call: grpc › proto

          Where to fetch the .proto file: an object with an endpoint.

          proto:
            endpoint: https://example.com/greeter.proto
        • service object required

          workflow › do › call › call: grpc › service

          The service to call: name and host are required; port and authentication are optional.

          service:
            name: GreeterApi.Greeter
            host: localhost
            port: 5011
        • method string required

          workflow › do › call › call: grpc › method

          The gRPC method name.

          method: SayHello
        • arguments map

          workflow › do › call › call: grpc › arguments

          The method arguments, name: value.

          arguments:
            name: Ada
      • call: openapi object

        workflow › do › call › call: openapi

        Calls an operation from an OpenAPI document, by its operationId. The runtime builds the HTTP request.

        call: openapi
        with:
          document:
            endpoint: https://petstore.swagger.io/v2/swagger.json
          operationId: findPetsByStatus
          parameters:
            status: available
        • document object required

          workflow › do › call › call: openapi › document

          Where to fetch the OpenAPI document: an object with an endpoint.

          document:
            endpoint: https://api.example.com/openapi.json
        • operationId string required

          workflow › do › call › call: openapi › operationId

          The operationId in that document.

          operationId: findPetsByStatus
        • parameters map

          workflow › do › call › call: openapi › parameters

          Parameters of the operation, path, query or body, by name.

          parameters:
            status: available
        • authentication object

          workflow › do › call › call: openapi › authentication

          Credentials for the call, inline or by name.

          authentication:
            use: shopApi
        • output string

          workflow › do › call › call: openapi › output

          content (default), response or raw, as with http.

          output: content
      • call: asyncapi object

        workflow › do › call › call: asyncapi

        Publishes or subscribes to messages through an AsyncAPI operation: Kafka, MQTT, AMQP, NATS and others.

        call: asyncapi
        with:
          document:
            endpoint: https://example.com/orders.asyncapi.yaml
          operation: publishOrder
          protocol: kafka
          message:
            payload: ${ .order }
        • document object required

          workflow › do › call › call: asyncapi › document

          Where to fetch the AsyncAPI document.

          document:
            endpoint: https://example.com/orders.asyncapi.yaml
        • operation string

          workflow › do › call › call: asyncapi › operation

          The operation to run (AsyncAPI 3). For AsyncAPI 2.6, use channel.

          operation: publishOrder
        • protocol string

          workflow › do › call › call: asyncapi › protocol

          Picks the server by protocol: kafka, mqtt, amqp, nats, ws…

          protocol: kafka
        • message object

          workflow › do › call › call: asyncapi › message

          The message to publish: payload, headers. Use this or subscription.

          message:
            payload: ${ .order }
        • subscription object

          workflow › do › call › call: asyncapi › subscription

          Consume messages instead: a filter, how many to consume, and what to do with each.

          subscription:
            consume:
              amount: 5
      • call: a2a object

        workflow › do › call › call: a2a

        Talks to another agent over the A2A (agent-to-agent) protocol: send a message, check or cancel a task.

        call: a2a
        with:
          method: message/send
          agentCard:
            endpoint: https://agents.example.com/.well-known/agent.json
          parameters:
            message:
              parts:
                - kind: text
                  text: Summarise order 42
        • method string required

          workflow › do › call › call: a2a › method

          The A2A JSON-RPC method: message/send, message/stream, tasks/get, tasks/cancel…

          method: message/send
        • agentCard object

          workflow › do › call › call: a2a › agentCard

          Where to fetch the agent card that describes the agent. Use this or server.

          agentCard:
            endpoint: https://agents.example.com/.well-known/agent.json
        • server string | object

          workflow › do › call › call: a2a › server

          The A2A server URL, when there is no agent card.

          server: https://agents.example.com/a2a
        • parameters map

          workflow › do › call › call: a2a › parameters

          Parameters of the method. For message/send, the runtime fills in messageId and role.

          parameters:
            message:
              parts:
                - kind: text
                  text: Hello
      • call: mcp object

        workflow › do › call › call: mcp

        Calls a Model Context Protocol server: list or call tools, read resources, get prompts.

        call: mcp
        with:
          protocolVersion: '2025-06-18'
          method: tools/call
          parameters:
            name: search
            arguments:
              query: ${ .question }
          transport:
            http:
              endpoint: https://mcp.example.com
        • method string required

          workflow › do › call › call: mcp › method

          The MCP method: tools/list, tools/call, resources/read, prompts/get…

          method: tools/call
        • transport object required

          workflow › do › call › call: mcp › transport

          How to reach the server: http (an endpoint) or stdio (a command to start).

          transport:
            stdio:
              command: npx
              arguments: [my-mcp-server]
        • parameters map

          workflow › do › call › call: mcp › parameters

          Method parameters, such as the tool name and its arguments.

          parameters:
            name: search
            arguments:
              query: workflows
        • protocolVersion string required

          workflow › do › call › call: mcp › protocolVersion

          The MCP protocol version. Defaults to 2025-06-18.

          protocolVersion: '2025-06-18'
    • set map | expression

      workflow › do › set

      Builds data. The task output is exactly what you write, with ${ } expressions evaluated against the task input.

      - price:
          set:
            orderId: ${ .order.id }
            total: ${ [.order.items[] | .price * .qty] | add }
    • switch array · name: case

      workflow › do › switch

      Branches. Cases are checked in list order; the first whose when is true decides where to go. A case without when is the default.

      - route:
          switch:
            - urgent:
                when: ${ .priority == "P1" }
                then: pageOnCall
            - default:
                then: fileTicket
      • when expression

        workflow › do › switch › when

        The condition for this case. Leave it out on one case, the default.

        when: ${ .total > 100 }
      • then flow directive required

        workflow › do › switch › then

        Where to go when the case matches: a task name, continue, exit or end.

        then: applyDiscount
    • for object

      workflow › do › for

      Loops over a list and runs its do once per item. The item and its index are variables.

      - notifyAll:
          for:
            each: user
            in: ${ .users }
          do:
            - send:
                call: http
                with:
                  method: post
                  endpoint: https://hooks.example.com/notify
                  body: ${ $user }
      • for.in expression | array required

        workflow › do › for › for.in

        The list to loop over.

        for:
          in: ${ .order.items }
      • for.each string

        workflow › do › for › for.each

        Variable name for the current item. Defaults to item, read as $item.

        for:
          each: line
          in: ${ .lines }
      • for.at string

        workflow › do › for › for.at

        Variable name for the index. Defaults to index.

        for:
          in: ${ .lines }
          at: i
      • while expression

        workflow › do › for › while

        Keep looping only while this is true.

        while: ${ $index < 10 }
      • do array · name: task required

        workflow › do › for › do

        The tasks to run for each item.

        do:
          - reserve:
              set:
                sku: ${ $item.sku }
    • fork object

      workflow › do › fork

      Runs branches in parallel. It waits for all of them and returns a list of their outputs, unless compete makes it a race.

      - lookup:
          fork:
            compete: true
            branches:
              - fromCache:
                  call: http
                  with:
                    method: get
                    endpoint: https://cache.example.com/item/1
              - fromDb:
                  call: http
                  with:
                    method: get
                    endpoint: https://db.example.com/item/1
      • branches array · name: task

        workflow › do › fork › branches

        The tasks to run at the same time, one per list item.

        branches:
          - reserveStock:
              set: { reserved: true }
          - sendEmail:
              set: { sent: true }
      • compete boolean

        workflow › do › fork › compete

        true: the first branch to finish wins and its output is the result. Defaults to false.

        compete: true
    • try array · name: task

      workflow › do › try

      Runs tasks and handles their errors. try holds the tasks; catch says which errors to handle and how: retry, run recovery tasks, or both.

      - charge:
          try:
            - pay:
                call: http
                with:
                  method: post
                  endpoint: https://pay.example.com/charges
          catch:
            errors:
              with:
                status: 503
            retry: threeTimes
      • catch object required

        workflow › do › try › catch

        Which errors to handle, and how.

        catch:
          errors:
            with:
              type: https://serverlessworkflow.io/spec/1.0.0/errors/communication
          as: failure
          do:
            - logIt:
                set:
                  failed: ${ $failure.title }
        • errors.with object

          workflow › do › try › catch › errors.with

          Catch only errors with these properties: type, status, instance, title, detail.

          errors:
            with:
              status: 503
        • as string

          workflow › do › try › catch › as

          Variable name for the caught error. Defaults to error, read as $error.

          as: failure
        • when expression

          workflow › do › try › catch › when

          Catch only when this is true.

          when: ${ $error.status >= 500 }
        • exceptWhen expression

          workflow › do › try › catch › exceptWhen

          Do not catch when this is true.

          exceptWhen: ${ $error.status == 404 }
        • retry string | object

          workflow › do › try › catch › retry

          Retry the try tasks: a policy inline, or the name of one in use.retries.

          retry: threeTimes
        • do array · name: task

          workflow › do › try › catch › do

          Recovery tasks to run once the error is caught (and retries, if any, are used up).

          do:
            - refund:
                call: http
                with:
                  method: post
                  endpoint: https://pay.example.com/refunds
        • then flow directive

          workflow › do › try › catch › then

          Where to go after handling the error.

          then: end
    • emit object

      workflow › do › emit

      Publishes an event in CloudEvents format, so other systems and workflows can react.

      - announce:
          emit:
            event:
              with:
                source: https://shop.example.com
                type: com.example.order.paid.v1
                data:
                  orderId: ${ .id }
      • event.with object required

        workflow › do › emit › event.with

        The CloudEvent attributes. source and type are required when emitting; the runtime fills id and time.

        event:
          with:
            source: https://shop.example.com
            type: com.example.order.paid.v1
            data: ${ . }
        • source string required

          workflow › do › emit › event.with › source

          A URI for where the event happened.

          source: https://shop.example.com
        • type string required

          workflow › do › emit › event.with › type

          What happened, usually reverse-DNS with a version.

          type: com.example.order.paid.v1
        • data any

          workflow › do › emit › event.with › data

          The event payload.

          data:
            orderId: ${ .id }
        • subject string

          workflow › do › emit › event.with › subject

          What the event is about, within the source.

          subject: order-42
    • listen object

      workflow › do › listen

      Pauses until matching events arrive, then continues with them as output. Use it for approvals, callbacks and anything that happens later.

      - awaitApproval:
          listen:
            to:
              one:
                with:
                  type: com.example.approval.v1
      • to object required

        workflow › do › listen › to

        Which events to wait for. Set one of one, all or any.

        to:
          all:
            - with:
                type: com.example.payment.done.v1
            - with:
                type: com.example.stock.reserved.v1
        • one object

          workflow › do › listen › to › one

          Wait for one event that matches the filter. with lists the attributes to match.

          one:
            with:
              type: com.example.approval.v1
        • all array · filter

          workflow › do › listen › to › all

          Wait until every filter in the list has matched an event.

          all:
            - with: { type: com.example.a.v1 }
            - with: { type: com.example.b.v1 }
        • any array · filter

          workflow › do › listen › to › any

          Continue as soon as any filter matches. An empty list accepts any event.

          any:
            - with: { type: com.example.a.v1 }
            - with: { type: com.example.b.v1 }
        • until expression | object

          workflow › do › listen › to › until

          With any only: keep listening until this condition holds, or until these events arrive.

          until: ${ length >= 3 }
      • read string

        workflow › do › listen › read

        What each event contributes: data (the payload, default), envelope (with its attributes) or raw.

        read: envelope
    • wait duration

      workflow › do › wait

      Pauses for a fixed time, for back-off, rate limits or giving another system time. A duration: an object such as { minutes: 5, seconds: 30 } (days, hours, minutes, seconds, milliseconds), or an ISO 8601 string such as PT5M30S.

      - coolDown:
          wait:
            seconds: 30
    • raise object

      workflow › do › raise

      Fails on purpose with a structured error. A surrounding try can catch it; otherwise the workflow ends with that error.

      - reject:
          raise:
            error:
              type: https://serverlessworkflow.io/spec/1.0.0/errors/validation
              status: 400
              title: Order has no items
      • error string | object required

        workflow › do › raise › error

        The error to raise, inline or by the name of one in use.errors.

        error: outOfStock
        • type string required

          workflow › do › raise › error › type

          A URI naming the kind of error. The spec defines standard ones: validation, communication, timeout, authentication, authorization, configuration, expression, runtime.

          type: https://serverlessworkflow.io/spec/1.0.0/errors/timeout
        • status integer required

          workflow › do › raise › error › status

          A status code, HTTP style.

          status: 409
        • title string

          workflow › do › raise › error › title

          A short summary for people.

          title: Item is out of stock
        • detail string

          workflow › do › raise › error › detail

          An explanation of this occurrence. Can be an expression.

          detail: ${ "SKU " + .sku + " is sold out" }
    • run object

      workflow › do › run

      Runs a process: a container, a script, a shell command or another workflow. Set exactly one of the four.

      - resize:
          run:
            container:
              image: ghcr.io/example/resizer:1.0
              command: resize --width 800
      • container object

        workflow › do › run › container

        Runs a container image. image is required; command, arguments, environment, ports, volumes and pullPolicy are optional.

        container:
          image: ghcr.io/example/label-printer:1.2
          environment:
            PRINTER: dock-3
      • script object

        workflow › do › run › script

        Runs code in js or python, inline (code) or from a URL (source).

        script:
          language: python
          code: |
            import sys
            print(sys.argv[1].upper())
          arguments: [hello]
      • shell object

        workflow › do › run › shell

        Runs a shell command with optional arguments, environment and working directory.

        shell:
          command: ls
          arguments: [-la, /data]
      • workflow object

        workflow › do › run › workflow

        Runs another workflow as a sub-workflow, by namespace, name and version, with an input.

        workflow:
          namespace: shop
          name: send-invoice
          version: '1.0.0'
          input: ${ . }
      • await boolean

        workflow › do › run › await

        Wait for the process to finish. false starts it and moves on. Defaults to true.

        await: false
      • return string

        workflow › do › run › return

        What the task outputs: stdout (default), stderr, code, all or none.

        return: all
    • do array · name: task

      workflow › do › do

      do is also a task: a group of tasks run in order, inside another list. Useful for structure and for then: exit.

      - prepare:
          do:
            - load:
                set: { loaded: true }
            - check:
                set: { checked: true }
  • timeout string | object

    workflow › timeout

    A limit on the whole run. If it takes longer than after, the workflow fails with a timeout error. A string names a timeout from use.timeouts.

    timeout:
      after: { minutes: 30 }
    • after duration required

      workflow › timeout › after

      How long the run may take. A duration: an object such as { minutes: 5, seconds: 30 } (days, hours, minutes, seconds, milliseconds), or an ISO 8601 string such as PT5M30S.

      after: { hours: 1, minutes: 30 }
  • output object

    workflow › output

    Shapes what the workflow returns. Without it, the workflow returns the output of its last task.

    output:
      as: '${ { orderId: $context.orderId, total: $context.total } }'
    • as expression

      workflow › output › as

      A jq expression that builds the result. Quote it when it contains ": ", or YAML reads it as a map.

      as: '${ { id: .orderId } }'
    • schema object

      workflow › output › schema

      A JSON Schema the result must match, the same shape as input.schema.

      schema:
        format: json
        document:
          type: object
          required: [orderId]
  • schedule object

    workflow › schedule

    Starts the workflow on its own instead of on request. Set one of every, cron, after or on.

    schedule:
      cron: '0 6 * * *'
    • every duration

      workflow › schedule › every

      Start a run at this interval, even if the last one is still running.

      every: { minutes: 15 }
    • cron string

      workflow › schedule › cron

      A cron expression. Quote it: * has a meaning in YAML.

      cron: '0 * * * *'
    • after duration

      workflow › schedule › after

      Start again this long after the previous run completes.

      after: { hours: 1 }
    • on object

      workflow › schedule › on

      Start when events arrive, with the same one, all or any as listen.to.

      on:
        one:
          with:
            type: com.example.order.created.v1
  • evaluate object

    workflow › evaluate

    How runtime expressions are evaluated. Rarely needed: the defaults are jq, strict.

    evaluate:
      language: jq
      mode: strict
    • language string

      workflow › evaluate › language

      The expression language. Defaults to jq.

      language: jq
    • mode string

      workflow › evaluate › mode

      strict (default): only values inside ${ } are expressions. loose: every string is tried as an expression.

      mode: strict

Three rules that hold everywhere

  1. Data flows down the list. Each task’s output is the next task’s input. Inside a task, . is that input.
  2. ${ } is jq. Anything inside it is a jq expression evaluated at run time. Quote it when it contains : .
  3. A task is a one-key map. In do, try, fork.branches and switch, each list item is - name: and the task sits under it.

How A3T runs it

A3T runs these workflows on a runtime written in Rust, and adds two kinds of call: call: adb runs AQL queries against agent memory, and call: a3t:agent runs an LLM agent, with tools and memory, as a single task. Everything in the tree above works as written.

Try it in the docsFrom a plain workflow to an agent with memory, in four examples

Sources