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

docs: add getting-started guide and architecture overview [AUTO-DOCS-3] #8253

Closed
HAL9000 wants to merge 1 commits from auto-docs-3/user-guide-and-architecture into master
pull from: auto-docs-3/user-guide-and-architecture
merge into: cleveragents:master
Conversation 5 Commits 1 Files Changed 5
+996
5 changed files with 996 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/index.md
+68
View File
@@ -0,0 +1,68 @@
# Architecture Documentation
Comprehensive documentation of the CleverAgents platform architecture.
---
## Available Documents
| Document | Description |
|----------|-------------|
| [Architecture Overview](overview.md) | Six-layer architecture, domain concepts, plan lifecycle state machine, actor system, resource system, A2A protocol facade, data flow diagram, and full ADR table |
---
## Quick Reference
### The Six Layers
| Layer | Package(s) | Responsibility |
|-------|-----------|----------------|
| **Entry Points** | `cli`, `tui` | CLI commands, TUI screens |
| **Application** | `application` | DI wiring, service orchestration, A2A facade |
| **Domain** | `domain`, `actor`, `skills`, `tool`, `resource` | Core business logic |
| **Infrastructure** | `infrastructure` | Database, sandbox, events, observability |
| **Integration** | `a2a`, `mcp`, `lsp`, `langgraph`, `acms` | External protocol adapters |
| **Core** | `core`, `shared`, `config` | Cross-cutting utilities |
### Plan Lifecycle at a Glance
```
Action ──► Strategize ──► Execute ──► Apply
│ │ │ │
│ (estimate) (validate) (diff review)
│ │
└───────────────────────────┘
(correction / rollback)
```
### Key Standards
| Standard | Role |
|----------|------|
| **A2A** | Sole client-server communication protocol (JSON-RPC 2.0) |
| **MCP** | External tool discovery and invocation |
| **LSP** | Code intelligence for actors |
| **AgentSkills.io** | Instruction-driven skill packaging |
---
## Related Documentation
- [Specification](../specification.md) — Authoritative platform specification
- [architecture.md](../architecture.md) — Developer-oriented component map with Mermaid diagrams
- [ADR Index](../adr/index.md) — All Architecture Decision Records
- [Getting Started Guide](../guides/getting-started.md) — Step-by-step installation and first plan
- [API Reference](../api/index.md) — Full CLI and Python API reference
---
## Contributing Architecture Documentation
To add new architecture documentation:
1. Create a Markdown file in `docs/architecture/` (e.g., `acms-deep-dive.md`).
2. Add an entry to this index file.
3. Add the document to the `nav` section of `mkdocs.yml` under `Architecture`.
4. Cross-reference the relevant ADRs.
5. Follow the [Documentation Writer](../development/docs-writer.md) standards.
docs/architecture/overview.md
+510
View File
@@ -0,0 +1,510 @@
# Architecture Overview
CleverAgents is a Python-first AI agent orchestration platform built around a strict
**six-layer architecture**, a rich **domain model**, and open **interoperability standards**.
This document provides a comprehensive but accessible overview of the system design.
For the authoritative specification see [`docs/specification.md`](../specification.md).
For individual design decisions see the [ADR index](../adr/index.md).
For the developer-oriented component map see [`docs/architecture.md`](../architecture.md).
---
## Six-Layer Architecture
CleverAgents enforces a strict layered architecture
([ADR-001](../adr/ADR-001-layered-architecture.md)) where **dependencies flow downward
only** — upper layers may import from lower layers but never the reverse.
```
┌─────────────────────────────────────────────────────────────────┐
│ LAYER 1 — ENTRY POINTS │
│ CLI (agents / cleveragents) │ TUI (agents tui) │ Server │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 2 — APPLICATION │
│ A2A Facade │ DI Container │ Application Services │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 3 — DOMAIN │
│ Plan Lifecycle │ Actor System │ Resource DAG │
│ Decision Tree │ Skill System │ Tool System │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 4 — INFRASTRUCTURE │
│ Database (SQLAlchemy) │ Sandbox │ Event Bus │
│ Observability │ Plugin Manager │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 5 — INTEGRATION │
│ LangGraph Bridge │ MCP Adapter │ LSP Client │
│ ACMS │ UKO Runtime │
├─────────────────────────────────────────────────────────────────┤
│ LAYER 6 — CORE │
│ Shared Utilities │ Configuration │ Cross-cutting Concerns │
└─────────────────────────────────────────────────────────────────┘
```
| Layer | Package(s) | Responsibility |
|-------|-----------|----------------|
| **Entry Points** | `cli`, `tui` | User-facing interfaces — CLI commands, TUI screens |
| **Application** | `application` | DI wiring, service orchestration, A2A facade |
| **Domain** | `domain`, `actor`, `skills`, `tool`, `resource` | Core business logic and domain model |
| **Infrastructure** | `infrastructure` | Database, sandbox, events, observability, plugins |
| **Integration** | `a2a`, `mcp`, `lsp`, `langgraph`, `acms` | External protocol adapters and runtime bridges |
| **Core** | `core`, `shared`, `config` | Cross-cutting utilities, configuration, logging |
---
## Key Domain Concepts
### Plan
A **Plan** is a ULID-identified, hierarchical unit of work instantiated from an Action
template. It progresses through four phases and persists a decision tree at each step.
- May spawn child plans (hierarchical composition)
- Scoped to one or more projects
- Top-level plans carry a namespaced name (`[[server:]namespace/]name`)
- Child plans are identified solely by their plan ID (ULID)
### Action
An **Action** is a YAML-defined, reusable plan template specifying:
- Description and definition of done
- Strategy and execution actors
- Typed arguments
- Optional invariants
Actions are project-agnostic until bound to a project via `agents plan use`.
### Actor
An **Actor** is a YAML-configured conversational unit — either a single LLM/agent or a
composed LangGraph of actors and tool nodes.
Specialized actor roles:
| Role | Description |
|------|-------------|
| **Strategy Actor** | Produces the initial decision tree during Strategize |
| **Execution Actor** | Carries out decisions during Execute |
| **Estimation Actor** | Wired via `actor.default.estimation` config key |
| **Invariant Reconciliation Actor** | Runs automatically at each phase transition |
### Tool
A **Tool** is the atomic unit of execution — a namespaced, independently registered
callable operation with:
- JSON Schema inputs/outputs
- Capability metadata (`read_only`, `writes`, `checkpointable`)
- Four-stage lifecycle: `discover → activate → execute → deactivate`
- Sources: MCP servers, Agent Skills folders, built-ins, or custom Python
### Skill
A **Skill** is a composable, namespaced collection of tools. Actors reference skills
by name to acquire capabilities. Skills can:
- Reference named tools
- Define inline anonymous tools
- Include other skills
- Expose MCP server tools and AgentSkills.io tools
### Resource
A **Resource** is a ULID-identified entity registered in the Resource Registry
representing anything readable, writable, or queryable:
- Git repositories (`git-checkout`)
- Filesystems (`fs-mount`, `fs-directory`)
- Databases (`sqlite`, `postgresql`, `mysql`, `duckdb`)
- Containers (`container.docker`, `container.podman`, `devcontainer-instance`)
- LSP servers (`lsp.*`)
- Cloud infrastructure (`cloud.*`)
Resources are organized as a **DAG** (Directed Acyclic Graph) with dependency tracking
and support single-inheritance type hierarchies ([ADR-042](../adr/ADR-042-resource-type-inheritance.md)).
### Project
A **Project** is a named scope linking resources, context policies, invariants, and
validation attachments. Projects do not own resources — a single resource may be linked
to multiple projects.
### Decision
A **Decision** is a persisted choice point in a plan's decision tree, created during
Strategize or Execute. It records:
- The question and chosen option
- Alternatives considered
- Confidence score and rationale
- Context snapshot
- Downstream dependencies
Decisions support targeted correction with selective subtree recomputation
([ADR-007](../adr/ADR-007-decision-tree-and-correction.md)).
---
## Plan Lifecycle State Machine
The plan lifecycle is the central abstraction ([ADR-006](../adr/ADR-006-plan-lifecycle.md)):
```
┌─────────────────────────────────────────┐
│ │
▼ │
┌──────────┐ │
│ ACTION │ User intent captured as a │
│ (init) │ plan request from an Action │
└────┬─────┘ template │
│ │
▼ │
┌────────────────┐ │
│ STRATEGIZE │ LLM generates structured plan │
│ (read-only) │ decision tree; no resource │
└────────┬───────┘ mutations │
│ │
│ [optional: Estimate phase] │
│ │
▼ │
┌────────────────┐ │
│ EXECUTE │ Operations executed against │
│ (sandbox) │ resources via tools; all │
└────────┬───────┘ mutations in sandbox │
│ │
▼ │
┌────────────────┐ │
│ APPLY │ Sandbox changeset merged into │
│ (commit) │ real project resources after │
└────────┬───────┘ diff review │
│ │
┌─────────┼──────────────┐ │
▼ ▼ ▼ │
[applied] [errored] [constrained] ─────────────────►┘
(revert to Strategize)
```
### Phase Details
| Phase | Actor | Mutations | Output |
|-------|-------|-----------|--------|
| **Action** | — | None | Plan instantiated from Action template |
| **Strategize** | Strategy Actor | None (read-only) | Decision tree with strategy choices |
| **Execute** | Execution Actor | Sandbox only | Artifacts, tool results, child plans |
| **Apply** | — | Real resources | Merged changeset; terminal state |
### Phase Transition Gates
Every phase transition is gated by:
1. **Invariant Reconciliation** — `InvariantReconciliationActor` runs automatically;
failures block the transition with `ReconciliationBlockedError`
2. **Validation Pipeline** — rule-based checks with severity levels
3. **Definition-of-Done** — explicit criteria evaluated before Apply
4. **Advisory Locking** — prevents concurrent modification of the same plan
---
## Actor System
Actors are defined in YAML with a LangGraph node graph
([ADR-010](../adr/ADR-010-actor-and-agent-architecture.md),
[ADR-031](../adr/ADR-031-actor-abstraction-definition.md)):
```yaml
name: local/my-workflow-actor
entry_node: planner
nodes:
planner:
model: gpt-4o
tool_sources: [builtin, mcp://bash-tools]
lsp_bindings: [python]
executor:
model: gpt-4o-mini
tool_sources: [builtin, skill://my-skill]
edges:
- from: planner
to: executor
condition: needs_execution
```
### Actor Types
| Type | Description |
|------|-------------|
| **LLM Actor** | Single LLM node; simplest form |
| **Graph Actor** | Multi-node LangGraph with routing conditions |
| **Tool Actor** | Wraps a tool as an actor for composability |
| **Built-in Actors** | `openai/gpt-4o`, `anthropic/claude-*`, etc. — immutable |
| **Custom Actors** | Must be named `local/<id>` |
### Actor Compilation
1. YAML loaded and validated by `ActorLoader`
2. `ActorCompiler` resolves tool sources, LSP bindings, and skill references
3. `CompiledActor` registered in `ActorRegistry`
4. Resolved by name at runtime via the DI container
---
## Resource System
Resources are managed via the Resource Registry
([ADR-008](../adr/ADR-008-resource-system.md)):
```
Resource Registry (DAG)
│
├── git-checkout: /repos/my-app (physical)
│ └── devcontainer-instance: my-app (auto-discovered, inherits container-instance)
│
├── fs-directory: /data/docs (physical)
│
├── postgresql: prod-db (physical)
│
└── virtual-repo: my-app-identity (virtual — links physical equivalents)
```
### Resource Handler Lifecycle
Each resource type implements a handler with:
- **CRUD** — read, write, list, delete
- **Checkpoint** — snapshot current state before mutations
- **Rollback** — restore from checkpoint on failure or rejection
- **Sandbox** — isolate mutations during Execute phase
### Built-in Resource Types
| Type | Description |
|------|-------------|
| `git-checkout` | Git repository at a specific path/URL |
| `fs-mount` / `fs-directory` | Filesystem mount or directory |
| `sqlite` / `postgresql` / `mysql` / `duckdb` | Database resources |
| `container.docker` / `container.podman` | Container instances |
| `devcontainer-instance` | Dev container (inherits `container-instance`) |
| `lsp.*` | Language server resources |
| `cloud.*` | Cloud infrastructure resources |
---
## A2A Protocol Facade
All CLI, TUI, and server interactions cross the **A2A (Agent-to-Agent Protocol)**
boundary ([ADR-026](../adr/ADR-026-agent-client-protocol.md),
[ADR-047](../adr/ADR-047-acp-standard-adoption.md)):
```
CLI / TUI / IDE Plugin / Third-party Client
│
│ JSON-RPC 2.0 (A2A)
▼
┌─────────────────────┐
│ A2A Facade │
│ │
│ Local mode: │
│ A2aLocalFacade │──► Direct Python calls to Application Services
│ (stdio / in-proc) │
│ │
│ Server mode: │
│ A2aHttpTransport │──► HTTP → CleverAgents Server
└─────────────────────┘
```
### Standard A2A Operations
| Operation | Description |
|-----------|-------------|
| `message/send` | Send a message to an actor |
| `message/stream` | Stream responses via SSE |
| Task lifecycle | Create, update, cancel tasks |
| Agent Card | Capability discovery |
### CleverAgents Extensions (`_cleveragents/` prefix)
| Extension Method | Description |
|-----------------|-------------|
| `_cleveragents/plan.*` | Plan lifecycle operations |
| `_cleveragents/registry.*` | Registry CRUD (actors, tools, skills, resources) |
| `_cleveragents/entity.*` | Entity sync |
| `_cleveragents/namespace.*` | Namespace management |
| `_cleveragents/diagnostics` | Platform diagnostics |
---
## Data Flow Diagram
The following ASCII diagram shows the end-to-end data flow for a typical plan execution:
```
User Input (CLI / TUI)
│
│ agents plan use <action> --project <project>
▼
┌─────────────┐
│ CLI / TUI │ Entry Point Layer
└──────┬──────┘
│ A2A JSON-RPC 2.0
▼
┌─────────────┐
│ A2A Facade │ Application Layer
└──────┬──────┘
│
▼
┌──────────────────┐
│ PlanService │ Application Services
│ SessionService │
└──────┬───────────┘
│
▼
┌──────────────────────────────────────────┐
│ Plan Lifecycle (Domain Layer) │
│ │
│ Action ──► Strategize ──► Execute ──► Apply
│ │ │
│ [Decision Tree] [Sandbox]
└──────┬───────────────────────────────────┘
│
├──► ActorRegistry ──► ActorCompiler ──► CompiledActor
│ │
│ ┌─────────┴──────────┐
│ │ LangGraph Bridge │
│ │ (Integration Layer)│
│ └─────────┬──────────┘
│ │
│ ┌───────────────┼───────────────┐
│ ▼ ▼ ▼
│ MCP Adapter LSP Client ACMS/UKO
│ (ext tools) (code intel) (context mgmt)
│
├──► ResourceRegistry ──► ResourceHandler ──► Checkpoint/Rollback
│
├──► ToolRegistry ──► Tool Execution ──► Sandbox
│
└──► Database (SQLAlchemy) ──► Persistence
│
└──► Observability (logging, metrics, audit)
```
---
## Advanced Context Management System (ACMS)
The ACMS manages what context is assembled and sent to the LLM at each phase
([ADR-014](../adr/ADR-014-context-management-acms.md)):
```
Context Assembly Pipeline
│
├── Tier 1 (Hot) — Always-present system context; per-actor scoped views
├── Tier 2 (Warm) — Phase-specific context (plan, project, actor)
└── Tier 3 (Cold) — Dynamic retrieval via pluggable Context Strategies
│
├── Keyword Search Strategy
├── Semantic Embedding Strategy
├── Graph Navigation Strategy (UKO)
└── Temporal Archaeology Strategy
```
### Universal Knowledge Ontology (UKO)
The UKO is an RDF-based, inheritance-driven ontology with four layers:
1. **Universal Foundation** — base concepts applicable to all domains
2. **Domain Specializations** — software, documents, data schemas, infrastructure
3. **Paradigm/Format Specializations** — procedural programming, markdown
4. **Technology-Specific** — Python, PostgreSQL, etc.
Key UKO capabilities:
- **Typed triples with provenance** — every triple carries `sourceResource`,
`validFrom`, and `isCurrent` metadata
- **Temporal versioning** — revision chain enables point-in-time queries
- **Implicit inference** — `UKOInferenceEngine` produces implicit relationship triples
with confidence scores
---
## Key Architecture Decision Records (ADRs)
The following ADRs document the most significant design decisions:
| ADR | Title | Summary |
|-----|-------|---------|
| [ADR-001](../adr/ADR-001-layered-architecture.md) | Layered Architecture | Strict six-layer boundaries; no upward imports |
| [ADR-002](../adr/ADR-002-namespace-system.md) | Namespace System | `[[server:]namespace/]name` qualified identifiers |
| [ADR-003](../adr/ADR-003-dependency-injection.md) | Dependency Injection | Single DI container; no service locator pattern |
| [ADR-004](../adr/ADR-004-data-validation.md) | Data Validation | Pydantic-based validation at domain boundaries |
| [ADR-005](../adr/ADR-005-technical-stack.md) | Technical Stack | Python 3.13+, LangGraph, SQLAlchemy, Textual |
| [ADR-006](../adr/ADR-006-plan-lifecycle.md) | Plan Lifecycle | Four-phase lifecycle with gating and invariants |
| [ADR-007](../adr/ADR-007-decision-tree-and-correction.md) | Decision Tree & Correction | Persisted decision tree with targeted recomputation |
| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | DAG-organized resources with handler lifecycle |
| [ADR-009](../adr/ADR-009-project-model.md) | Project Model | Projects as resource scopes, not resource owners |
| [ADR-010](../adr/ADR-010-actor-and-agent-architecture.md) | Actor & Agent Architecture | YAML-configured LangGraph actors |
| [ADR-011](../adr/ADR-011-tool-system.md) | Tool System | Atomic, namespaced, four-stage lifecycle tools |
| [ADR-012](../adr/ADR-012-skill-system.md) | Skill System | Composable tool bundles with progressive disclosure |
| [ADR-013](../adr/ADR-013-validation-abstraction.md) | Validation Abstraction | Tool subtype with pass/fail semantics |
| [ADR-014](../adr/ADR-014-context-management-acms.md) | Context Management (ACMS) | Pluggable, tiered context assembly pipeline |
| [ADR-015](../adr/ADR-015-sandbox-and-checkpoint.md) | Sandbox & Checkpoint | Checkpoint/rollback for all resource writes |
| [ADR-016](../adr/ADR-016-invariant-system.md) | Invariant System | Four-scope invariants with precedence resolution |
| [ADR-017](../adr/ADR-017-automation-profiles.md) | Automation Profiles | Confidence-threshold gating for autonomous operation |
| [ADR-018](../adr/ADR-018-semantic-error-prevention.md) | Semantic Error Prevention | Type-safe domain model to prevent logic errors |
| [ADR-019](../adr/ADR-019-storage-and-persistence.md) | Storage & Persistence | SQLAlchemy + Alembic; ULID primary keys |
| [ADR-020](../adr/ADR-020-session-model.md) | Session Model | Persistent conversation threads tied to actors |
| [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) | CLI & Output Rendering | Typer/Click CLI with Rich output rendering |
| [ADR-022](../adr/ADR-022-langchain-langgraph-integration.md) | LangGraph Integration | LangGraph as graph execution engine |
| [ADR-023](../adr/ADR-023-server-mode.md) | Server Mode | Multi-user shared backend with namespace resolution |
| [ADR-024](../adr/ADR-024-configuration-system.md) | Configuration System | Layered config: defaults → file → env → CLI flags |
| [ADR-025](../adr/ADR-025-observability-and-logging.md) | Observability & Logging | Structured logging, metrics, audit trail |
| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | A2A Protocol | JSON-RPC 2.0 as sole client-server protocol |
| [ADR-027](../adr/ADR-027-language-server-protocol.md) | LSP Integration | LSP servers as code intelligence tools for actors |
| [ADR-028](../adr/ADR-028-agent-skills-standard.md) | Agent Skills Standard | AgentSkills.io SKILL.md packaging |
| [ADR-029](../adr/ADR-029-model-context-protocol.md) | MCP Adoption | MCP servers bridged into Tool Registry |
| [ADR-030](../adr/ADR-030-skill-abstraction-definition.md) | Skill Abstraction | Formal skill definition and registry contract |
| [ADR-031](../adr/ADR-031-actor-abstraction-definition.md) | Actor Abstraction | Formal actor definition and compilation contract |
| [ADR-032](../adr/ADR-032-jinja2-yaml-template-preprocessing.md) | Jinja2 YAML Templates | Sandboxed Jinja2 with allowlist for YAML configs |
| [ADR-033](../adr/ADR-033-decision-recording-protocol.md) | Decision Recording | Protocol for persisting decisions during plan phases |
| [ADR-034](../adr/ADR-034-decision-tree-versioning-and-history.md) | Decision Tree Versioning | Immutable history with version pointers |
| [ADR-035](../adr/ADR-035-decision-tree-rollback-and-replay.md) | Decision Tree Rollback | Rollback to prior version; selective subtree replay |
| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Semantics | DAG traversal, dependency resolution, cycle detection |
| [ADR-037](../adr/ADR-037-tool-reachability-and-access-projection.md) | Tool Reachability | Access projection for tool visibility per actor node |
| [ADR-038](../adr/ADR-038-cross-mechanism-sandbox-coordination.md) | Sandbox Coordination | Coordinating git, container, and DB sandboxes |
| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Docker/Podman container resource type hierarchy |
| [ADR-040](../adr/ADR-040-lsp-resource-types.md) | LSP Resource Types | LSP server resource type and registry |
| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles as composable sub-models |
| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Single-inheritance type hierarchy with field merging |
| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Auto-discovered dev containers as resource types |
| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture | Textual-based full-screen TUI with persona system |
| [ADR-045](../adr/ADR-045-tui-persona-system.md) | TUI Persona System | YAML-backed personas with actor/preset binding |
| [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference & Commands | Slash commands and reference picker system |
| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | Adopting the external A2A protocol standard |
| [ADR-048](../adr/ADR-048-server-application-architecture.md) | Server Application Architecture | ASGI server with Kubernetes Helm deployment |
---
## Standards Alignment
CleverAgents deliberately adopts open, versioned protocols for interoperability:
| Standard | Role | Key Benefit |
|----------|------|-------------|
| **A2A** (Agent-to-Agent Protocol) | Sole client-server communication protocol | Interchangeable clients; Agent Card discovery |
| **MCP** (Model Context Protocol) | External tool discovery and invocation | Plug-and-play tool ecosystem |
| **LSP** (Language Server Protocol) | Code intelligence for actors | Semantic understanding from mature LSP ecosystem |
| **AgentSkills.io** | Instruction-driven skill packaging | Teaches agents *how* to accomplish complex tasks |
---
## Further Reading
| Document | Description |
|----------|-------------|
| [Specification](../specification.md) | Authoritative platform specification with full glossary |
| [architecture.md](../architecture.md) | Developer-oriented component map with Mermaid diagrams |
| [ADR Index](../adr/index.md) | All Architecture Decision Records |
| [Getting Started Guide](../guides/getting-started.md) | Step-by-step installation and first plan |
| [CLI Reference](../api/index.md) | Full command reference |
| [Python API](../api/core.md) | Programmatic access to CleverAgents services |
| [A2A Protocol](../api/a2a.md) | A2A protocol implementation details |
| [Development Guide](../development/quality-automation.md) | Nox sessions, linting, testing |
docs/guides/getting-started.md
+371
View File
@@ -0,0 +1,371 @@
# Getting Started with CleverAgents
Welcome to **CleverAgents** — a unified platform for orchestrating complex AI agent tasks.
This guide walks you through installation, first-run verification, LLM provider setup, and
running your first plan end-to-end.
---
## Prerequisites
| Requirement | Minimum Version | Notes |
|-------------|----------------|-------|
| **Python** | 3.13+ | Required for all runtime features |
| **Git** | 2.38+ | Required for git-checkout resources and sandbox |
| **pip** | 23+ | Bundled with Python 3.13 |
| **bash** | any | Used by `setup-dev.sh` |
!!! tip "Check your Python version"
```bash
python --version # should print Python 3.13.x or later
git --version
```
---
## Installation
### 1. Clone the Repository
```bash
git clone https://git.cleverthis.com/cleveragents/core.git
cd core
```
### 2. Create a Virtual Environment
```bash
python -m venv .venv
source .venv/bin/activate # Linux / macOS
# .venv\Scripts\activate # Windows PowerShell
```
### 3. Install the Package
Install the core package plus the optional extras you need:
```bash
# Core + development tools + tests + docs
pip install -e ".[dev,tests,docs]"
# Add the TUI (Textual-based interactive terminal UI)
pip install -e ".[tui]"
```
!!! note "Extras at a glance"
| Extra | Contents |
|-------|----------|
| `dev` | Nox, Ruff, Pyright, pre-commit |
| `tests` | Behave, Robot Framework, pytest |
| `docs` | MkDocs, mkdocstrings, kroki |
| `tui` | Textual and TUI dependencies |
### 4. Run the Developer Setup Script
```bash
bash scripts/setup-dev.sh
```
This installs pre-commit hooks (formatting, linting, type-checking, security scanning)
and verifies that all required tooling is available.
---
## First Run
### Verify the CLI
```bash
agents --version
agents --help
```
Both `agents` and `cleveragents` are equivalent entry points.
### Run Diagnostics
```bash
agents diagnostics
```
`diagnostics` prints:
- Whether the registry can see your credentials
- Which actor/provider is selected
- Data directory and configuration paths
- Any missing dependencies or misconfigurations
---
## Setting Up an LLM Provider
CleverAgents auto-discovers API keys from environment variables and selects the best
available provider. Export at least one of the following:
| Provider | Environment Variable(s) |
|----------|------------------------|
| **OpenAI** | `OPENAI_API_KEY` |
| **Anthropic** | `ANTHROPIC_API_KEY` |
| **Google** | `GOOGLE_API_KEY` or `GOOGLE_GENAI_API_KEY` |
| **Azure OpenAI** | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_ENDPOINT` + `AZURE_OPENAI_DEPLOYMENT` |
| **OpenRouter** | `OPENROUTER_API_KEY` |
| **Gemini** | `GEMINI_API_KEY` or `GOOGLE_GEMINI_API_KEY` |
| **Cohere** | `COHERE_API_KEY` |
| **Groq** | `GROQ_API_KEY` |
| **Together** | `TOGETHER_API_KEY` |
### Quick Example — OpenAI
```bash
export OPENAI_API_KEY="sk-..."
agents diagnostics # should now show openai/gpt-4o as the selected actor
```
### Pin a Specific Provider and Model
```bash
export CLEVERAGENTS_DEFAULT_PROVIDER=anthropic
export CLEVERAGENTS_DEFAULT_MODEL=claude-sonnet-4-20250514
```
### Set a Default Actor
```bash
agents actor set-default openai/gpt-4o
```
!!! tip "Testing without an API key"
Set `CLEVERAGENTS_TESTING_USE_MOCK_AI=true` to force the built-in mock provider.
This is how the Behave/Robot test suites run without hitting external APIs.
---
## Creating Your First Action
An **Action** is a reusable YAML template that describes a task — the plan's "what".
Actions are project-agnostic until bound to a project.
```bash
agents action create my-first-action \
--description "Summarise the README of a repository" \
--strategy-actor openai/gpt-4o \
--execution-actor openai/gpt-4o
```
List available actions:
```bash
agents action list
agents action show my-first-action
```
---
## Creating a Project and Linking a Resource
A **Project** groups resources (git repos, databases, filesystems) and provides the
context in which plans execute.
### 1. Register a Git Resource
```bash
agents resource add git-checkout \
--url https://github.com/example/my-repo.git \
--path /tmp/my-repo \
my-repo
```
### 2. Create a Project
```bash
agents project create my-project \
--description "My first CleverAgents project"
```
### 3. Link the Resource to the Project
```bash
agents project link-resource my-project my-repo
```
Verify the project:
```bash
agents project show my-project
```
---
## Running Your First Plan
A **Plan** is a live instance of an Action bound to a project. It progresses through
four phases: **Action → Strategize → Execute → Apply**.
### 1. Instantiate a Plan
```bash
agents plan use my-first-action --project my-project
```
This prints the new plan ID (a ULID, e.g. `01HZ...`). Export it for convenience:
```bash
export PLAN_ID=01HZ...
```
### 2. Run the Strategize Phase
The strategy actor reads the action template and project context, then produces a
structured decision tree — without modifying any resources.
```bash
agents plan execute --phase strategize $PLAN_ID
```
Review the generated strategy:
```bash
agents plan show $PLAN_ID
agents plan decisions $PLAN_ID
```
### 3. Run the Execute Phase
The execution actor carries out the decisions from Strategize — invoking tools,
producing artifacts, and writing to the sandbox.
```bash
agents plan execute --phase execute $PLAN_ID
```
### 4. Review the Diff
Before committing changes, inspect what the plan proposes to change:
```bash
agents plan diff $PLAN_ID
```
This shows a unified diff of all sandbox changes against the current resource state.
### 5. Apply the Changes
If the diff looks correct, apply the changes to the real resources:
```bash
agents plan apply $PLAN_ID
```
!!! warning "Apply is irreversible by default"
Once applied, changes are merged into the real resource. Use `--dry-run` to
preview the apply operation without committing.
### Full Plan Lifecycle at a Glance
```
agents plan use <action> --project <project> # Action phase — instantiate
agents plan execute --phase strategize <id> # Strategize — plan the work
agents plan execute --phase execute <id> # Execute — do the work (sandbox)
agents plan diff <id> # Review proposed changes
agents plan apply <id> # Apply — commit to real resources
```
---
## Using the TUI
The **TUI** (Terminal User Interface) provides a full-screen, interactive experience
for working with CleverAgents — ideal for exploratory sessions and multi-plan workflows.
### Launch
```bash
agents tui
```
On first launch, the **Actor Selection Overlay** guides you to pick an actor and
automatically creates a `"default"` persona.
### Key Bindings
| Key | Action |
|-----|--------|
| `Enter` | Send message to the active actor |
| `/` | Open slash command overlay (67 commands across 14 groups) |
| `@` | Open reference picker — insert file/resource references |
| `!` | Enter shell mode — run a subprocess command |
| `F1` | Toggle context-sensitive help panel |
| `Ctrl+T` | Cycle through argument presets for the active persona |
| `Ctrl+Q` | Quit |
### Slash Commands (Examples)
```
/plan use my-first-action --project my-project
/plan execute
/plan diff
/plan apply
/session create --actor openai/gpt-4o
/actor set-default anthropic/claude-sonnet-4-20250514
```
### Shell Mode
Prefix a command with `!` to run it as a subprocess:
```
! git status
! ls -la
```
!!! warning "Shell Danger Detection"
The TUI classifies shell commands by danger level (LOW → CRITICAL) and shows a
warning overlay before executing destructive, privilege-escalating, or
exfiltration-risk commands.
---
## Session Management
Sessions are persistent conversation threads tied to an actor.
```bash
# Create a new session
agents session create --actor openai/gpt-4o
# List all sessions
agents session list
# Export a session (JSON or Markdown)
agents session export --session-id <ID> --output session.json
agents session export --session-id <ID> --format md --output session.md
# Import a session
agents session import --input session.json
```
---
## Next Steps
Now that you have CleverAgents running, explore these resources:
| Resource | Description |
|----------|-------------|
| [Architecture Overview](../architecture/overview.md) | Six-layer architecture, domain concepts, data flow |
| [CLI Reference](../api/index.md) | Full command reference with all flags |
| [Python API](../api/core.md) | Programmatic access to CleverAgents services |
| [A2A Protocol](../api/a2a.md) | Agent-to-Agent protocol details |
| [Specification](../specification.md) | Authoritative platform specification |
| [ADR Index](../adr/index.md) | Architecture Decision Records |
| [Development Guide](../development/quality-automation.md) | Nox sessions, linting, testing |
| [FAQ](../faq.md) | Frequently asked questions |
### Common Workflows
- **Multi-actor pipelines** — compose actors in a LangGraph YAML to chain strategy and execution roles
- **Custom tools** — register tools with `agents tool add --config tool.yaml`
- **Custom skills** — bundle tools into skills with `agents skill add --config skill.yaml`
- **Invariants** — add constraints to projects with `agents project create --invariant "..."`
- **Server mode** — connect to a shared backend with `agents server connect --url <URL> --token <TOKEN>`
- **Observability** — enable LangSmith tracing with `CLEVERAGENTS_LANGSMITH_ENABLED=true`
docs/guides/index.md
+41
View File
@@ -0,0 +1,41 @@
# Guides
Practical, task-oriented guides for working with CleverAgents.
---
## Available Guides
| Guide | Description |
|-------|-------------|
| [Getting Started](getting-started.md) | Install CleverAgents, configure an LLM provider, and run your first plan end-to-end |
---
## What's in a Guide?
Guides are **task-oriented** — they walk you through accomplishing a specific goal
step by step. They assume you want to *do* something rather than *understand* something.
For conceptual background, see:
- [Architecture Overview](../architecture/overview.md) — how CleverAgents is structured
- [Specification](../specification.md) — the authoritative platform specification
- [ADR Index](../adr/index.md) — the reasoning behind key design decisions
For reference material, see:
- [CLI Reference](../api/index.md) — every command and flag
- [Python API](../api/core.md) — programmatic access to CleverAgents services
---
## Contributing a Guide
To add a new guide:
1. Create a Markdown file in `docs/guides/` following the naming convention
`<topic>.md` (e.g., `custom-actors.md`).
2. Add an entry to this index file.
3. Add the guide to the `nav` section of `mkdocs.yml` under `Guides`.
4. Follow the [Documentation Writer](../development/docs-writer.md) standards.
mkdocs.yml
+6
View File
@@ -11,6 +11,12 @@ site_dir: build/site
nav:
- Specification: specification.md
- Architecture: architecture.md
- Guides:
- Overview: guides/index.md
- Getting Started: guides/getting-started.md
- Architecture Deep Dive:
- Overview: architecture/index.md
- Architecture Overview: architecture/overview.md
- API Reference:
- Overview: api/index.md
- Core Utilities: api/core.md