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

# Workflow Templates

> Create deterministic, zero-token workflows using Shannon's template system

## Overview

Shannon's template system enables **deterministic, zero-token workflows** for common patterns. Templates define structured workflows in YAML that execute without AI decomposition, providing significant cost savings for repeatable tasks.

<CardGroup cols={2}>
  <Card title="Zero Token Cost" icon="coins">
    Templates bypass LLM calls for workflow routing
  </Card>

  <Card title="Deterministic Execution" icon="route">
    Predictable, repeatable workflow behavior
  </Card>

  <Card title="Budget Control" icon="gauge">
    Per-node token limits with automatic degradation
  </Card>

  <Card title="DAG Support" icon="diagram-project">
    Parallel execution with dependency management
  </Card>
</CardGroup>

## When to Use Templates

**Use templates when:**

* Workflows are repeatable with known structure
* You want to eliminate decomposition token costs
* Predictable execution order is required
* Budget control per workflow stage is needed

**Use AI decomposition when:**

* Task structure is unknown or variable
* Complex reasoning about workflow design is needed
* One-off or highly dynamic tasks

## Template Structure

Templates are YAML files with this structure:

```yaml theme={null}
name: "workflow_name"
version: "1.0.0"
description: "What this workflow does"

defaults:
  model_tier: "medium"        # small | medium | large
  budget_agent_max: 6000      # Total token budget
  require_approval: false     # Human approval gate

nodes:
  - id: "step_1"
    type: "simple"            # Node type
    strategy: "react"         # Execution strategy
    tools_allowlist:          # Permitted tools
      - "web_search"
    budget_max: 1500          # Per-node token limit
    depends_on: []            # Dependencies

  - id: "step_2"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 2000
    depends_on: ["step_1"]

edges:
  - from: "step_1"
    to: "step_2"
```

### Core Fields

| Field         | Type   | Required | Description                      |
| ------------- | ------ | -------- | -------------------------------- |
| `name`        | string | Yes      | Unique workflow identifier       |
| `version`     | string | Yes      | Semantic version (e.g., "1.0.0") |
| `description` | string | No       | Human-readable description       |
| `defaults`    | object | No       | Global settings for all nodes    |
| `nodes`       | array  | Yes      | Workflow execution units         |
| `edges`       | array  | No       | Explicit dependency connections  |

### Default Settings

```yaml theme={null}
defaults:
  model_tier: "medium"        # Model size for all nodes
  budget_agent_max: 6000      # Total workflow token budget
  require_approval: false     # Require human approval before execution
```

## Node Types

Shannon supports four node types for different execution patterns:

### Simple Nodes

Single-task execution with direct tool invocation.

```yaml theme={null}
- id: "fetch_data"
  type: "simple"
  strategy: "react"
  tools_allowlist:
    - "web_search"
  budget_max: 1000
  depends_on: []
```

**Use for:** Data fetching, simple transformations, tool-based operations.

### Cognitive Nodes

Complex reasoning with multi-step analysis.

```yaml theme={null}
- id: "analyze"
  type: "cognitive"
  strategy: "chain_of_thought"
  budget_max: 2500
  depends_on: ["fetch_data"]
  degrade_to: "react"         # Fallback if budget exceeded
  retries: 1
```

**Use for:** Analysis, reasoning, synthesis tasks.

### DAG Nodes

Parallel execution with internal task dependencies.

```yaml theme={null}
- id: "parallel_analysis"
  type: "dag"
  budget_max: 5000
  depends_on: ["understand"]
  metadata:
    tasks:
      - id: "collect"
        tools_allowlist: ["web_search"]
        depends_on: []
      - id: "quantitative"
        tools_allowlist: ["calculator"]
        depends_on: ["collect"]
      - id: "qualitative"
        tools_allowlist: []
        depends_on: ["collect"]
      - id: "cross_validate"
        depends_on: ["quantitative", "qualitative"]
```

**Use for:** Parallel processing, fan-out/fan-in patterns.

### Supervisor Nodes

Hierarchical task decomposition and coordination.

```yaml theme={null}
- id: "orchestrate"
  type: "supervisor"
  strategy: "reflection"
  budget_max: 3000
  depends_on: ["parallel_analysis"]
```

**Use for:** Result aggregation, quality control, synthesis.

