> ## Documentation Index
> Fetch the complete documentation index at: https://docs.contextual.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# YAML Format

> Root-level fields and node structure for Agent Composer YAML

## Description

Agent Composer uses a YAML-based configuration format to define workflow graphs. This page describes the root-level fields and basic node structure.

## Root-Level Fields

At the root level, the Agent Composer YAML format accepts four main fields:

### `inputs`

Lists the inputs of the graph mapped to their accepted types. Type annotations should conform to Python typing syntax.

```yaml theme={null}
inputs:
  query: str
```

<Note>
  The main graph currently only accepts a single `str` input named `query`, unless used as a subgraph.
</Note>

### `outputs`

Lists the outputs of the graph mapped to their types. A graph can have arbitrarily many outputs, as long as their types are JSON-serializable.

```yaml theme={null}
outputs:
  response: str
  groundedness_scores: List[Dict[str, float]]
```

### `nodes`

Lists the nodes in the graph and specifies how they are connected.

```yaml theme={null}
nodes:
  preprocess:
    type: PreprocessNode
    input_mapping:
      input: __inputs__#query

  finalize:
    type: FinalizationNode
    input_mapping:
      query: __inputs__#query
      processed_query: preprocess#output
```

### `ui_output`

Specifies exactly one of the fields listed under `outputs` as the UI output. Required when there are multiple outputs; optional for single-output graphs.

```yaml theme={null}
ui_output: response
```

## Node Format

Nodes represent basic operations in the graph. A typical node definition:

```yaml theme={null}
example_node:
  type: PreprocessNode
  config:
    threshold: 0.2
    process_type: standard
  input_mapping:
    preprocessing_input: earlier_node#output_key
```

### Core Node Arguments

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `type`             | The step type (must be registered in the component registry) |
| `config`           | Configuration arguments passed to the step constructor       |
| `input_mapping`    | Describes how nodes connect to each other                    |
| `config_overrides` | Dynamic configuration determined at runtime                  |
| `ui_stream_types`  | Controls what data streams to the UI                         |

### Config Parameters

Config parameters are passed as keyword arguments to the step constructor. Nested configurations are supported:

```yaml theme={null}
my_node:
  type: CustomProcessorStep
  config:
    threshold: 0.85
    mode: "strict"
    options:
      enable_caching: true
      timeout_seconds: 30
  input_mapping:
    data: previous_node#output
```

<Note>
  If a config field is not specified, the platform agent configuration setting is used as the default.
</Note>

## Input and Output Nodes

Every graph has an implicit input node named `__inputs__`. Access inputs via:

```yaml theme={null}
input_mapping:
  current_node_input: __inputs__#query
```

The output node must be explicitly added:

```yaml theme={null}
__outputs__:
  type: output
  input_mapping:
    graph_output: final_node#node_output
```

## Related

* [Input Mapping](/reference/ac-input-mapping)
* [Config Overrides](/reference/ac-config-overrides)
* [UI Stream Types](/reference/ac-ui-stream-types)