cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

[AUTO-DOCS-1] Fix documentation nav, broken anchors, and missing showcase page #10340

Closed
HAL9000 wants to merge 1 commits from auto-docs-1/fix-mkdocs-nav-and-links into main
pull from: auto-docs-1/fix-mkdocs-nav-and-links
merge into: cleveragents:main
Conversation 2 Commits 1 Files Changed 3
+293 -6
3 changed files with 293 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/showcase/cli-tools/config-and-automation-profiles.md
+265
Protected
View File
@@ -0,0 +1,265 @@
# Config and Automation Profiles
This showcase demonstrates how to use CleverAgents' configuration system and automation profiles to control agent behavior, set execution policies, and manage automation levels across different workflows.
## Overview
CleverAgents provides a layered configuration system with automation profiles that let you control:
- **Automation level** — how much the agent does autonomously vs. asking for confirmation
- **Safety constraints** — sandbox requirements, checkpoint policies, tool access controls
- **Cost controls** — budget caps, rate limits, and token usage policies
- **Execution guards** — denylist rules, tool call limits, and escalation thresholds
## Prerequisites
- CleverAgents installed and initialized (`agents init`)
- A project created and linked to resources
- Basic familiarity with the CLI
## Part 1: Global Configuration
### Viewing Current Configuration
```bash
# List all configuration keys and their current values
agents config list
# Get a specific configuration value
agents config get core.log_level
agents config get plan.max_cost_per_plan
agents config get sandbox.strategy
```
### Setting Configuration Values
```bash
# Set the default log level
agents config set core.log_level INFO
# Set a cost cap for all plans
agents config set plan.max_cost_per_plan 5.00
# Configure the default sandbox strategy
agents config set sandbox.strategy git-worktree
# Enable automatic checkpointing
agents config set sandbox.auto_checkpoint true
agents config set sandbox.checkpoint_interval_steps 10
```
### Configuration Scoping
Configuration values can be set at different scopes:
```bash
# Global scope (applies to all projects)
agents config set --scope global plan.max_cost_per_plan 10.00
# Project scope (applies to a specific project)
agents config set --scope project --project local/my-project plan.max_cost_per_plan 2.00
```
The resolution order is: **plan > action > project > global**. More specific scopes override broader ones.
## Part 2: Automation Profiles
Automation profiles define how autonomously the agent operates. CleverAgents ships with eight built-in profiles ranging from fully manual to fully automatic.
### Built-in Profiles
| Profile | Autonomy Level | Description |
|---------|---------------|-------------|
| `manual` | 1.0 | Always asks for confirmation |
| `cautious` | 0.8 | Asks for most decisions |
| `supervised` | 0.6 | Asks for significant decisions |
| `default` | 0.5 | Balanced — asks for risky operations |
| `assisted` | 0.4 | Mostly automatic, asks for destructive ops |
| `semi-auto` | 0.3 | Automatic except for irreversible changes |
| `auto` | 0.1 | Almost fully automatic |
| `full-auto` | 0.0 | Never asks for confirmation |
### Listing and Viewing Profiles
```bash
# List all available automation profiles
agents automation-profile list
# Show details of a specific profile
agents automation-profile show default
agents automation-profile show cautious
```
### Creating a Custom Automation Profile
```bash
# Create a custom profile configuration file
cat > /tmp/my-profile.yaml << 'EOF'
name: local/code-review-profile
description: "Profile for automated code review — reads only, never writes"
autonomy_threshold: 0.2
safety_profile:
require_sandbox: false
require_checkpoints: false
allow_unsafe_tools: false
read_only: true
guards:
max_cost_per_plan: 1.00
max_tool_calls_per_plan: 50
denylist:
- "file_write"
- "file_delete"
- "shell_exec"
EOF
# Register the custom profile
agents automation-profile add --config /tmp/my-profile.yaml
# Verify it was created
agents automation-profile show local/code-review-profile
```
### Using Profiles in Plans
```bash
# Use a profile when executing a plan
agents plan use local/my-action --automation-profile cautious
# Use a custom profile
agents plan use local/my-action --automation-profile local/code-review-profile
```
## Part 3: Safety Profiles
Safety profiles are a sub-component of automation profiles that control security constraints.
### Key Safety Settings
```bash
# Create a safety-focused profile
cat > /tmp/safe-profile.yaml << 'EOF'
name: local/safe-execution
description: "Maximum safety constraints for production environments"
autonomy_threshold: 0.7
safety_profile:
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
read_only: false
max_file_size_bytes: 10485760 # 10MB
guards:
max_cost_per_plan: 2.00
max_total_cost: 20.00
max_tool_calls_per_plan: 100
denylist:
- "shell_exec"
- "network_request"
EOF
agents automation-profile add --config /tmp/safe-profile.yaml
```
## Part 4: Guard Enforcement
Guards provide hard limits that cannot be overridden by the agent.
### Viewing Active Guards
```bash
# Show active guards for a plan
agents plan guard <plan_id>
```
### Guard Types
| Guard | Description |
|-------|-------------|
| `max_cost_per_plan` | Maximum USD cost for a single plan |
| `max_total_cost` | Maximum total cost across all plans |
| `max_tool_calls_per_plan` | Maximum number of tool invocations |
| `denylist` | Tools that are never allowed |
## Part 5: Profile Precedence
When multiple profiles apply, the most specific one wins:
```
plan-level profile > action-level profile > project-level > global default
```
```bash
# Set a project-level default profile
agents config set --scope project --project local/my-project \
plan.default_automation_profile local/safe-execution
# Override at action level in the action YAML
# automation_profile: cautious
# Override at plan level via CLI flag
agents plan use local/my-action --automation-profile full-auto
```
## Part 6: Semantic Escalation
When the agent encounters a situation that exceeds its autonomy threshold, it escalates to the user:
```bash
# Run a plan with a cautious profile — agent will ask before risky operations
agents plan use local/refactor-action --automation-profile cautious
agents plan execute <plan_id>
# The agent will pause and ask:
# "I'm about to delete 15 files. This exceeds my autonomy threshold (0.8).
# Do you want to proceed? [y/N]"
```
## Complete Example: Setting Up a Development Environment Profile
```bash
# 1. Create a development profile with moderate autonomy
cat > /tmp/dev-profile.yaml << 'EOF'
name: local/development
description: "Development environment — moderate autonomy with safety nets"
autonomy_threshold: 0.4
safety_profile:
require_sandbox: true
require_checkpoints: true
allow_unsafe_tools: false
guards:
max_cost_per_plan: 3.00
max_tool_calls_per_plan: 200
denylist:
- "production_deploy"
EOF
agents automation-profile add --config /tmp/dev-profile.yaml
# 2. Set it as the project default
agents config set --scope project --project local/my-app \
plan.default_automation_profile local/development
# 3. Verify the configuration
agents automation-profile show local/development
agents config get --scope project --project local/my-app plan.default_automation_profile
# 4. Run a plan using the profile
agents plan use local/implement-feature
agents plan execute <plan_id>
```
## Key Takeaways
- **Automation profiles** control how autonomously the agent operates (0.0 = full-auto, 1.0 = always ask)
- **Safety profiles** enforce security constraints like sandbox requirements and tool restrictions
- **Guards** provide hard limits on cost, tool calls, and forbidden operations
- **Configuration scoping** allows fine-grained control at global, project, action, and plan levels
- **Semantic escalation** ensures the agent asks for confirmation when it encounters risky operations
## Related Documentation
- [Automation Profiles](../../specification.md#automation-profiles)
- [Safety Profile (Composed Sub-Model)](../../specification.md#safety-profile-composed-sub-model)
- [Guardrails](../../specification.md#guardrails)
- [Configuration System](../../specification.md#configuration)
- [ADR-017 Automation Profiles](../../adr/ADR-017-automation-profiles.md)
- [ADR-024 Configuration System](../../adr/ADR-024-configuration-system.md)
docs/specification.md
+6 -6
Protected
View File
@@ -46815,7 +46815,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: Decisions are recorded during Strategize and Execute phases and persisted to the database. Users can view the decision tree, inspect individual decisions, manage invariants, and correct decisions with selective subtree recomputation.
**Spec Coverage**: [Decision Tree and Correction](#decision-tree-and-correction), [Invariant System](#invariant-system), [Validation Abstraction](#validation-abstraction)
**Spec Coverage**: [Decision Tree and Correction](#the-plan-decision-tree-and-visualization), [Invariant System](#layer-3-invariant-enforcement), [Validation Abstraction](#validation)
#### Deliverables
@@ -46856,7 +46856,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: Plans can spawn child plans (subplans) during execution. Subplans execute in parallel with configurable concurrency limits. Results are merged back using three-way merge strategies. Checkpointing enables rollback to previous plan states.
**Spec Coverage**: [Subplan Architecture](#subplan-architecture), [Checkpoint and Rollback](#checkpoint-and-rollback), [Merge Strategies](#merge-strategies), [Correction Model](#correction-model)
**Spec Coverage**: [Subplan Architecture](#plan-hierarchy-and-parallelism), [Checkpoint and Rollback](#checkpointing-in-execute-core-safety-mechanism), [Merge Strategies](#child-plan-result-merging), [Correction Model](#correcting-plans-core-feature)
#### Deliverables
@@ -46895,7 +46895,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: The Advanced Context Management System v1 is operational. Projects with 10,000+ files can be indexed and queried. The context assembly pipeline produces scoped, budget-constrained context views for actors. Hot/warm/cold storage tiers manage context lifecycle.
**Spec Coverage**: [ACMS Architecture](#acms-advanced-context-management-system), [Context Assembly Pipeline](#context-assembly-pipeline), [UKO Ontology](#uko-universal-knowledge-ontology), [Hot/Warm/Cold Tiers](#context-storage-tiers)
**Spec Coverage**: [ACMS Architecture](#acms-advanced-context-management-system), [Context Assembly Pipeline](#context-assembly-pipeline), [UKO Ontology](#universal-knowledge-ontology-uko), [Hot/Warm/Cold Tiers](#temporal-data-model-and-storage-tiers)
#### Deliverables
@@ -46935,7 +46935,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: The system can autonomously execute a large-scale task using hierarchical plan decomposition with 4+ levels of subplans, decision correction with selective subtree recomputation, parallel execution scaling to 10+ concurrent subplans, and validation-gated apply.
**Spec Coverage**: [Automation Profiles](#automation-profiles), [Safety Profiles](#safety-profiles), [A2A Facade](#agent-to-agent-protocol-a2a), [Guard Enforcement](#guard-enforcement), [Event Queue](#event-queue)
**Spec Coverage**: [Automation Profiles](#automation-profiles), [Safety Profiles](#safety-profile-composed-sub-model), [A2A Facade](#agent-to-agent-protocol-a2a), [Guard Enforcement](#automation-guard-sub-model), [Event Queue](#event-system)
#### Deliverables
@@ -46976,7 +46976,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: Advanced concepts not needed for basic MVP. Extends beyond core MVP but does not require TUI (v3.7.0) or Server (v3.8.0). Includes advanced context strategies, additional LLM backends, additional resource types, A2A module rename, container tool execution, pluggable scope chain extensions, cost/session budgets, and E2E workflow specification tests.
**Spec Coverage**: [LSP Integration](#lsp-integration), [Resource Type Inheritance](#resource-type-inheritance), [Devcontainer Integration](#devcontainer-integration), [Container Resource Types](#container-resource-types), [Advanced Context Strategies](#advanced-context-strategies), [Provider Registry](#provider-registry)
**Spec Coverage**: [LSP Integration](#lsp-integration), [Resource Type Inheritance](#resource-type-inheritance), [Devcontainer Integration](#devcontainer-auto-discovery), [Container Resource Types](#cloud-infrastructure-resource-types), [Advanced Context Strategies](#built-in-strategy-catalogue), [Provider Registry](#plugin-architecture-overview)
#### Deliverables
@@ -47021,7 +47021,7 @@ This section defines the ordered milestone plan for CleverAgents v3.x, mapping a
**Goal**: Implement the comprehensive Text User Interface (TUI) and all TUI-dependent features using Textual ≥ 1.0.
**Spec Coverage**: [TUI Architecture](#tui), [Persona System](#persona-system), [Reference and Command System](#reference-and-command-system), [TUI Materializer](#tui-materializer)
**Spec Coverage**: [TUI Architecture](#tui), [Persona System](#persona-system), [Reference and Command System](#reference-and-command-system), [TUI Materializer](#integration-with-future-tui)
**Key ADRs**: [ADR-044](adr/ADR-044-tui-architecture-and-framework.md), [ADR-045](adr/ADR-045-tui-persona-system.md), [ADR-046](adr/ADR-046-tui-reference-and-command-system.md)
mkdocs.yml
+22
Protected
View File
@@ -45,6 +45,28 @@ nav:
- Automation Tracking: development/automation-tracking.md
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
- Documentation Writer: development/docs-writer.md
- Showcase:
- Overview: showcase/index.md
- CLI Tools:
- Overview: showcase/cli-tools/README.md
- CLI Basics: showcase/cli-tools/cleveragents-cli-basics.md
- Action and Plan Management: showcase/cli-tools/action-and-plan-management.md
- Actor Context Management: showcase/cli-tools/actor-context-management.md
- Actor Management Workflow: showcase/cli-tools/actor-management-workflow.md
- Audit Log and Security: showcase/cli-tools/audit-log-and-security.md
- Config and Automation Profiles: showcase/cli-tools/config-and-automation-profiles.md
- Database Migration Management: showcase/cli-tools/database-migration-management.md
- Output Format Flags: showcase/cli-tools/output-format-flags.md
- Project Init and Context Management: showcase/cli-tools/project-init-and-context-management.md
- REPL and Actor Run: showcase/cli-tools/repl-and-actor-run.md
- Repo Indexing Workflows: showcase/cli-tools/repo-indexing-workflows.md
- Resource and Skill Management: showcase/cli-tools/resource-and-skill-management.md
- Server and A2A Integration: showcase/cli-tools/server-and-a2a-integration.md
- Session Management Workflows: showcase/cli-tools/session-management-workflows.md
- Tool and Validation Management: showcase/cli-tools/tool-and-validation-management.md
- API Clients: showcase/api-clients/README.md
- Data Processing: showcase/data-processing/README.md
- Testing Tools: showcase/testing-tools/README.md
- Implementation Timeline: timeline.md
- FAQ: faq.md
- Reference: reference/