## Execution Strategies

Strategies define how nodes process tasks:

| Strategy           | Token Range | Description                             |
| ------------------ | ----------- | --------------------------------------- |
| `react`            | \~500-1500  | Tool-based reasoning with action cycles |
| `chain_of_thought` | \~1500-3000 | Sequential step-by-step reasoning       |
| `tree_of_thoughts` | \~3000-8000 | Explores multiple reasoning branches    |
| `reflection`       | \~1000-2000 | Self-evaluation and refinement          |
| `debate`           | \~2000-4000 | Multi-perspective analysis              |

### Automatic Degradation

When budget constraints are reached, strategies degrade automatically:

```
tree_of_thoughts → chain_of_thought → react
```

Configure explicit degradation:

```yaml theme={null}
- id: "explore"
  type: "cognitive"
  strategy: "tree_of_thoughts"
  budget_max: 2500
  degrade_to: "chain_of_thought"  # Fallback strategy
  retries: 1                       # Retry count on degradation
```

## Creating Templates

<Steps>
  <Step title="Create Template File">
    Create a YAML file in `config/workflows/examples/` or your custom directory:

    ```yaml theme={null}
    # config/workflows/examples/my_workflow.yaml
    name: "my_workflow"
    version: "1.0.0"
    description: "Custom analysis workflow"

    defaults:
      model_tier: "medium"
      budget_agent_max: 5000
      require_approval: false

    nodes:
      - id: "intake"
        type: "simple"
        strategy: "react"
        tools_allowlist:
          - "web_search"
        budget_max: 1500
        depends_on: []

      - id: "analyze"
        type: "cognitive"
        strategy: "chain_of_thought"
        budget_max: 2000
        depends_on: ["intake"]

      - id: "synthesize"
        type: "cognitive"
        strategy: "reflection"
        budget_max: 1500
        depends_on: ["analyze"]

    edges:
      - from: "intake"
        to: "analyze"
      - from: "analyze"
        to: "synthesize"
    ```
  </Step>

  <Step title="Register Template Directory">
    Templates are loaded at startup via `InitTemplateRegistry`:

    ```go theme={null}
    // In orchestrator initialization
    registry := templates.InitTemplateRegistry(
        "./config/workflows/builtin",
        "./config/workflows/examples",  // Your templates
    )

    // Validate all templates
    if err := registry.Finalize(); err != nil {
        log.Fatal(err)
    }
    ```
  </Step>

  <Step title="Restart Services">
    ```bash theme={null}
    docker compose -f deploy/compose/docker-compose.yml up -d --force-recreate orchestrator
    ```
  </Step>

  <Step title="List Available Templates">
    Via gRPC:

    ```bash theme={null}
    grpcurl -plaintext -d '{}' localhost:50052 \
      shannon.orchestrator.OrchestratorService/ListTemplates
    ```
  </Step>
</Steps>

## Using Templates

### Via HTTP Gateway

```bash theme={null}
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Analyze the current AI market trends",
    "context": {
      "template": "my_workflow",
      "template_version": "1.0.0"
    }
  }'
```

### Via gRPC

```bash theme={null}
grpcurl -plaintext -d '{
  "query": "Analyze the current AI market trends",
  "context": {
    "template": "my_workflow",
    "template_version": "1.0.0",
    "disable_ai": true
  }
}' localhost:50052 shannon.orchestrator.OrchestratorService/SubmitTask
```

<Note>
  Set `disable_ai: true` to enforce template-only execution without AI fallback.
</Note>

### Via Python SDK

```python theme={null}
from shannon import ShannonClient

client = ShannonClient(base_url="http://localhost:8080")
handle = client.submit_task(
    "Analyze the current AI market trends",
    context={
        "template": "my_workflow",
        "template_version": "1.0.0",
    },
)
result = client.wait(handle.task_id)
print(result.result)
```

## Template Examples

### Simple Analysis Workflow

Two-stage pipeline for quick summarization:

```yaml theme={null}
name: "simple_analysis"
version: "1.0.0"
description: "Quick summarization workflow for short briefs"

defaults:
  model_tier: "medium"
  budget_agent_max: 3000
  require_approval: false

nodes:
  - id: "intake"
    type: "simple"
    strategy: "react"
    budget_max: 1000
    depends_on: []

  - id: "summarize"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 1200
    depends_on: ["intake"]

edges:
  - from: "intake"
    to: "summarize"
```

