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

# Subgraphs

> Reusable workflow components in Agent Composer

## Description

Subgraphs are reusable components that can be referenced in larger workflows. They allow you to define common patterns once and use them multiple times, improving maintainability and reducing duplication.

## Creating Subgraphs

Define subgraphs at the same level as the main graph with their own `inputs`, `outputs`, and `nodes`:

```yaml theme={null}
# Define a reusable retrieval subgraph
document_retrieval:
  inputs:
    query: str
    threshold: float
  outputs:
    documents: List[str]
    quality_score: float
  nodes:
    search:
      type: SearchUnstructuredDataStep
      input_mapping:
        query: __inputs__#query
    
    quality_check:
      type: QualityCheckStep
      config:
        threshold: 0.7
      input_mapping:
        results: search#retrievals
    
    __outputs__:
      type: output
      input_mapping:
        documents: search#retrievals
        quality_score: quality_check#score
```

## Using Subgraphs

Reference subgraphs using the `subgraph:` prefix in the type field:

```yaml theme={null}
# Main workflow using the subgraph
inputs:
  user_query: str

outputs:
  final_result: str

nodes:
  constant_threshold:
    type: ConstantStep
    config:
      value: 0.8

  retriever:
    type: subgraph:document_retrieval
    input_mapping:
      query: __inputs__#user_query
      threshold: constant_threshold#output

  __outputs__:
    type: output
    input_mapping:
      final_result: retriever#documents
```

## Subgraph Reference Syntax

```yaml theme={null}
node_name:
  type: subgraph:subgraph_name
  input_mapping:
    subgraph_input: source_node#output
```

## Features

| Feature           | Description                                                    |
| ----------------- | -------------------------------------------------------------- |
| **Nesting**       | Subgraphs can contain other subgraphs                          |
| **Reusability**   | One subgraph can be called multiple times in the same workflow |
| **Encapsulation** | Internal node names don't conflict with parent graph           |
| **Typed I/O**     | Subgraphs define their own typed inputs and outputs            |

## Example: Multiple Subgraph Calls

```yaml theme={null}
# Subgraph definition
search_and_rerank:
  inputs:
    query: str
  outputs:
    retrievals: Retrievals
  nodes:
    search:
      type: SearchUnstructuredDataStep
      input_mapping:
        query: __inputs__#query
    rerank:
      type: RerankRetrievalsStep
      input_mapping:
        query: __inputs__#query
        retrievals: search#retrievals
    __outputs__:
      type: output
      input_mapping:
        retrievals: rerank#retrievals

# Main workflow calling the subgraph twice
inputs:
  query: str

outputs:
  response: str

nodes:
  # First call with original query
  primary_search:
    type: subgraph:search_and_rerank
    input_mapping:
      query: __inputs__#query

  # Second call with expanded query
  expanded_search:
    type: subgraph:search_and_rerank
    input_mapping:
      query: query_expansion#expanded_query

  # Merge results
  merge:
    type: MergeRetrievalsStep
    input_mapping:
      retrievals1: primary_search#retrievals
      retrievals2: expanded_search#retrievals
```

## Related

* [YAML Format](/reference/ac-yaml-format)
* [Conditional Nodes](/reference/ac-conditional-nodes)