> ## 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.

# Agent Composer YAML Cheat Sheet

> A single-page reference for Agent Composer YAML

<Note>
  Custom Agent Composer YAML workflows are available in public preview for enterprise users. Template agents (Basic Search and Agentic Search) are available for self-serve users, but creating custom workflows with YAML requires enterprise access. For more information or to request access, please contact your Contextual AI representative.
</Note>

Agent Composer YAML defines **executable agent workflows** as graphs.\
Each graph specifies **inputs → nodes → outputs** and runs via `/query/acl`.

***

## Minimal Graph

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

outputs:
  response: str

nodes:
  generate:
    type: ResponseGenerationStep
    input_mapping:
      query: __inputs__#query

  __outputs__:
    type: output
    input_mapping:
      response: generate#response
```

***

## Root-level Fields

| Field       | Required | Notes                                    |
| ----------- | -------- | ---------------------------------------- |
| `inputs`    | ✅        | Root graph accepts **only** `query: str` |
| `outputs`   | ✅        | Must be JSON-serializable                |
| `nodes`     | ✅        | Execution steps                          |
| `ui_output` | ⚠️       | Required if multiple outputs             |

***

## Core Rules (Remember These)

* Root graph: one input only (query)
* All node inputs must be wired
* Outputs must be JSON-serializable
* Multiple outputs → set exactly one ui\_output
* `__outputs__` node is mandatory

***

## Wiring Syntax

```yaml theme={null}
node_name#output_key
```

Special nodes:

* `__inputs__` → graph/subgraph inputs
* `__outputs__` → graph outputs

***

## Node Template

```yaml theme={null}
node_name:
  type: StepType
  config: {}
  config_overrides: {}
  input_mapping:
    input: upstream#output
```

Common fields:

* `type` (required)
* `input_mapping`
* `config` (static)
* `config_overrides` (runtime)
* `ui_stream_types`

***

## Output Node

```yaml theme={null}
__outputs__:
  type: output
  input_mapping:
    result: node#output
```

* No config
* No outputs
* Maps internal values → API outputs

***

## UI Streaming

```yaml theme={null}
ui_stream_types:
  retrievals: true
  generation: true
```

* Declared per node
* Multiple nodes may stream
* Independent of `ui_output`

***

## Subgraphs (Reusable Workflows)

Define:

```yaml theme={null}
my_subgraph:
  inputs:
    query: str
  outputs:
    docs: List[str]
  nodes: ...
```

Use:

```yaml theme={null}
retriever:
  type: subgraph:my_subgraph
  input_mapping:
    query: __inputs__#query
```

* Nestable
* Reusable
* Isolated I/O scope

***

## Conditional Execution

```yaml theme={null}
conditional:
  type: ConditionalStep
  config:
    variable: score
    branches:
      - condition: ">= 0.8"
        executable: HighQuality
      - condition: "< 0.8"
        executable: LowQuality
  input_mapping:
    score: eval#score
```

* Top-down evaluation
* First match executes
* Branch `__inputs__` != graph inputs

***

## Agentic Research Pattern

Standard flow:

1. `CreateMessageHistoryStep`
2. `AgenticResearchStep`
3. `GenerateFromResearchStep`

### Message History

```yaml theme={null}
create_message_history:
  type: CreateMessageHistoryStep
  input_mapping:
    query: __inputs__#query
```

### Agentic Research

```yaml theme={null}
research:
  type: AgenticResearchStep
  ui_stream_types:
    retrievals: true
```

* Multi-turn agent loop
* Plans and invokes tools
* Produces structured research

### Tools

```yaml theme={null}
tools_config:
  - name: search_docs
    step_config:
      type: SearchUnstructuredDataStep
```

Rules:

* Use either step\_config or graph\_config
* Inputs = basic Python types

### Final Generation

```yaml theme={null}
generate:
  type: GenerateFromResearchStep
  ui_stream_types:
    generation: true
```

Consumes `message_history` and `research` as inputs

***

## Run a Graph (Python)

```python theme={null}
graph = ExecutableGraph.from_yaml(yaml_string)
graph.execute_graph({"query": "Hello"})
```

## API Response

* `outputs`
* `workflow_trace`
* `dynamic_agent_trace` (if agentic steps used)

***

## Common Errors

| Error                   | Fix                    |
| ----------------------- | ---------------------- |
| Missing node input      | Wire it                |
| No `__outputs__`        | Add output node        |
| Multiple outputs        | Set `ui_output`        |
| Non-serializable output | Convert to basic types |