### Research Summary Workflow

Four-stage research pipeline with progressive reasoning:

```yaml theme={null}
name: "research_summary"
version: "1.0.0"
description: "Multi-stage research workflow"

defaults:
  model_tier: "medium"
  budget_agent_max: 6000
  require_approval: false

nodes:
  - id: "discover"
    type: "simple"
    strategy: "react"
    tools_allowlist:
      - "web_search"
    budget_max: 1500
    depends_on: []

  - id: "reason"
    type: "cognitive"
    strategy: "chain_of_thought"
    budget_max: 1500
    depends_on: ["discover"]

  - id: "explore"
    type: "cognitive"
    strategy: "tree_of_thoughts"
    budget_max: 2500
    degrade_to: "chain_of_thought"
    retries: 1
    depends_on: ["reason"]

  - id: "finalize"
    type: "cognitive"
    strategy: "reflection"
    budget_max: 1000
    depends_on: ["explore"]

edges:
  - from: "discover"
    to: "reason"
  - from: "reason"
    to: "explore"
  - from: "explore"
    to: "finalize"
```

### Parallel DAG Workflow

Complex workflow with parallel execution branches:

```yaml theme={null}
name: "parallel_analysis"
version: "1.0.0"
description: "Parallel analysis with convergence"

defaults:
  model_tier: "medium"
  budget_agent_max: 8000
  require_approval: false

nodes:
  - id: "understand"
    type: "simple"
    strategy: "react"
    budget_max: 1000
    depends_on: []

  - id: "parallel_analysis"
    type: "dag"
    budget_max: 5000
    depends_on: ["understand"]
    metadata:
      tasks:
        - id: "collect"
          tools_allowlist: ["web_search"]
          depends_on: []
        - id: "quantitative"
          tools_allowlist: ["calculator"]
          depends_on: ["collect"]
        - id: "qualitative"
          tools_allowlist: []
          depends_on: ["collect"]
        - id: "cross_validate"
          depends_on: ["quantitative", "qualitative"]

  - id: "report"
    type: "cognitive"
    strategy: "reflection"
    budget_max: 2000
    degrade_to: "chain_of_thought"
    depends_on: ["parallel_analysis"]

edges:
  - from: "understand"
    to: "parallel_analysis"
  - from: "parallel_analysis"
    to: "report"
```

## Template Inheritance

Templates can inherit from parent templates using `extends`:

```yaml theme={null}
# base_research.yaml
name: "base_research"
version: "1.0.0"

defaults:
  model_tier: "medium"
  budget_agent_max: 5000
  require_approval: false
```

```yaml theme={null}
# advanced_research.yaml
name: "advanced_research"
version: "1.0.0"
extends: ["base_research"]    # Inherits all defaults

defaults:
  budget_agent_max: 10000     # Override specific values

nodes:
  # ... additional nodes
```

Multiple parents are applied in order, with the derived template's values taking precedence.

## Validation

Templates are validated at load time for:

* YAML syntax correctness
* Required field presence
* DAG acyclicity (no circular dependencies)
* Budget hierarchy (node budgets ≤ agent budget)
* Tool registry existence
* Variable reference resolution

