YAML
Everything you build in A3T is a YAML document you can read, diff and keep in Git: a flow, a template (a flow that agents run), a trigger and a canvas. Studio shows each as a graph and as this code; both edit the same document.
New to YAML? How to read and write YAML walks through maps, lists, strings and nesting, with the gotchas that break files. This page is the reference for A3T’s files.
The four kinds
Section titled “The four kinds”| Kind | Starts with | Where you edit it | Page |
|---|---|---|---|
| Flow | document: (dsl, namespace, name, version) then do: | Studio | CNCF Serverless Workflow |
| Template | A flow whose steps run an agent (call: a3t:agent, or run of the core agent) | Templates › Edit in Studio | Templates |
| Trigger | name:, project:, then on: and send: | Triggers › YAML | below |
| Canvas | flowRef:, placement:, lifecycle:, health: | Canvas › YAML | below |
A flow
Section titled “A flow”document: # who it is dsl: 1.0.3 # the CNCF Serverless Workflow version namespace: qa-operator-support # its project name: flow_qa_operator_support_refund_decide version: 1.0.0 # a released version never changes title: Decide what to do about a late refundinput: # optional: what it must be started with schema: format: json document: type: object required: [order_id, days_late] properties: order_id: { type: string } days_late: { type: integer }metadata: # optional: A3T's own settings a3t: extends: system/flow_system_base@1.0.0 # inherit the base's error handlingdo: # the steps, top to bottom - decide: switch: - late: { when: '${ .days_late >= 7 }', then: escalate } - default: { then: wait } - escalate: set: { action: escalate } then: end - wait: set: { action: wait } then: endA trigger
Section titled “A trigger”name: refund-requestsproject: qa-operator-supportdescription: Refund requests from the shop, sent to the help-desk agentenabled: trueon: # one source: webhook, schedule, topic or event webhook: path: /acme/refund method: POSTsend: # one or more targets - agent: agt-87c819a3 message: '${ "Refund request for order " + .body.order_id }' conversation: '${ "order-" + .body.order_id }' - flow: qa-operator-support/flow_qa_operator_support_refund_decide input: '${ {order_id: .body.order_id, days_late: .body.days_late} }'on takes exactly one source:
| Source | Its fields | What .body is |
|---|---|---|
webhook | path, method (default POST), message | The JSON body the caller posts |
cron | expression (e.g. "0 6 * * *"), timezone, message | { trigger: cron, trigger_id, fired_at, minute } |
adb_topic | resource (an ADB resource), topic, filter, message | The message’s fields, plus _topic and _offset |
event | source (e.g. flow.completed), filter, message | The platform event |
send takes one or more targets: flow: <project>/<flow> with input; agent: <agent id> with message and conversation; or url: with headers, which posts the event on. Each mapping is a jq expression in a string over { body, message, source, trigger, time }; left out, a flow gets the body as it came and an agent the trigger’s message, in conversation trigger-<name>. Mappings run only once they are approved; see Triggers.
A canvas
Section titled “A canvas”flowRef: qa-operator-support/flow_qa_operator_support_refund_decidedescription: The refund decision, on the shared CPU poolplacement: mode: shared # shared | isolated runtimeSelector: # labels a runtime must carry class: cpulifecycle: state: running # running | paused session: ephemeral # ephemeral | persistent scaling: { min: 1, max: 3, metric: queue_depth, target: 10 } restart: { policy: on-failure, backoff: exponential, maxRetries: 5 } # backoff: exponential | linear | fixedhealth: dependsOn: - resource: qa-operator-support/tickets onDependencyDown: queue # queue | cordon | circuit-break | failRules that keep YAML valid
Section titled “Rules that keep YAML valid”The short list; the writing rules in the YAML guide explain each.
| Rule | Example |
|---|---|
Quote a value that starts with ${, or holds : , # or { | when: '${ .days_late >= 7 }' |
| Inside a single-quoted value, write jq strings in double quotes | '${ "Order " + .order_id }' |
Long text: > folds lines into one, | keeps them | summary: > then the indented text |
| Indentation is spaces, never tabs, and it is the structure | Two spaces per level throughout A3T |
Lists start with - ; each step in do: is a one-key map | - decide: then its body indented below |
Names are <kind>_<project>_<what it does> | flow_acme_support_refund, tmpl_acme_support_helpdesk |