Skip to content

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.

KindStarts withWhere you edit itPage
Flowdocument: (dsl, namespace, name, version) then do:StudioCNCF Serverless Workflow
TemplateA flow whose steps run an agent (call: a3t:agent, or run of the core agent)Templates › Edit in StudioTemplates
Triggername:, project:, then on: and send:Triggers › YAMLbelow
CanvasflowRef:, placement:, lifecycle:, health:Canvas › YAMLbelow
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 refund
input: # 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 handling
do: # 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: end
name: refund-requests
project: qa-operator-support
description: Refund requests from the shop, sent to the help-desk agent
enabled: true
on: # one source: webhook, schedule, topic or event
webhook:
path: /acme/refund
method: POST
send: # 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:

SourceIts fieldsWhat .body is
webhookpath, method (default POST), messageThe JSON body the caller posts
cronexpression (e.g. "0 6 * * *"), timezone, message{ trigger: cron, trigger_id, fired_at, minute }
adb_topicresource (an ADB resource), topic, filter, messageThe message’s fields, plus _topic and _offset
eventsource (e.g. flow.completed), filter, messageThe 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.

flowRef: qa-operator-support/flow_qa_operator_support_refund_decide
description: The refund decision, on the shared CPU pool
placement:
mode: shared # shared | isolated
runtimeSelector: # labels a runtime must carry
class: cpu
lifecycle:
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 | fixed
health:
dependsOn:
- resource: qa-operator-support/tickets
onDependencyDown: queue # queue | cordon | circuit-break | fail

The short list; the writing rules in the YAML guide explain each.

RuleExample
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 themsummary: > then the indented text
Indentation is spaces, never tabs, and it is the structureTwo 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