Skip to main content
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

FieldRequiredNotes
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:
  1. CreateMessageHistoryStep
  2. AgenticResearchStep
  3. 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

ErrorFix
Missing node inputWire it
No __outputs__Add output node
Multiple outputsSet ui_output
Non-serializable outputConvert to basic types