Skip to main content

YAML basics

Several editors in the portal expect YAML — a text format for structured configuration. You edit YAML when you build a workflow or a conversation result schema in Advanced mode, write a tool definition, or configure a deep analysis. This page covers the syntax you need to read and change those configurations. It does not describe the fields of any one schema — for that, follow the links at the end.

The examples reuse small pieces of real Flametree configuration so you can recognize the patterns in the editors.

Indentation sets the structure​

YAML uses indentation, not brackets, to show which lines belong together. Indent each level with exactly two spaces, and use spaces only.

- process_name: SupportProcess
  name: Greeting
  kind: StateConfig
  init_state: true

The four lines above belong to one workflow state because they share the same indentation under the -. The single rule behind every example on this page: lines at the same depth are siblings, and a line indented further belongs to the line above it.

warning

Never use the Tab key to indent. YAML rejects tabs, and a single tab among spaces breaks the file even though the editor may show the same width. If a configuration fails to parse, check for tabs first.

Keys and values​

Most lines are a key, a colon, a space, and a value:

field_name: HumanFullName
field_title: Name
field_type: str

The space after the colon is required. field_name:HumanFullName is not valid. Values can be text, numbers (30), or true / false.

Lists​

A list is a set of lines that each start with a dash and a space. A workflow is a list of states, and a conversation result schema is a list of fields:

available_tools:
  SingleStatefulOutboundAgent:
    - SendChatMessage
    - FinishSession

Here available_tools holds a group whose value is a list of two tool names. Keep every dash in one list at the same indentation.

Nesting​

To put structure inside a value, indent the inner lines one level further. A list item can itself contain keys and its own lists:

- field_name: HumanFullName
  field_description: The name of the human
  field_title: Name
  field_type: str
  kind: FormInfoField
- field_name: HumanPhoneNumber
  field_description: Human's contact phone number
  kind: FormInfoField

This is a list of two fields. The dash marks the start of each item, and the keys that follow are indented to line up under it. Read the workflow and conversation result examples in Advanced mode as lists of these nested items.

Strings and quoting​

Most text needs no quotes. Quote a value when it contains a colon-and-space, starts with a special character, or could be read as something else — for example a number you want kept as text:

description: "human asks a question"

For a fixed set of allowed values, the value is a Literal with the options in square brackets. Quote each option:

field_type: Literal["PROMISED", "NOT_INTERESTED", "DECLINED"]

For text that runs over several lines, write a pipe (|) and put the text on indented lines below. The line breaks are kept:

description: |
  - Greet the human
  - Ask how you can help
  - Determine human intent

This is how a workflow state's description holds multi-line instructions.

Comments​

A # starts a comment. Everything after it on that line is ignored, so you can leave notes for yourself or temporarily disable a line:

field_type: str
# field_type: int   # not used yet

Common mistakes​

These are the errors that most often make an editor report invalid YAML:

  • Tabs instead of spaces. The most frequent cause. Re-indent the affected lines with two spaces each. See the warning above.
  • Inconsistent indentation. Sibling lines must share the exact same indentation. Two spaces on one line and three on the next breaks the structure.
  • Missing space after a colon. Write key: value, not key:value.
  • Misaligned list items. Every dash in the same list must start at the same column.
  • An unquoted value with a colon. A value such as Ask: how can I help is read as a key. Wrap it in quotes: "Ask: how can I help".
tip

The ? icon in the Workflow and Conversation result section headers opens the formatting reference for that schema. Use the Playground to test changes after you save and restart the agent.

Where YAML appears in the portal​

LocationWhat you edit
Advanced modeThe agent Workflow (states and transitions) and the Conversation result schema.
ToolsA tool group definition file that lists its tools and their parameters.
Deep AnalysisThe analysis configuration that defines metrics and the dashboards built from them.

Was this article helpful?