Agent Composer YAML Cheat Sheet - Contextual AI Documentation

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.

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

Minimal Graph

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

node_name#output_key

Special nodes:

__inputs__ → graph/subgraph inputs
__outputs__ → graph outputs

Node Template

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

__outputs__:
  type: output
  input_mapping:
    result: node#output

No config
No outputs
Maps internal values → API outputs

UI Streaming

ui_stream_types:
  retrievals: true
  generation: true

Declared per node
Multiple nodes may stream
Independent of ui_output

Subgraphs (Reusable Workflows)

Define:

my_subgraph:
  inputs:
    query: str
  outputs:
    docs: List[str]
  nodes: ...

Use:

retriever:
  type: subgraph:my_subgraph
  input_mapping:
    query: __inputs__#query

Nestable
Reusable
Isolated I/O scope

Conditional Execution

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:

CreateMessageHistoryStep
AgenticResearchStep
GenerateFromResearchStep

Message History

create_message_history:
  type: CreateMessageHistoryStep
  input_mapping:
    query: __inputs__#query

Agentic Research

research:
  type: AgenticResearchStep
  ui_stream_types:
    retrievals: true

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

Tools

tools_config:
  - name: search_docs
    step_config:
      type: SearchUnstructuredDataStep

Rules:

Use either step_config or graph_config
Inputs = basic Python types

Final Generation

generate:
  type: GenerateFromResearchStep
  ui_stream_types:
    generation: true

Consumes message_history and research as inputs

Run a Graph (Python)

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

​Minimal Graph

​Root-level Fields

​Core Rules (Remember These)

​Wiring Syntax

​Node Template

​Output Node

​UI Streaming

​Subgraphs (Reusable Workflows)

​Conditional Execution

​Agentic Research Pattern

​Message History

​Agentic Research

​Tools

​Final Generation

​Run a Graph (Python)

​API Response

​Common Errors

Minimal Graph

Root-level Fields

Core Rules (Remember These)

Wiring Syntax

Node Template

Output Node

UI Streaming

Subgraphs (Reusable Workflows)

Conditional Execution

Agentic Research Pattern

Message History

Agentic Research

Tools

Final Generation

Run a Graph (Python)

API Response

Common Errors