cleveragents-core/docs/specification/index.md

CleverAgents Documentation (Detailed Spec)

Overview

CleverAgents is your command center for AI agents — a unified platform for orchestrating any task you want agents to accomplish, from developing large software projects to writing comprehensive technical papers, administering databases, managing cloud infrastructure, or any complex multi-step workflow.

The core value proposition is enabling long-running, complex, large-scale tasks to execute autonomously with minimal human intervention, making it ideal for building entire software systems, producing extensive documentation, or managing sophisticated operations largely hands-off.

!!! info "Server Mode"

In **server mode**, CleverAgents becomes a collaborative hub where teams can share resources — prompts, actors, actions, and projects — while executing plans in the cloud. This enables a consistent experience across all your devices: start a complex task on your laptop, check progress from your phone, and review results from any machine.

!!! note "Runtime Foundation"

While CleverAgents leverages LangGraph and LangChain for the underlying LLM runtime primitives (tool calling, graphs, routing), its value lies in what it builds on top of these foundations.

!!! success "Core Capabilities"

- [x] A **first-class plan lifecycle** (Action templates driving Strategize / Execute / Apply phases) for breaking down and tracking complex work
- [x] A **project + resource model** for grounding tasks in real codebases, databases, documents, and infrastructure
- [x] A consistent **actor abstraction** for defining and composing intelligent agents
- [x] An independently registered **resource abstraction** for representing anything that can be read, written, or queried
- [x] An independently registered **tool abstraction** for reusable, callable operations with resource bindings
- [x] A **validation abstraction** that extends the tool concept with pass/fail semantics and resource-centric attachment with optional project/plan scoping
- [x] A consistent **skill abstraction** for organizing tools into composable capability collections
- [x] A **sandbox + checkpoint** safety model for safe, reversible execution
- [x] A **CLI/TUI/Web UX** for controlling and monitoring large multi-step autonomous work

!!! example "Advanced Subsystems"

- A scalable **Advanced Context Management System (ACMS)** with a Universal Knowledge Ontology (UKO), a demand-driven Context Request Protocol (CRP), pluggable context strategies, a fusion coordinator, and hot/warm/cold tiers with per-actor views.
- **Invariants** as first-class constraints (global, project, action, and plan scoped) that flow into the decision tree, with precedence-based conflict resolution via the Invariant Reconciliation Actor.
- A future-facing ==correction model== where the user can "edit the decision tree" and only recompute affected subtrees.

Standards Alignment

CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations.

!!! tip "Guiding Principles"

1. **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in.
2. **Keep adapters at the edge** — standards map into stable internal domain models so core logic remains protocol-agnostic.

The following standards are integrated into the architecture:

Standard	Role	Key Benefit
A2A (Agent-to-Agent Protocol)	Versioned client-server contract for messaging, task lifecycle, plan management, registry access, and event streaming	Clients are interchangeable; Agent Card discovery enables ecosystem interoperability; reliable remote execution in server mode
MCP (Model Context Protocol)	Discovering and invoking external tools over a server boundary	Plug-and-play access to a growing ecosystem of tool providers
LSP (Language Server Protocol)	Attaching language intelligence (diagnostics, type info, symbol navigation, completions) to actors and agents	Actors gain semantic code understanding from the mature LSP ecosystem without bespoke language analysis
Agent Skills (AgentSkills.io)	Packaging instruction-driven, multi-step workflows as SKILL.md with progressive disclosure	Teaches agents how to accomplish complex tasks, complementing MCP tools

??? info "Agent-to-Agent Protocol (A2A) -- Details"

CleverAgents adopts the external **Agent-to-Agent (A2A) Protocol** standard ([a2a-protocol.org](https://a2a-protocol.org)) as the **sole** communication protocol for all client-server interaction. A2A is the successor to the Agent Client Protocol (ACP), which is now deprecated; A2A retains backward compatibility with ACP's JSON-RPC 2.0 foundation. A2A is built on **JSON-RPC 2.0** (with additional gRPC and REST bindings available) and defines the **fundamental boundary between the Presentation and Application layers** — every client operation flows through A2A regardless of deployment mode. The standard provides operations for messaging (`message/send`, `message/stream`), task lifecycle management, streaming updates via SSE, and **Agent Card**-based capability discovery. CleverAgents extends the standard with `_cleveragents/`-prefixed extension methods (declared via the A2A extension mechanism) for platform operations: plan lifecycle, registry CRUD, entity sync, namespace management, and diagnostics. In local mode, A2A flows over **stdio** via the JSON-RPC binding (agent as subprocess) with platform operations resolved in-process via `A2aLocalFacade`. In server mode, A2A flows over **HTTP** to the CleverAgents server. Both transports use the A2A Python SDK. All clients — CLI, TUI, IDE plugin, and third-party — communicate exclusively through A2A. See [ADR-047](adr/ADR-047-acp-standard-adoption.md), [ADR-048](adr/ADR-048-server-application-architecture.md), and [Server and Client Architecture](#server-and-client-architecture) for the full detail.

??? info "Model Context Protocol (MCP) -- Details"

The standard for discovering and invoking external tools over a server boundary. MCP servers are bridged into the Tool Registry via adapters, giving CleverAgents plug-and-play access to a growing ecosystem of tool providers.

??? info "Language Server Protocol (LSP) -- Details"

The standard for attaching language intelligence to actors and agents. LSP servers are registered in a global LSP Registry (namespaced like all other entities) and bound to actor graph nodes via YAML configuration. When an actor activates, the LSP Runtime starts the appropriate language servers for the actor's bound languages and workspace resources. LSP capabilities — diagnostics, type information, symbol navigation, completions, references, rename, code actions, and more — are exposed to the actor as callable tools (via the `LSPToolAdapter`) and as automatic context enrichment (diagnostics and type annotations injected into the ACMS hot context). Actors can bind LSP servers explicitly by name, by language, or automatically based on the languages detected in their project's resources. Different nodes in an actor's graph can have different LSP bindings, enabling fine-grained control over which agents receive which language intelligence capabilities. See [LSP Integration](#lsp-integration) for the full architectural detail and [ADR-027](adr/ADR-027-language-server-protocol.md) for the decision record.

??? info "Agent Skills (AgentSkills.io) -- Details"

The standard for packaging instruction-driven, multi-step workflows as `SKILL.md` with progressive disclosure. Agent Skills complement MCP tools by teaching agents *how* to accomplish complex tasks rather than simply exposing callable functions.

Specification Sections

This specification is organized into the following sections:

Section	Description
Glossary	All glossary entries (Plan, Action, Resource, Actor, Tool, Skill, Session, etc.)
CLI Commands	Complete CLI command reference for all agents * commands
Core Concepts	Plan lifecycle, actors, tools, skills, sessions, resources, context, output rendering
Behavior	Automation profiles, guardrails, plan corrections, human-in-the-loop
TUI	Text User Interface architecture, persona system, reference/command system, widgets
Configuration	Configuration system, global config keys, environment variables
Workflow Examples	End-to-end workflow examples and integration patterns
Architecture	Layered architecture, domain models, data validation, storage, persistence

---