cleveragents-core/docs/configuration

Configuration YAML Reference

CleverAgents uses YAML configuration files for defining actions, actors, skills, tools, and validation rules. This document covers the primary configuration schemas.

Action Configuration (action.yaml)

Actions define the behavior, actor, and invariants for plan execution.

# action.yaml example
name: my-action                    # Required: namespace/name or plain name
description: "Refactor the auth module"
actor: local/my-actor              # Required: actor name to use for execution
automation_profile: supervised     # Optional: manual|supervised|review|ci|trusted
arguments:
  - key: target_file
    value: src/auth.py
invariants:
  - name: tests-pass
    description: "All tests must pass after changes"
    required: true

Schema defined in docs/schema/action.schema.yaml.

Actor Configuration (actor.yaml)

Actors define the LLM/tool/graph behavior for plan execution. All actors use version: "3" and specify a type.

LLM Actor

# actor.yaml — LLM actor example
version: "3"
type: llm
name: local/my-llm-actor
model: gpt-4o                      # Provider/model identifier
system_prompt: |
  You are a helpful coding assistant. Analyze the codebase and make targeted changes.
tools: []                          # Optional: list of tool names to bind

Tool Actor

# actor.yaml — Tool actor example
version: "3"
type: tool
name: local/my-tool-actor
tool: my-namespace/my-tool         # Required: tool to execute

Graph Actor

# actor.yaml — Graph actor example
version: "3"
type: graph
name: local/my-graph-actor
entry: strategize                  # Required: entry node name
nodes:
  strategize:
    type: llm
    model: gpt-4o
    system_prompt: "Analyze the task and create a plan."
  execute:
    type: llm
    model: gpt-4o
    system_prompt: "Execute the plan step by step."
edges:
  - from: strategize
    to: execute
  - from: execute
    to: __end__

Schema defined in docs/reference/actors_schema.md and docs/reference/actor_config.md.

Skill Configuration (skill.yaml)

Skills define reusable tool bundles that can be loaded into actors.

# skill.yaml example
version: "1"
name: my-namespace/my-skill
description: "File editing and search tools"
tools:
  - name: read_file
    description: "Read a file from the filesystem"
  - name: write_file
    description: "Write content to a file"
  - name: search_files
    description: "Search for patterns in files"

Schema defined in docs/schema/skill.schema.yaml.

Tool Configuration (tool.yaml)

Tools define individual callable functions available to actors.

# tool.yaml example
tool:
  name: my-namespace/my-tool
  description: "Execute a shell command safely"
  parameters:
    - name: command
      type: string
      description: "The command to execute"
      required: true
  execution_env: sandbox            # Optional: sandbox|local|container

Schema defined in docs/schema/tool.schema.yaml.

Validation Configuration (validation.yaml)

Validations define checks that must pass before a plan can be applied.

# validation.yaml example
name: my-namespace/run-tests
description: "Run the test suite"
type: required                     # required|informational
command: "pytest tests/ -x"
timeout: 300

Schema defined in docs/schema/validation.schema.yaml.

Automation Profile Configuration

Automation profiles control how much human oversight is required during plan execution.

Profile	Description
manual	All steps require explicit human approval
supervised	Pauses at confidence thresholds for human review
review	Runs autonomously but requires review before apply
ci	Fully automated for CI/CD pipelines
trusted	Maximum autonomy, minimal interruptions

Profiles are configured via agents config set actor.default.automation_profile <profile> or per-action in action.yaml.

Global Settings

CleverAgents settings are stored in ~/.config/cleveragents/settings.yaml and can be managed via agents config:

agents config set actor.default.strategy local/my-strategy-actor
agents config set actor.default.estimation local/my-estimation-actor
agents config set server_url https://my-server.example.com
agents config set format rich

Key settings defined in cleveragents.config.Settings:

Key	Description
actor.default.strategy	Default strategy actor for plan execution
actor.default.estimation	Default estimation actor
actor.default.automation_profile	Default automation profile
server_url	Remote CleverAgents server URL
server_token	Authentication token for server mode
format	Default output format (plain, json, yaml, rich, color)

See Also

• Actor schema reference: docs/reference/actors_schema.md
• Actor configuration guide: docs/reference/actor_config.md
• Automation profiles: docs/reference/automation_profiles.md
• Config resolution: docs/reference/config_resolution.md