AutoLoad

Overview

Automatic Discovery

Scan project directories and automatically load agents, tools, workflows, and memory configurations

Hot-Reloading

Monitor file changes and reload resources instantly without restarting the server

Instead of manually registering every resource:

Manual Configuration (Without AutoLoad)

# workflow.yaml
agents:
  - $ref: ./agents/researcher.yaml
  - $ref: ./agents/writer.yaml
  - $ref: ./agents/reviewer.yaml
  - $ref: ./agents/translator.yaml
  - $ref: ./agents/analyzer.yaml
  # ... dozens more manual entries

tools:
  - $ref: ./tools/web-search.yaml
  - $ref: ./tools/document-parser.yaml
  - $ref: ./tools/email-sender.yaml
  # ... dozens more manual entries

AutoLoad automatically discovers and loads them:

AutoLoad Configuration

# compozy.yaml
autoload:
  enabled: true
  watch_enabled: true  # Enable hot-reloading
  include:
    - "agents/**/*.yaml"
    - "tools/**/*.yaml"
    - "memory/**/*.yaml"
  exclude:
    - "**/*-test.yaml"
    - "**/*-draft.yaml"

Configuration Reference

Basic Configuration

compozy.yaml

autoload:
  enabled: true
  include:
    - "agents/*.yaml"
    - "tools/*.yaml"

For the complete AutoLoad configuration schema and all available options, see the AutoLoad Configuration Schema.

Include/Exclude Patterns

AutoLoad uses doublestar glob patterns for powerful file matching:

include:
  # Resource-specific patterns
  - "agents/*.yaml"           # Agent configurations
  - "tools/*.yaml"            # Tool definitions
  - "memory/**/*.yaml"        # Memory configurations
  - "workflows/**/*.yaml"     # Workflow definitions
  - "mcps/*.yaml"            # MCP server configurations

Development Workflow

Hot-Reloading Setup

Enable watch_enabled for automatic reloading during development:

compozy.yaml

autoload:
  enabled: true
  watch_enabled: true
  strict: false          # Allow partial loading during development
  include:
    - "agents/**/*.yaml"
    - "tools/**/*.yaml"
    - "memory/**/*.yaml"

Directory Structure Recommendations

AutoLoad Configuration:

autoload:
  enabled: true
  include:
    - "agents/*.yaml"
    - "tools/*.yaml"
    - "memory/*.yaml"

Supported Resource Types

AutoLoad automatically discovers and registers these resource types:

Agents
AI-powered components that understand natural language
Tools
TypeScript functions for specific operations
Memory
Persistent context and conversation history
Workflows
Task orchestration and execution flows
MCP Servers
Model Context Protocol server configurations
Projects
Project-level configurations and settings

Resource Format Requirements

All auto-discovered resources must include resource and id fields:

agents/researcher.yaml

resource: agent
id: researcher
description: Research specialist agent
version: 1.0.0

config:
  provider: openai
  model: gpt-4.1-2025-04-14
  api_key: "{{ .env.OPENAI_API_KEY }}"

instructions: |
  You are a research specialist that finds and analyzes information.
  Use available tools to gather comprehensive data on any topic.

tools:
  - $ref: resource::tool::#(id=='web-search')
  - $ref: resource::tool::#(id=='document-parser')

actions:
  - id: research_topic
    prompt: |
      Research the following topic: {{ .input.topic }}
      Provide comprehensive findings with sources.

Resource References

Using AutoLoaded Resources

AutoLoad integrates with Compozy's reference system, enabling resource:: scope references:

workflow.yaml

# Reference auto-loaded agents
agents:
  - $ref: resource::agent::#(id=='researcher')
  - $ref: resource::agent::#(id=='writer')
  - $ref: resource::agent::#(id=='reviewer')

# Reference auto-loaded tools
tools:
  - $ref: resource::tool::#(id=='web-search')
  - $ref: resource::tool::#(id=='document-parser')

# Reference auto-loaded memory
memory:
  - $ref: resource::memory::#(id=='conversation')

tasks:
  - id: research
    type: basic
    $use: agent(resource::agent::#(id=='researcher'))
    action: research_topic

  - id: write
    type: basic
    $use: agent(resource::agent::#(id=='writer'))
    action: create_content
    with:
      research_data: "{{ .tasks.research.output }}"

  - id: review
    type: basic
    $use: agent(resource::agent::#(id=='reviewer'))
    action: review_content
    with:
      content: "{{ .tasks.write.output }}"
    final: true

Strict vs Non-Strict Mode

Strict Mode (Production)

When strict: true (default), AutoLoad fails immediately on any loading error:

compozy.yaml

autoload:
  enabled: true
  strict: true  # Fail fast on errors

Strict Mode Behavior

Any invalid resource file will cause the entire application to fail startup. Use this in production to ensure all resources are valid.

Security Features

Path Validation

AutoLoad includes comprehensive security measures:

Path Traversal Prevention
Blocks ../ and absolute paths to prevent directory traversal attacks
Symlink Resolution
Validates symbolic links stay within project root directory
Pattern Validation
Rejects malicious glob patterns that could access sensitive files
Default Exclusions
Automatically excludes system and temporary files for security

Security Best Practices

Use only relative paths in include patterns
Avoid absolute paths that could access system files
Exclude sensitive directories (.env, .ssh, secrets)
Prevent accidental exposure of sensitive configuration files
Validate all auto-loaded resources in CI/CD
Ensure resource validation in your deployment pipeline
Use strict mode in production environments
Fail fast on any resource loading errors in production
Regularly audit include/exclude patterns
Review patterns to ensure they still meet security requirements

# ✅ Safe AutoLoad patterns
autoload:
  enabled: true
  include:
    - "agents/*.yaml"           # Relative paths only
    - "tools/safe/*.yaml"       # Specific subdirectories
    - "config/production/*.yaml" # Controlled locations
  exclude:
    - "**/.env*"                # Exclude environment files
    - "**/*.secret"             # Exclude secret files
    - "**/private/**"           # Exclude private directories