```go theme={null}
registry := templates.InitTemplateRegistry("./templates")

// Validates all templates
if err := registry.Finalize(); err != nil {
    log.Fatalf("Template validation failed: %v", err)
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Keep Nodes Small and Focused">
    Each node should do one thing well:

    ```yaml theme={null}
    # Good: Focused nodes
    - id: "search"
      type: "simple"
      strategy: "react"
      tools_allowlist: ["web_search"]

    - id: "analyze"
      type: "cognitive"
      strategy: "chain_of_thought"
    ```
  </Accordion>

  <Accordion title="Explicitly Allowlist Tools">
    Restrict tools per node for security and predictability:

    ```yaml theme={null}
    # Good: Explicit allowlist
    tools_allowlist:
      - "web_search"
      - "calculator"

    # Bad: Allowing all tools
    # tools_allowlist: ["*"]
    ```
  </Accordion>

  <Accordion title="Use Budget Degradation">
    Configure fallback strategies for cost control:

    ```yaml theme={null}
    - id: "explore"
      strategy: "tree_of_thoughts"
      budget_max: 2500
      degrade_to: "chain_of_thought"
      retries: 1
    ```
  </Accordion>

  <Accordion title="Use Inheritance for Common Patterns">
    Extract shared defaults into base templates:

    ```yaml theme={null}
    extends: ["base_research"]
    defaults:
      budget_agent_max: 8000  # Only override what changes
    ```
  </Accordion>

  <Accordion title="Version Your Templates">
    Use semantic versioning and specify version in requests:

    ```yaml theme={null}
    name: "my_workflow"
    version: "1.0.0"  # Increment on breaking changes
    ```

    ```json theme={null}
    {
      "context": {
        "template": "my_workflow",
        "template_version": "1.0.0"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Template Not Found">
    **Symptom:** `template 'my_workflow' not found`

    **Solutions:**

    1. Check template file exists in registered directory
    2. Verify YAML syntax: `yamllint config/workflows/examples/my_workflow.yaml`
    3. Restart orchestrator to reload templates
    4. Check orchestrator logs for load errors
  </Accordion>

  <Accordion title="Validation Errors">
    **Symptom:** `Template validation failed: circular dependency`

    **Solutions:**

    1. Review `depends_on` fields for cycles
    2. Ensure DAG nodes have acyclic task dependencies
    3. Check `edges` don't create loops
  </Accordion>

  <Accordion title="Budget Exceeded">
    **Symptom:** Node execution stops early or degrades unexpectedly

    **Solutions:**

    1. Increase `budget_max` for affected nodes
    2. Configure `degrade_to` for graceful fallback
    3. Review total budget vs. sum of node budgets
  </Accordion>

  <Accordion title="Tools Not Available">
    **Symptom:** `tool 'my_tool' not registered`

    **Solutions:**

    1. Verify tool is registered in tool registry
    2. Check tool name spelling in `tools_allowlist`
    3. Ensure LLM service has tool loaded
  </Accordion>
</AccordionGroup>

## Synthesis Templates

Synthesis templates control how Shannon formats final output after all agents complete their work. These Go templates live in `config/templates/synthesis/` and are rendered by the Orchestrator before returning results.

### Available Templates

| Template                      | Purpose                            |
| ----------------------------- | ---------------------------------- |
| `normal_default.tmpl`         | Default for non-research tasks     |
| `research_comprehensive.tmpl` | Detailed research reports          |
| `research_concise.tmpl`       | Brief research summaries           |
| `research_with_facts.tmpl`    | Research with fact-based citations |
| `domain_analysis_digest.tmpl` | Domain analysis format             |
| `swarm_default.tmpl`          | Swarm multi-agent output           |
| `test_bullet_summary.tmpl`    | Bullet-point test format           |

### Base Contract

All synthesis templates inherit behavioral rules from `_base.tmpl`:

<AccordionGroup>
  <Accordion title="Citation Handling">
    * When **CitationAgent is enabled**: no inline `[n]` citations in synthesis — Citation Agent adds them separately
    * When **CitationAgent is disabled**: use inline `[n]` matching the `AvailableCitations` list
  </Accordion>

  <Accordion title="Temporal References">
    The `CurrentDate` field is injected into every template, enabling "as of" statements for time-sensitive content.
  </Accordion>

  <Accordion title="Structured Artifacts">
    Templates must preserve structured artifacts (tables, code blocks, JSON) — never flatten them to prose.
  </Accordion>

  <Accordion title="Source Sections">
    Templates should **not** include a "Sources" section. The system appends source citations automatically.
  </Accordion>
</AccordionGroup>

### Template Data

Every synthesis template receives a `SynthesisTemplateData` struct with the following fields:

```go theme={null}
type SynthesisTemplateData struct {
    Query                string   // Original user query
    QueryLanguage        string   // Detected language (e.g., "en", "ja")
    ResearchAreas        []string // Topics explored by agents
    AvailableCitations   string   // Formatted citation list
    CitationCount        int      // Total citations available
    MinCitations         int      // Minimum citations to include
    LanguageInstruction  string   // Output language directive
    AgentResults         string   // Combined agent output
    TargetWords          int      // Target word count
    IsResearch           bool     // Whether task is research-type
    SynthesisStyle       string   // Selected synthesis style
    CitationAgentEnabled bool     // Whether Citation Agent is active
    CurrentDate          string   // Current date for temporal context
    NewsCount            int      // Number of news items found
}
```

### Selecting a Synthesis Template

The Orchestrator selects synthesis templates based on the task type and configuration:

<Tabs>
  <Tab title="Via Task Context">
    ```bash theme={null}
    curl -X POST http://localhost:8080/api/v1/tasks \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Research quantum computing trends",
        "context": {
          "synthesis_style": "research_comprehensive"
        }
      }'
    ```
  </Tab>

  <Tab title="Via Workflow Template">
    ```yaml theme={null}
    name: "my_research"
    version: "1.0.0"
    defaults:
      model_tier: "medium"
      synthesis_style: "research_with_facts"
    ```
  </Tab>
</Tabs>

<Note>
  If no `synthesis_style` is specified, Shannon automatically selects `research_comprehensive` for research tasks and `normal_default` for all others.
</Note>

## Example Workflows

Shannon ships with 8 example workflow templates in `config/workflows/examples/`. These serve as ready-to-use starting points and reference implementations.

### Workflow Catalog

| Template                           | Description             | Nodes | Pattern                         |
| ---------------------------------- | ----------------------- | ----- | ------------------------------- |
| `simple_analysis.yaml`             | Quick summarization     | 2     | Sequential (intake + summarize) |
| `research_summary.yaml`            | Multi-stage research    | 4     | Sequential with degradation     |
| `research_summary_enterprise.yaml` | Enterprise research     | 4+    | Sequential with large models    |
| `market_analysis.yaml`             | Market research         | 3+    | Sequential with tools           |
| `market_analysis_playbook.yaml`    | Market playbook variant | 3+    | Playbook-driven                 |
| `complex_dag.yaml`                 | Multi-parallel DAG      | 5+    | DAG with fan-out/fan-in         |
| `parallel_dag_example.yaml`        | Parallel execution demo | 4+    | DAG with parallel branches      |
| `parallel_items_example.yaml`      | Batch item processing   | 3+    | Parallel items                  |

### YAML Structure Reference

All example workflows follow this structure:

```yaml theme={null}
name: workflow_id
description: "Description"

defaults:
  model_tier: small|medium|large    # Model size for all nodes
  budget_agent_max: 3000            # Total token budget
  require_approval: false           # Human-in-the-loop gate

nodes:
  - id: node_id
    type: simple|cognitive|dag      # Execution type
    strategy: react|chain_of_thought|tree_of_thoughts
    depends_on: [other_node_ids]    # DAG dependencies
    budget_max: 1000                # Per-node token limit

edges:
  - from: node1
    to: node2
```

### Pattern Degradation

Example workflows demonstrate Shannon's automatic degradation behavior when resources are constrained:

```
DAG        → sequential        (if insufficient agents available)
tree_of_thoughts → chain_of_thought  (if budget constrained)
multi-node → single-node       (fallback for minimal environments)
```

<Warning>
  Degradation is automatic and logged. Check Orchestrator logs for `strategy_degraded` events to monitor when fallbacks activate.
</Warning>

### Learning Router

When enabled, the **Learning Router** automatically selects workflow templates based on query similarity to past successful executions. This eliminates the need for callers to specify a template explicitly.

```bash theme={null}
# Enable learning router via environment
ORCHESTRATOR_LEARNING_ROUTER_ENABLED=true

# The router will match incoming queries to historical patterns
# and select the best-performing template automatically
```

<Tip>
  The Learning Router improves over time. For new deployments, explicitly specify templates until enough execution history accumulates (typically 50+ successful tasks).
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/en/tutorials/custom-tools">
    Add tools for your templates
  </Card>

  <Card title="Extending Shannon" icon="puzzle-piece" href="/en/tutorials/extending-shannon">
    Other extension methods
  </Card>

  <Card title="Configuration" icon="gear" href="/en/quickstart/configuration">
    Environment and YAML config
  </Card>

  <Card title="Architecture" icon="sitemap" href="/en/architecture/overview">
    Understanding Shannon's design
  </Card>
</CardGroup>