forked from cleveragents/cleveragents-core
111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
# Automation Profiles
|
|
|
|
Automation Profiles control how much autonomy the CleverAgents system has at each phase of plan execution. Each profile defines a set of **threshold values** and **safety requirements** that determine when the system may proceed automatically versus when it must wait for human approval.
|
|
|
|
## Threshold Semantics
|
|
|
|
Each threshold field is a float in the range `[0.0, 1.0]`:
|
|
|
|
| Value | Meaning |
|
|
|-------|---------|
|
|
| `0.0` | Fully automatic — no human gate required |
|
|
| `1.0` | Always requires human approval |
|
|
| `0.0 < v < 1.0` | Probabilistic — the system may proceed if its confidence exceeds the threshold |
|
|
|
|
### Threshold Fields
|
|
|
|
| Field | Category | Description |
|
|
|-------|----------|-------------|
|
|
| `auto_strategize` | Phase transition | Gate before entering the strategy phase |
|
|
| `auto_execute` | Phase transition | Gate before entering the execution phase |
|
|
| `auto_apply` | Phase transition | Gate before applying changes |
|
|
| `auto_decisions_strategize` | Decision autonomy | Gate for decisions during strategy |
|
|
| `auto_decisions_execute` | Decision autonomy | Gate for decisions during execution |
|
|
| `auto_validation_fix` | Self-repair | Gate for automatic validation fixes |
|
|
| `auto_strategy_revision` | Self-repair | Gate for automatic strategy revision |
|
|
| `auto_reversion_from_apply` | Self-repair | Gate for reverting from the apply phase |
|
|
| `auto_child_plans` | Child plans | Gate for spawning child plans |
|
|
| `auto_retry_transient` | Retry | Gate for retrying transient failures |
|
|
| `auto_checkpoint_restore` | Checkpoint | Gate for automatic checkpoint restoration |
|
|
|
|
### Safety Fields
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `require_sandbox` | bool | `true` | Execution must happen in a sandbox |
|
|
| `require_checkpoints` | bool | `true` | Checkpoints must be created before writes |
|
|
| `allow_unsafe_tools` | bool | `false` | Tools flagged as `unsafe` may be invoked |
|
|
|
|
## Built-in Profiles
|
|
|
|
Eight profiles ship with every CleverAgents installation:
|
|
|
|
| Flag | manual | review | supervised | cautious | trusted | auto | ci | full-auto |
|
|
|------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
|
|
| auto_strategize | 1.0 | 0.0 | 0.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_execute | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_apply | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 1.0 | 0.0 | 0.0 |
|
|
| auto_decisions_strategize | 1.0 | 1.0 | 0.0 | 0.6 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_decisions_execute | 1.0 | 1.0 | 1.0 | 0.8 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_validation_fix | 1.0 | 1.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_strategy_revision | 1.0 | 1.0 | 1.0 | 0.8 | 1.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_reversion_from_apply | 1.0 | 1.0 | 1.0 | 0.9 | 1.0 | 1.0 | 0.0 | 0.0 |
|
|
| auto_child_plans | 1.0 | 0.0 | 1.0 | 0.7 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_retry_transient | 1.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 | 0.0 |
|
|
| auto_checkpoint_restore | 1.0 | 1.0 | 1.0 | 0.6 | 1.0 | 0.0 | 0.0 | 0.0 |
|
|
| require_sandbox | true | true | true | true | true | true | true | false |
|
|
| require_checkpoints | true | true | true | true | true | true | true | false |
|
|
| allow_unsafe_tools | false | false | false | false | false | false | false | true |
|
|
|
|
### Profile Descriptions
|
|
|
|
- **manual** — Human approves every action. Maximum safety, minimum autonomy.
|
|
- **review** — Strategy and execution proceed automatically; human reviews before apply. Good default for development.
|
|
- **supervised** — Human reviews strategy and execution decisions. Strategy creation itself is automatic.
|
|
- **cautious** — Probabilistic gates on most actions. The system proceeds when confident, asks when unsure.
|
|
- **trusted** — Automatic for most phases, but human approval required for apply and reversion. Suitable for experienced teams.
|
|
- **auto** — Fully automatic except reversion from apply. Suitable for well-tested pipelines.
|
|
- **ci** — Designed for CI/CD pipelines. All thresholds at 0.0 but sandbox and checkpoints remain required.
|
|
- **full-auto** — No gates, no sandbox, no checkpoints, unsafe tools allowed. Use with extreme caution.
|
|
|
|
## Resolution Precedence
|
|
|
|
When determining which profile applies to a given plan execution, the system resolves profiles in the following order (highest priority first):
|
|
|
|
1. **Plan-level override** — A profile specified directly on the plan.
|
|
2. **Project-level setting** — The default profile configured for the project.
|
|
3. **Organization-level default** — The organization's default profile.
|
|
4. **System default** — Falls back to the `review` built-in profile.
|
|
|
|
At each level, the profile may be specified by:
|
|
- A built-in name (e.g. `cautious`)
|
|
- A namespaced custom profile (e.g. `acme/strict`)
|
|
|
|
## Custom Profiles
|
|
|
|
Custom profiles use a `namespace/name` naming convention:
|
|
|
|
```yaml
|
|
name: acme/strict
|
|
description: Strict profile for production deployments
|
|
schema_version: "1.0"
|
|
|
|
auto_strategize: 0.9
|
|
auto_execute: 0.9
|
|
auto_apply: 1.0
|
|
auto_decisions_strategize: 0.8
|
|
auto_decisions_execute: 0.9
|
|
auto_validation_fix: 0.5
|
|
auto_strategy_revision: 0.9
|
|
auto_reversion_from_apply: 1.0
|
|
auto_child_plans: 0.8
|
|
auto_retry_transient: 0.3
|
|
auto_checkpoint_restore: 0.7
|
|
|
|
require_sandbox: true
|
|
require_checkpoints: true
|
|
allow_unsafe_tools: false
|
|
```
|
|
|
|
See `docs/schema/automation_profile.schema.yaml` for the full YAML schema and `examples/profiles/` for example configurations.
|