Compare commits
2 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 brent.edwards
|
11c246b7c0 | ||
 freemo
|
740e08b2a4
|
@@ -123,6 +123,8 @@ Agent behavior is configurable without code changes: prompt templates, tool sets
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools serve as atomic execution nodes within actor graphs |
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills provide the tool collections that actors are equipped with |
|
||||
| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | Actors are implemented as LangGraph StateGraph instances |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Skills are the unit of capability assignment to actors |
|
||||
| [ADR-031](ADR-031-actor-abstraction-definition.md) | Actor Abstraction Definition | Formalizes the canonical definition of what an actor is |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -149,6 +149,9 @@ None — specification-driven requirement. The tool system with its four-stage l
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills compose tools into reusable collections for actor assignment |
|
||||
| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validations are a specialized Tool subtype with structured pass/fail semantics |
|
||||
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Tool invocations create checkpoints for rollback and recovery |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills are a tool source (`agent_skill`) integrated into the Tool Registry |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools are registered as Tool records and follow the four-stage tool lifecycle |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Tools are the atomic operations that skills collect and present to actors |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -121,6 +121,9 @@ Actors specify a `skill_access_policy` that controls which skills they can use.
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Skills are assigned to actors to provide their tool capabilities |
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Skills compose tools into reusable, hierarchical collections |
|
||||
| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validation tools can be included in skills alongside regular tools |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills are composed and exposed through the skill system |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools are exposed through skills for actor access |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Formalizes the canonical definition of what a skill is |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -125,6 +125,8 @@ Plans can require checkpoints via the `require_checkpoints` flag. If enabled, on
|
||||
| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Sandboxes are created per-plan and destroyed on plan completion or reversion |
|
||||
| [ADR-008](ADR-008-resource-system.md) | Resource System | Sandbox strategy is determined by resource type (git_worktree, filesystem_copy, etc.) |
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tool invocations create checkpoints for granular rollback |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Sub-tool-calls within Agent Skill execution are individually checkpointed |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tool execution must respect sandbox boundaries via path rewriting |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -114,6 +114,7 @@ Plans are executed within sessions. A session may have multiple active plans (se
|
||||
| [ADR-006](ADR-006-plan-lifecycle.md) | Plan Lifecycle | Plans execute within sessions and inherit session-scoped context |
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Sessions bind a user to an orchestrator actor for conversation |
|
||||
| [ADR-014](ADR-014-context-management-acms.md) | Context Management (ACMS) | Sessions maintain session-scoped context tiers and conversation history |
|
||||
| [ADR-026](ADR-026-agent-client-protocol.md) | Agent Client Protocol (ACP) | ACP exposes session lifecycle operations to all clients |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -112,6 +112,8 @@ LangChain Community provides `FakeListLLM` and `FakeEmbeddings` for testing with
|
||||
| [ADR-003](ADR-003-dependency-injection.md) | Dependency Injection | LLM providers and LangGraph components are registered through the DI container |
|
||||
| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | LangChain and LangGraph are core stack choices for LLM orchestration |
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors are implemented as LangGraph StateGraph instances |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP SDK is part of the LLM runtime stack; MCPToolAdapter bridges MCP tools to LangGraph tool nodes |
|
||||
| [ADR-031](ADR-031-actor-abstraction-definition.md) | Actor Abstraction Definition | Actors are implemented as LangGraph StateGraph instances; LangGraph is the actor graph runtime |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -127,6 +127,7 @@ The key architectural enabler is the hexagonal pattern (ADR-001):
|
||||
| [ADR-002](ADR-002-namespace-system.md) | Namespace System | Server mode introduces server-prefixed namespaces for multi-server entity resolution |
|
||||
| [ADR-005](ADR-005-technical-stack.md) | Technical Stack | FastAPI, uvicorn, and Helm/Kubernetes are the server mode stack choices |
|
||||
| [ADR-019](ADR-019-storage-and-persistence.md) | Storage and Persistence | Server mode uses PostgreSQL instead of SQLite for multi-user persistence |
|
||||
| [ADR-026](ADR-026-agent-client-protocol.md) | Agent Client Protocol (ACP) | ACP is the client-server contract implemented by the REST API in server mode |
|
||||
|
||||
## Acceptance
|
||||
|
||||
|
||||
@@ -0,0 +1,146 @@
|
||||
# ADR-026: Agent Client Protocol (ACP)
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents is accessed through multiple presentation-layer clients — CLI, TUI, Web, and an IDE plugin — and can operate in both local (single-process) and server (multi-user HTTPS) modes. Without a shared, versioned contract between clients and the backend, each client would require bespoke integration code that drifts from the core domain model, making interoperability fragile and third-party client development impractical. The architecture needs a single protocol surface that all clients rely on regardless of deployment mode.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents adopts the **Agent Client Protocol (ACP)** as the versioned contract governing all client-to-backend communication. ACP defines canonical operations for sessions, plans, registries, context, and event streaming. In local mode ACP maps to in-process service facade calls; in server mode it is implemented by the REST API over HTTPS.
|
||||
|
||||
## Design
|
||||
|
||||
### Protocol Scope
|
||||
|
||||
ACP covers five operation groups:
|
||||
|
||||
| Group | Operations |
|
||||
|-------|-----------|
|
||||
| **Session lifecycle** | create, resume, list, show, delete, export, import, tell |
|
||||
| **Plan lifecycle** | use, execute, apply, cancel, status, tree, explain, correct, diff, artifacts, prompt, rollback |
|
||||
| **Registries** | list / show / add / update / remove for actors, skills, tools, validations, resources, resource types, projects, actions, automation profiles, invariants |
|
||||
| **Context operations** | context show, context inspect, context simulate, context set |
|
||||
| **Event streaming** | plan state changes, tool execution events, validation results, structured log events |
|
||||
|
||||
### Request / Response Envelope
|
||||
|
||||
Every ACP operation uses a canonical JSON envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"acp_version": "1.0",
|
||||
"request_id": "<ULID>",
|
||||
"operation": "plan.status",
|
||||
"params": { "plan_id": "01HXRCF1..." },
|
||||
"auth": { "token": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
Responses follow a matching envelope with `status`, `data`, and `error` fields. Error objects carry `code`, `message`, and optional `details`.
|
||||
|
||||
### Transport
|
||||
|
||||
- ACP is **transport-agnostic** at the specification level.
|
||||
- The default server implementation uses **HTTPS + JSON** via the FastAPI REST API.
|
||||
- Streaming updates use **Server-Sent Events (SSE)** in server mode with structured event payloads.
|
||||
- Local mode resolves operations to direct Python method calls on the Service Facade, bypassing serialization entirely.
|
||||
|
||||
### Versioning and Compatibility
|
||||
|
||||
- Each client advertises `acp_version` during connection.
|
||||
- Servers must support the current minor version plus one prior minor version.
|
||||
- Backward-compatible additions (new optional fields, new operations) are permitted within a major version; breaking changes require a major version bump.
|
||||
|
||||
### Authentication and Authorization
|
||||
|
||||
- **Server mode**: Token-based authentication (`server.token`) required for all ACP requests. Authorization is enforced per namespace.
|
||||
- **Local mode**: Authentication is bypassed but the ACP operation surface remains identical.
|
||||
|
||||
### Service Facade Mapping
|
||||
|
||||
Each ACP operation group maps to an Application-layer service:
|
||||
|
||||
| ACP Group | Service |
|
||||
|-----------|---------|
|
||||
| Session | `SessionWorkflow` |
|
||||
| Plan | `PlanService`, `PlanLifecycle`, `CorrectionFlow` |
|
||||
| Registries | `ActorService`, `ToolService`, `SkillService`, `ResourceService`, `ProjectService` |
|
||||
| Context | `ContextService` |
|
||||
| Events | `EventEmitter` (via SSE or in-process subscription) |
|
||||
|
||||
## Constraints
|
||||
|
||||
- Clients must not bypass ACP to access storage, repositories, or internal domain services directly.
|
||||
- All ACP operations must be implementable in both local and server modes with identical semantics.
|
||||
- All ACP operations in server mode must require valid authentication.
|
||||
- ACP responses must use the canonical JSON envelope; ad-hoc response shapes are prohibited.
|
||||
- Event streaming must preserve causal ordering within a single plan lifecycle.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Clients are interchangeable — new clients (e.g., mobile, third-party dashboards) can be built against the same stable contract.
|
||||
- Local and server modes share the same operational surface, eliminating behavioral drift.
|
||||
- Versioning guarantees backward compatibility for at least one prior minor version.
|
||||
|
||||
### Negative
|
||||
- The protocol adds upfront design and versioning overhead.
|
||||
- Some client-specific optimizations (e.g., batching, caching) are harder when constrained to a shared contract.
|
||||
|
||||
### Risks
|
||||
- Protocol evolution could lag feature development if versioning discipline is not maintained.
|
||||
- SSE streaming channels may become a bottleneck for plans with very high event throughput.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Per-client bespoke APIs** — Faster initial development but leads to drift, duplicated logic, and higher long-term maintenance costs. Rejected.
|
||||
|
||||
**Direct database access for local clients** — Faster reads in local mode but breaks parity with server mode and tightly couples clients to storage schema. Rejected.
|
||||
|
||||
**gRPC** — Strong typing and streaming but adds a code-generation dependency and is less accessible for browser-based clients than JSON over HTTPS. May be revisited for high-throughput server-to-server communication.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **Contract tests**: Validate all ACP endpoints against the canonical schema for every supported version.
|
||||
- **Local/server parity tests**: Execute the same ACP test suite in both deployment modes and assert identical results.
|
||||
- **Authentication tests**: Verify token enforcement and namespace authorization in server mode.
|
||||
- **Streaming tests**: Ensure event ordering and schema compliance for SSE event payloads.
|
||||
- **Bypass detection**: Architecture tests verify that no Presentation-layer module imports from the Infrastructure layer directly.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | ACP sits at the Presentation-Application boundary defined by the layered architecture |
|
||||
| [ADR-020](ADR-020-session-model.md) | Session Model | ACP defines the session lifecycle operations exposed to clients |
|
||||
| [ADR-023](ADR-023-server-mode.md) | Server Mode | ACP is the client-server contract for remote execution in server mode |
|
||||
| [ADR-027](ADR-027-language-server-protocol.md) | Language Server Protocol (LSP) Integration | The LSP server communicates with the backend exclusively through ACP |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
@@ -0,0 +1,125 @@
|
||||
# ADR-027: Language Server Protocol (LSP) Integration
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents needs deep IDE integration for plan-aware workflows: validation feedback displayed inline, context exploration on hover, and code actions that trigger plan operations. Building bespoke plugins for each editor (VS Code, JetBrains, Neovim, Emacs, etc.) would be expensive and prone to divergence. The architecture requires a single, standard, editor-agnostic interface that connects to the CleverAgents backend and behaves identically across local and server modes.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents implements the IDE plugin as a **Language Server Protocol (LSP)** server. The LSP server surfaces plan-aware code actions, diagnostics, and context lookups, and communicates with the backend exclusively through ACP (ADR-026).
|
||||
|
||||
## Design
|
||||
|
||||
### LSP Server Role
|
||||
|
||||
The LSP server is a Presentation-layer adapter. It translates LSP requests into ACP calls and maps ACP responses back to LSP messages.
|
||||
|
||||
```
|
||||
Editor ←— LSP JSON-RPC —→ LSP Server ←— ACP —→ Service Facade
|
||||
```
|
||||
|
||||
### Feature Mapping
|
||||
|
||||
| LSP Feature | CleverAgents Source | ACP Operation |
|
||||
|-------------|--------------------|--------------|
|
||||
| **Diagnostics** | Validation results (required + informational) | `validation.list_results` |
|
||||
| **Code actions** | Run validation, propose fix, apply plan, cancel plan | `plan.execute`, `plan.apply`, `validation.run` |
|
||||
| **Hover** | Context snippets, decision provenance, UKO entity summaries | `context.inspect` |
|
||||
| **Workspace symbols** | Registered resources, active plans, attached validations | `resource.list`, `plan.list` |
|
||||
|
||||
### Workspace and Resource Resolution
|
||||
|
||||
- LSP workspace roots are matched to registered resource paths in the Resource Registry.
|
||||
- File URI paths are resolved through the Resource Registry so that sandbox-resident files map correctly to their logical resources.
|
||||
- If a workspace root does not correspond to a registered resource, plan-aware features degrade gracefully (standard editing still works).
|
||||
|
||||
### Diagnostic Severity Mapping
|
||||
|
||||
| Validation Mode | LSP Severity |
|
||||
|----------------|-------------|
|
||||
| `required` — failed | `Error` |
|
||||
| `required` — passed | (suppressed) |
|
||||
| `informational` — failed | `Warning` |
|
||||
| `informational` — passed | `Hint` |
|
||||
|
||||
### Lifecycle
|
||||
|
||||
The LSP server is a long-lived process launched by the editor. It:
|
||||
|
||||
1. Initializes an ACP client (in-process for local mode, HTTPS for server mode).
|
||||
2. Subscribes to plan and validation events via ACP streaming.
|
||||
3. Pushes diagnostics to the editor as events arrive.
|
||||
4. Handles editor-initiated requests (code actions, hover, completion) synchronously via ACP.
|
||||
|
||||
## Constraints
|
||||
|
||||
- The LSP server must not access storage, database, or domain services directly — all operations go through ACP.
|
||||
- IDE features must remain strictly editor-agnostic; no editor-specific APIs outside the LSP specification.
|
||||
- LSP diagnostics must reflect validation results without modifying any resources (read-only at the presentation boundary).
|
||||
- The LSP server must function in both local mode (in-process ACP) and server mode (remote ACP over HTTPS).
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- One integration serves all LSP-compatible editors (VS Code, JetBrains via LSP bridge, Neovim, Emacs, Helix, etc.).
|
||||
- IDE features stay exactly aligned with CLI/TUI/Web behavior because they share the same ACP contract.
|
||||
- Reduced maintenance burden compared to N bespoke editor plugins.
|
||||
- Diagnostics arrive in real-time via ACP event streaming, keeping editors up to date during long-running plan execution.
|
||||
|
||||
### Negative
|
||||
- LSP's fixed feature set may limit richer custom UI experiences that specific editors could offer (e.g., custom webview panels in VS Code).
|
||||
- ACP round-trips add latency to interactive IDE operations compared to direct in-process access.
|
||||
|
||||
### Risks
|
||||
- Future LSP specification changes could require compatibility work in the server.
|
||||
- High-frequency IDE events (typing, hover) could place excessive load on ACP endpoints if not debounced.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Editor-specific plugins** — More tailored UX per editor but requires separate implementations and ongoing maintenance for each editor. Rejected as the primary strategy (may be revisited for value-add features on top of the LSP baseline).
|
||||
|
||||
**Custom IDE protocol** — Maximum flexibility but zero ecosystem adoption, higher learning curve for contributors, and no editor-side library support. Rejected.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **LSP conformance tests**: Validate request/response message formats and declared capabilities against the LSP specification.
|
||||
- **ACP integration tests**: Verify that every LSP feature correctly maps to the corresponding ACP operation and produces the expected editor-visible result.
|
||||
- **Diagnostics tests**: Ensure validation results translate to LSP diagnostics with the correct severity mapping and no resource side effects.
|
||||
- **Degradation tests**: Verify graceful fallback when workspace roots do not map to registered resources.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-001](ADR-001-layered-architecture.md) | Layered Architecture | The LSP server is a Presentation-layer adapter |
|
||||
| [ADR-013](ADR-013-validation-abstraction.md) | Validation Abstraction | Validation results are the primary source for LSP diagnostics |
|
||||
| [ADR-026](ADR-026-agent-client-protocol.md) | Agent Client Protocol (ACP) | The LSP server communicates with the backend exclusively through ACP |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
@@ -0,0 +1,139 @@
|
||||
# ADR-028: Agent Skills Standard (AgentSkills.io)
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents needs a portable way to package instruction-driven workflows that go beyond single tool calls. An agent following a deployment checklist, for example, must orchestrate multiple MCP tools, make decisions based on intermediate results, and follow domain-specific best practices — something a single schema-driven tool call cannot express. These workflows should be shareable across teams, compatible with different agent runtimes, and efficient to load (only paying token cost when actually used). A standard format reduces fragmentation and enables a broader ecosystem of reusable skills.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents adopts the **Agent Skills standard** from [https://AgentSkills.io](https://AgentSkills.io). Skills are authored as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, and are ingested as a tool source (`agent_skill`) with progressive disclosure.
|
||||
|
||||
## Design
|
||||
|
||||
### Discovery and Registration
|
||||
|
||||
- Skill folders are discovered via paths configured in skill YAML (`agent_skills` section).
|
||||
- `SKILL.md` frontmatter provides metadata: name, description, tags.
|
||||
- Each Agent Skill is registered as a tool record with source `agent_skill` in the Tool Registry.
|
||||
- Name collisions with existing tools or validations are rejected at registration time.
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
| Tier | What loads | When | Token cost |
|
||||
|------|-----------|------|------------|
|
||||
| **Metadata** | `name` + `description` from SKILL.md frontmatter | Tool registration / actor activation | ~50–100 tokens per skill |
|
||||
| **Instructions** | Full SKILL.md Markdown body | When the LLM determines the task matches (activate phase) | Recommended < 5,000 tokens |
|
||||
| **Resources** | `scripts/`, `references/`, `assets/` | On demand during execution | Variable |
|
||||
|
||||
This three-tier model means an actor can have dozens of Agent Skills available while only paying the metadata token cost at startup. Full instructions load only when relevant.
|
||||
|
||||
### Execution Model
|
||||
|
||||
- Agent Skills are **instruction-driven**: the LLM actor reads the SKILL.md instructions and follows the prescribed procedure.
|
||||
- During execution, the agent may invoke any other tool in its assigned skill set — MCP tools, built-in tools, or other Agent Skills.
|
||||
- Scripts provided with the skill are never auto-executed; they must be invoked via explicit tool calls (e.g., a `shell` or `python` tool).
|
||||
- Each sub-tool-call within the skill's execution is individually checkpointed, enabling fine-grained rollback.
|
||||
|
||||
### Actor Graph Integration
|
||||
|
||||
- Agent Skills are exposed through skill YAML and flattened into the actor's tool set during skill resolution.
|
||||
- Inside actor graphs, Agent Skills appear as **tool nodes** — identical in shape to MCP tool nodes or built-in tool nodes.
|
||||
- When the actor runtime activates an Agent Skill tool node, it loads the SKILL.md instructions into the LLM context and the agent follows the procedure.
|
||||
- A single Agent Skill tool node execution may generate multiple downstream tool calls (including calls to MCP tools), all tracked in the plan's change set.
|
||||
|
||||
### Composing MCP Tools and Agent Skills
|
||||
|
||||
A common and powerful pattern is an Agent Skill that teaches the agent a workflow involving multiple MCP tools:
|
||||
|
||||
```
|
||||
Agent Skill Tool: "local/deploy-staging"
|
||||
SKILL.md instructions:
|
||||
1. Run tests using the built-in shell tool
|
||||
2. Create a PR using the GitHub MCP tool (create_pull_request)
|
||||
3. Wait for CI using the GitHub MCP tool (get_check_runs)
|
||||
4. Deploy using the AWS MCP tool (ecs_update_service)
|
||||
5. Verify deployment using the HTTP MCP tool (fetch_url)
|
||||
```
|
||||
|
||||
This composition is a key design principle: Agent Skills extend the agent's *knowledge* (multi-step procedures, domain best practices), while MCP tools extend its *toolset* (callable functions). The two are complementary and coexist naturally within the same skill.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Skill discovery must be read-only and side-effect free.
|
||||
- Full instruction loading must follow progressive disclosure rules — SKILL.md body must not load until the activate phase.
|
||||
- Agent Skills must integrate with the Tool and Skill registries without name collisions.
|
||||
- Skill execution must respect sandbox and checkpoint policies for all tool calls made during the procedure.
|
||||
- Scripts bundled with a skill must never be auto-executed.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Portable, reusable workflows with minimal vendor lock-in — any AgentSkills.io-compatible runtime can consume the same SKILL.md files.
|
||||
- Reduced prompt duplication through standardized packaging.
|
||||
- Efficient context usage through progressive disclosure (metadata-only at startup).
|
||||
- Natural composition with MCP tools within actor graphs.
|
||||
|
||||
### Negative
|
||||
- Instruction-driven execution can be less deterministic than single-call schema-driven tools.
|
||||
- Debugging multi-step skill execution requires tracing through multiple tool calls, demanding stronger observability (ADR-025).
|
||||
|
||||
### Risks
|
||||
- Poorly authored SKILL.md files (verbose instructions, unclear procedures) could waste context budget or confuse the agent.
|
||||
- Over-reliance on instruction-driven skills could hide important decision points from the decision tree.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Proprietary skill format** — Faster to implement but locks users into a non-standard ecosystem and prevents sharing with the broader agent community. Rejected.
|
||||
|
||||
**Inline prompts only** — Simple but leads to prompt duplication, inconsistent practices across actors, and no progressive disclosure. Rejected.
|
||||
|
||||
**MCP-only tooling** — MCP tools are schema-driven and cannot express multi-step procedures with conditional logic. They are complementary, not a replacement. Rejected as a sole tool source.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **Discovery tests**: Verify that Agent Skills are discovered and registered without side effects.
|
||||
- **Progressive disclosure tests**: Ensure metadata, instructions, and resources load at the correct lifecycle stages and not earlier.
|
||||
- **Registry integration tests**: Validate naming, source tagging (`agent_skill`), and skill-tool composition behavior.
|
||||
- **Sandbox tests**: Confirm that all tool calls made during skill execution respect sandbox and checkpoint requirements.
|
||||
- **Actor graph tests**: Verify that Agent Skill tool nodes activate correctly in actor graphs, load instructions, and produce tracked change sets.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Agent Skills appear as tool nodes in actor graphs |
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Agent Skills are a tool source integrated into the Tool Registry |
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | Agent Skills are exposed and composed within skills |
|
||||
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | Sub-tool-calls within skill execution are individually checkpointed |
|
||||
| [ADR-025](ADR-025-observability-and-logging.md) | Observability and Logging | Multi-step skill execution requires structured tracing |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | Agent Skills commonly orchestrate MCP tools within workflows |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Agent Skills are one of the four tool sources unified under the skill abstraction |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
@@ -0,0 +1,159 @@
|
||||
# ADR-029: Model Context Protocol (MCP) Adoption
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents needs a standard way to discover and invoke external tools without building bespoke integrations for each service. The system also requires that externally hosted tools can be composed into skills and used as nodes in actor graphs while still honoring sandboxing, checkpointing, and change tracking. A vendor-neutral protocol is necessary to keep the tool ecosystem portable and extensible.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents adopts the **Model Context Protocol (MCP)** as the standard for discovering and invoking external tools. MCP servers are integrated through the `MCPToolAdapter`, which registers MCP tools into the Tool Registry with extended capability metadata, allowing them to be composed into skills and invoked within actor graphs using the same four-stage tool lifecycle as built-in tools.
|
||||
|
||||
## Design
|
||||
|
||||
### Tool Discovery and Mapping
|
||||
|
||||
1. MCP servers are declared in tool or skill YAML configuration with transport (`stdio`, `sse`, `streamable-http`), command/URL, and optional environment variables.
|
||||
2. During the **discover** phase the adapter spawns the server process (or connects to a remote endpoint), performs the MCP `initialize` handshake, negotiates capabilities, then calls `tools/list` to enumerate available tools.
|
||||
3. Each MCP tool becomes a separate `ToolDescriptor` record with source `mcp`, the server's JSON Schema `inputSchema`, and inferred capability metadata.
|
||||
|
||||
### Capability Inference and Override
|
||||
|
||||
MCP's native metadata is limited (name, description, inputSchema). CleverAgents infers extended capability metadata using heuristics:
|
||||
|
||||
- Tool names containing `create`, `write`, `delete`, `update` → `writes: true`
|
||||
- Tool names containing `get`, `list`, `read`, `search` → `read_only: true`
|
||||
- All others default to `writes: true` (conservative).
|
||||
|
||||
Inferred capabilities can be overridden in the tool or skill YAML configuration via an `overrides` block, ensuring safety constraints are explicit where heuristics are insufficient.
|
||||
|
||||
### MCP Tools as Skills
|
||||
|
||||
- Skills reference MCP servers in their `mcp_servers` section.
|
||||
- The Skill Registry flattens MCP-sourced tools alongside built-ins, custom tools, and Agent Skills.
|
||||
- MCP tools are available to any actor assigned a skill that includes them — no special treatment required.
|
||||
- Per-tool metadata overrides can be applied at the skill inclusion point.
|
||||
|
||||
### MCP Tools in Actor Graphs
|
||||
|
||||
- Actor graphs use tool nodes that resolve through the actor's assigned skills.
|
||||
- MCP tools appear as tool nodes identical in shape to built-in or Agent Skill tool nodes.
|
||||
- The actor runtime invokes MCP tools via the MCPToolAdapter's `execute()` method, which translates the call into an MCP `tools/call` JSON-RPC request.
|
||||
- Change tracking, checkpoint creation, and rollback apply identically to MCP tool nodes and built-in tool nodes.
|
||||
|
||||
### Sandbox Path Rewriting
|
||||
|
||||
MCP servers operate on real filesystem paths, but CleverAgents executes plans in sandboxes. The MCPToolAdapter transparently rewrites file paths in tool arguments:
|
||||
|
||||
- Logical path `src/main.py` → sandbox path `/tmp/sandbox-01HXM/worktree/src/main.py`
|
||||
- The MCP server operates on the sandboxed state without awareness of the sandbox model.
|
||||
- On return, paths in the result are rewritten back to logical paths for the plan's change set.
|
||||
|
||||
### Dynamic Tool Refresh
|
||||
|
||||
The adapter subscribes to `notifications/tools/list_changed` events. When an MCP server's tool list changes at runtime, the adapter re-enumerates available tools and updates the Tool Registry, ensuring skill resolution and actor graphs always reflect the current tool surface.
|
||||
|
||||
### Server Lifecycle Management
|
||||
|
||||
```
|
||||
Phase 1 — Registration:
|
||||
CLI → Registry: agents tool add / skill add
|
||||
Registry validates server command or endpoint, stores config.
|
||||
|
||||
Phase 2 — Actor Activation:
|
||||
Actor Runtime → Adapter: activate (for each MCP server)
|
||||
Adapter spawns process (stdio) or connects (HTTP)
|
||||
Adapter performs MCP initialize handshake, tools/list, subscribes to notifications.
|
||||
|
||||
Phase 3 — Execution:
|
||||
Actor Runtime → Adapter: tool call
|
||||
Adapter → MCP Server: tools/call (JSON-RPC)
|
||||
MCP Server → Adapter: result
|
||||
Adapter → Actor Runtime: result + change tracking
|
||||
|
||||
Phase 4 — Deactivation:
|
||||
Actor Runtime → Adapter: deactivate
|
||||
Adapter sends clean shutdown to MCP server, closes connection.
|
||||
```
|
||||
|
||||
## Constraints
|
||||
|
||||
- MCP tools must only be invoked via the MCPToolAdapter — direct JSON-RPC calls from domain code are prohibited.
|
||||
- MCP tool execution must respect sandbox boundaries through argument path rewriting.
|
||||
- MCP tool records must be refreshable at runtime when `notifications/tools/list_changed` events are received.
|
||||
- Capability metadata must be either correctly inferred or explicitly overridden; the conservative default is `writes: true`.
|
||||
- MCP server processes spawned by the adapter must be cleanly shut down during actor deactivation.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- Standardized tool integration with a growing ecosystem of MCP servers (GitHub, Linear, AWS, databases, etc.).
|
||||
- MCP tools are immediately usable in skills and actor graphs without custom glue code.
|
||||
- External tooling can be swapped or upgraded without changing core domain logic.
|
||||
- Sandbox path rewriting ensures MCP tools operate safely within plan boundaries.
|
||||
|
||||
### Negative
|
||||
- MCP tools expose limited capability metadata, requiring inference heuristics and manual overrides.
|
||||
- External server availability and latency directly affect plan execution speed.
|
||||
- The adapter adds a serialization/deserialization layer for every tool call.
|
||||
|
||||
### Risks
|
||||
- Misclassified tool capabilities (e.g., a write tool inferred as read-only) could lead to unsafe executions if not overridden.
|
||||
- MCP server outages could block plan execution or degrade skill availability.
|
||||
- Long-running MCP server processes could leak resources if deactivation is not handled cleanly.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Custom tool RPC protocol** — Greater control over metadata and lifecycle but increases integration burden for every new tool provider and forfeits MCP ecosystem interoperability. Rejected.
|
||||
|
||||
**Direct SDK integrations** — Simplifies single-tool integrations (e.g., GitHub SDK, AWS SDK) but scales poorly, fragments the tool ecosystem, and bypasses the uniform tool lifecycle. Rejected as a primary strategy (may be used for performance-critical built-ins).
|
||||
|
||||
**Agent Skills only (no schema-driven tools)** — Instruction-driven skills are powerful but cannot replace low-latency, deterministic schema-driven tool calls for atomic operations. MCP and Agent Skills are complementary. Rejected as a sole tool source.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **Handshake tests**: Verify MCP initialization, capability negotiation, and tool listing for both stdio and HTTP transports.
|
||||
- **Tool registry tests**: Ensure MCP tools are registered with correct schemas, source tags, and inferred/overridden capability metadata.
|
||||
- **Skill exposure tests**: Validate that MCP tools appear in flattened skill tool sets and can be invoked by actors.
|
||||
- **Sandbox rewrite tests**: Confirm path rewriting for filesystem-based MCP tools in both directions (request and response).
|
||||
- **Notification tests**: Verify tool list refresh on `notifications/tools/list_changed` events with correct registry updates.
|
||||
- **Lifecycle tests**: Verify clean startup and shutdown of MCP server processes across actor activation/deactivation cycles.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | MCP tools are registered as Tool records and follow the four-stage tool lifecycle |
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | MCP tools are exposed through skills for actor assignment |
|
||||
| [ADR-015](ADR-015-sandbox-and-checkpoint.md) | Sandbox and Checkpoint | MCP tool execution must respect sandbox boundaries and checkpoint rules |
|
||||
| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | MCP SDK is part of the LLM runtime stack; MCPToolAdapter bridges to LangGraph tool nodes |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills commonly orchestrate MCP tools within multi-step workflows |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | MCP tools are one of the four tool sources unified under the skill abstraction |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
@@ -0,0 +1,173 @@
|
||||
# ADR-030: Skill Abstraction Definition
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents integrates tools from four heterogeneous sources — MCP servers, Agent Skills (AgentSkills.io) folders, built-in tool groups, and custom Python implementations. Without a unifying abstraction, actors would need to understand each source's discovery mechanism, lifecycle, and metadata format individually. The system needs a single, well-defined concept that bridges the gap between individual tools (which are atomic, independently registered operations) and actors (which need coherent bundles of capabilities to perform their roles). The term "skill" is used throughout the specification, CLI, and configuration but its precise definition — what it is, what it is not, and how it relates to the four tool sources — must be formalized as an architectural commitment.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents defines a **skill** as a **composable, namespaced collection of tools** that serves as the unit of capability assignment to actors. A skill is not a tool; it is a container that assembles tools from any combination of the four supported sources into a coherent, reusable bundle. Actors never reference individual tools directly for capability assignment — they reference skills, and through skills gain access to a flattened set of tools.
|
||||
|
||||
## Design
|
||||
|
||||
### Canonical Definition
|
||||
|
||||
A **skill** is a YAML-configured, namespaced entity registered in the Skill Registry that:
|
||||
|
||||
1. **Aggregates tools from four sources** into a single collection:
|
||||
|
||||
| Source | How Referenced in Skill YAML | Discovery Mechanism |
|
||||
|--------|----------------------------|---------------------|
|
||||
| **Built-in tool groups** | `builtin_groups:` section | Pre-registered by the runtime |
|
||||
| **Custom Python tools** | `tools:` section (named references or inline anonymous tools) | Tool Registry lookup or inline definition |
|
||||
| **MCP server tools** | `mcp_servers:` section | MCPToolAdapter `discover()` via JSON-RPC `tools/list` |
|
||||
| **Agent Skills folders** | `agent_skill_folders:` section | AgentSkillAdapter `discover()` via SKILL.md parsing |
|
||||
|
||||
2. **Produces a flattened tool set** — when resolved, a skill yields a flat list of `ToolRecord` entries regardless of their original source. All tools in the set share the same four-stage lifecycle (`discover`, `activate`, `execute`, `deactivate`) and are indistinguishable to the actor runtime.
|
||||
|
||||
3. **Is the unit of capability assignment** — actors reference skills by fully-qualified namespaced name in their `skills:` list. The actor's graph gains access to the union of all tools from all referenced skills.
|
||||
|
||||
### What a Skill Is Not
|
||||
|
||||
| Skill is... | Skill is not... |
|
||||
|-------------|----------------|
|
||||
| A **container** of tools | A single executable operation |
|
||||
| **Named and registered** in the Skill Registry | An anonymous or inline concept |
|
||||
| **Defined in its own YAML file** | Defined inline in an actor configuration |
|
||||
| **Source-agnostic** after flattening | Tied to a specific tool source |
|
||||
| The **assignment unit** for actors | Directly callable by end users |
|
||||
|
||||
A skill never executes — tools execute. A skill organizes, composes, and presents tools to actors as a coherent capability surface.
|
||||
|
||||
### Tool Source Unification
|
||||
|
||||
The skill abstraction is the architectural seam where four distinct tool ecosystems converge into a uniform interface:
|
||||
|
||||
- **MCP tools** (schema-driven, low-latency, deterministic) enter through `mcp_servers:` and are individually registered with inferred or overridden capability metadata.
|
||||
- **Agent Skills** (instruction-driven, multi-step, knowledge-rich) enter through `agent_skill_folders:` and appear as tool records whose execution loads SKILL.md instructions into the LLM context.
|
||||
- **Built-in tools** (bundled with the runtime) enter through `builtin_groups:` and require no external process.
|
||||
- **Custom tools** (user-authored Python) enter through `tools:` either as named references to registered tools or as anonymous inline definitions.
|
||||
|
||||
After flattening, the actor runtime does not distinguish between these sources. A tool node in an actor graph referencing a skill-provided tool behaves identically whether the underlying source is MCP, Agent Skills, built-in, or custom.
|
||||
|
||||
### Hierarchical Composition
|
||||
|
||||
Skills compose hierarchically through the `includes:` mechanism:
|
||||
|
||||
```
|
||||
Skill: local/full-stack-ops
|
||||
includes:
|
||||
- local/file-ops (5 tools)
|
||||
- local/git-ops (3 tools)
|
||||
- local/github (8 MCP tools)
|
||||
tools:
|
||||
- local/run-migrations (1 custom tool)
|
||||
agent_skill_folders:
|
||||
- deploy-to-staging (1 Agent Skill)
|
||||
─────────────
|
||||
18 tools total (flattened)
|
||||
```
|
||||
|
||||
When a child skill is included, all of its tools (including those from its own includes) are merged into the parent's flattened set. Per-tool metadata overrides can be applied at the inclusion point to adjust capability flags (e.g., marking a tool as `human_approval_required` in a specific skill context).
|
||||
|
||||
### Skill Registry
|
||||
|
||||
The Skill Registry is the persistent catalog that stores all registered skills and their resolved tool sets. Key operations:
|
||||
|
||||
- **Register**: Parse skill YAML, resolve all tool references and includes, store the `SkillRecord` with its flattened tool list.
|
||||
- **Resolve**: Given a skill name, return the complete flattened tool set (used during actor activation).
|
||||
- **Validate**: Ensure all referenced tools exist in the Tool Registry, all included skills are registered, and no circular includes exist.
|
||||
- **Refresh**: When a tool's metadata changes (e.g., MCP tool list refresh), update all skills that include that tool.
|
||||
|
||||
### Actor Binding
|
||||
|
||||
When an actor is activated, the runtime:
|
||||
|
||||
1. Reads the actor's `skills:` list.
|
||||
2. Resolves each skill name through the Skill Registry.
|
||||
3. Merges all flattened tool sets into the actor's available tool surface.
|
||||
4. Makes these tools available both for LLM tool-calling and as named tool nodes in the actor's graph.
|
||||
|
||||
This binding is the only path through which actors acquire tool capabilities. There is no mechanism for an actor to reference a tool without going through a skill.
|
||||
|
||||
## Constraints
|
||||
|
||||
- A skill must be defined in its own YAML configuration file — inline skill definitions in actor YAML are not permitted.
|
||||
- A skill's flattened tool set must contain only valid, registered tools (or valid inline anonymous tool definitions).
|
||||
- Circular skill includes are prohibited and must be detected at registration time.
|
||||
- All four tool sources must produce `ToolRecord` entries with the same interface — source-specific behavior is encapsulated in the respective adapter.
|
||||
- Actors must reference skills by fully-qualified namespaced name; glob patterns or wildcards are not supported in skill references.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- A single abstraction unifies four heterogeneous tool ecosystems, eliminating source-specific logic in actor and graph code.
|
||||
- Hierarchical composition enables DRY skill definitions — common tool bundles are defined once and included everywhere.
|
||||
- The strict skill-as-container / tool-as-operation distinction prevents conceptual confusion in configuration and documentation.
|
||||
- Actors gain capabilities declaratively through skill references, making actor configurations readable and auditable.
|
||||
- New tool sources can be added in the future without changing the skill abstraction or actor binding model.
|
||||
|
||||
### Negative
|
||||
- An extra layer of indirection (skill) sits between actors and tools, requiring configuration even for simple single-tool use cases.
|
||||
- Flattening large skill hierarchies with many MCP servers could have non-trivial startup cost during actor activation.
|
||||
- Tool name collisions across included skills must be resolved via fully-qualified names, adding configuration verbosity.
|
||||
|
||||
### Risks
|
||||
- If the skill abstraction is bypassed (e.g., actors directly referencing tools outside skills), the uniform capability model breaks down.
|
||||
- Overly deep skill inclusion hierarchies could become difficult to reason about and debug.
|
||||
- Stale skill registrations (referencing removed tools or unreachable MCP servers) could cause silent capability degradation at actor activation time.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Direct tool assignment to actors** — Actors reference individual tools by name instead of skills. Simpler for trivial cases but scales poorly (actors with 20+ tools become unwieldy), eliminates reuse (common tool sets duplicated across actors), and loses the organizational abstraction that makes configurations readable. Rejected.
|
||||
|
||||
**Implicit skill creation from tool groups** — Automatically create a skill for each tool source (one skill per MCP server, one per built-in group, etc.). Removes user control over composition, prevents cross-source bundling, and makes the abstraction invisible rather than explicit. Rejected.
|
||||
|
||||
**Skills as executable workflows** — Define skills as multi-step procedures rather than tool collections. Conflates skills with Agent Skills (which are instruction-driven workflows) and with actor graphs (which are the execution model). The current design correctly separates organization (skills) from execution (tools) from orchestration (actors/graphs). Rejected.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **Skill YAML validation tests**: Verify that skill configurations correctly parse all four tool source sections and produce valid flattened tool sets.
|
||||
- **Flattening tests**: Ensure hierarchical skill includes correctly merge tools, apply overrides, and detect circular references.
|
||||
- **Actor binding tests**: Verify that actor activation resolves all skill references and produces the correct merged tool surface.
|
||||
- **Source uniformity tests**: Confirm that tools from all four sources are indistinguishable after flattening (same `ToolRecord` interface, same lifecycle).
|
||||
- **Registry consistency tests**: Validate that skill registration fails gracefully when referenced tools or included skills do not exist.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Actors reference skills to acquire tool capabilities; skills are the binding mechanism |
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools are the atomic operations that skills collect and present to actors |
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | Implements the skill abstraction: composition, inclusion, registry, and flattening |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills are one of the four tool sources unified under the skill abstraction |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools are one of the four tool sources unified under the skill abstraction |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
@@ -0,0 +1,204 @@
|
||||
# ADR-031: Actor Abstraction Definition
|
||||
|
||||
**Status:** Proposed
|
||||
**Date:** 2026-02-17
|
||||
**Supersedes:** None
|
||||
**Author(s):** CleverAgents Team
|
||||
**Approver(s):**
|
||||
|
||||
## Context
|
||||
|
||||
CleverAgents needs a single abstraction that covers everything from a simple LLM wrapper answering questions to a complex multi-stage pipeline orchestrating dozens of sub-agents and tool calls. The system must support hierarchical composition (graphs containing graphs), role specialization (strategy, execution, estimation, invariant), and uniform treatment of all conversational participants. Without a formal definition of what an "actor" is, the boundary between actors, agents, graphs, and workflows becomes ambiguous — leading to inconsistent configuration, unclear composition rules, and conceptual fragmentation in both documentation and implementation. This ADR formalizes the actor abstraction as an architectural commitment.
|
||||
|
||||
## Decision
|
||||
|
||||
CleverAgents defines an **actor** as a **YAML-configured conversational unit** that generalizes "agent" into "anything conversational." An actor can represent a single LLM node, a composed graph of actors and tool nodes, or any text-in/text-out system. Every custom actor is implemented as a graph (a LangGraph StateGraph), and graphs can compose and contain other actors — enabling hierarchical orchestration without a separate composition model.
|
||||
|
||||
## Design
|
||||
|
||||
### Canonical Definition
|
||||
|
||||
An **actor** is:
|
||||
|
||||
1. **Anything conversational** — the abstraction that generalizes "agent" into the broadest useful category. If it accepts text input and produces text output, it can be an actor.
|
||||
|
||||
2. **A YAML-configured graph** — every custom actor is technically a LangGraph StateGraph defined via YAML configuration. Even a simple actor wrapping a single LLM is a graph with one node.
|
||||
|
||||
3. **Composable and hierarchical** — an actor's graph can include nodes that reference other actors by name, and those actors are themselves graphs that may reference further actors. This enables "orchestrator of orchestrators" patterns with no depth limit.
|
||||
|
||||
4. **The unit of conversation** in CleverAgents — sessions are tied to actors, context is scoped to actors, and all plan phase transitions are driven by actors.
|
||||
|
||||
### What an Actor Can Represent
|
||||
|
||||
| Scale | Example | Graph Shape |
|
||||
|-------|---------|-------------|
|
||||
| **Single LLM node** | `openai/gpt-4` answering questions | One-node graph: LLM agent with skills |
|
||||
| **Simple agent** | `local/code-reviewer` with tools | One-node graph: LLM + tool-calling loop |
|
||||
| **Linear pipeline** | Analyze -> Implement -> Test | Multi-node graph: sequential actor and tool nodes |
|
||||
| **Branching workflow** | Triage -> (Security / Performance / Style) -> Merge | Multi-node graph: conditional routing to sub-actors |
|
||||
| **Orchestrator of orchestrators** | Strategy actor delegates to execution actors, each a graph | Nested graphs: top-level actor's nodes are themselves actors with their own graphs |
|
||||
| **External system wrapper** | Third-party API with conversational interface | One-node graph: adapter translating text-in/text-out to API calls |
|
||||
|
||||
### The Actor-as-Graph Principle
|
||||
|
||||
Every custom actor IS a graph. This is not a metaphor — it is the implementation model:
|
||||
|
||||
- A "simple" actor wrapping a single LLM is a graph with one agent node, zero or more tool nodes, and edges connecting them.
|
||||
- A "composite" actor orchestrating multiple sub-agents is a graph whose nodes include references to other actors (which are themselves graphs).
|
||||
- There is no separate "workflow" or "pipeline" abstraction — actors and graphs are the same thing.
|
||||
|
||||
This unification eliminates the need for separate concepts for "agent," "workflow," "pipeline," and "orchestrator." All are actors; they differ only in graph complexity.
|
||||
|
||||
### Hierarchical Composition
|
||||
|
||||
Actors compose through named references in graph node definitions:
|
||||
|
||||
```
|
||||
Actor: local/review-pipeline (graph)
|
||||
nodes:
|
||||
- orchestrator (agent: local/review-controller)
|
||||
- security (agent: local/security-reviewer) <- itself a graph
|
||||
- performance (agent: local/perf-reviewer) <- itself a graph
|
||||
- style (agent: local/style-reviewer) <- itself a graph
|
||||
- merge_results (tool: local/merge-reviews)
|
||||
|
||||
Each sub-actor (security, performance, style) is independently
|
||||
defined, registered, and testable. The parent actor references
|
||||
them by name — it does not inline their definitions.
|
||||
```
|
||||
|
||||
Key composition rules:
|
||||
|
||||
- **Named references only**: Actor A references Actor B by its fully-qualified namespaced name (`local/security-reviewer`), never by inlining B's definition.
|
||||
- **Load order matters**: Referenced actors must be loaded/defined before actors that depend on them.
|
||||
- **No depth limit**: Actor A -> Actor B -> Actor C -> ... is valid and supported.
|
||||
- **Circular references are prohibited**: Detected at registration time.
|
||||
|
||||
### Actor vs Agent
|
||||
|
||||
The actor/agent distinction is intentional and precise:
|
||||
|
||||
| | Actor | Agent |
|
||||
|-|-------|-------|
|
||||
| **Definition** | Anything conversational — the general abstraction | A specialized actor with LLM reasoning, tool-calling, and memory |
|
||||
| **Scope** | May be an agent, a composite workflow, a multi-step graph, or an external system wrapper | Always an LLM-backed conversational entity |
|
||||
| **Graph shape** | Any graph topology | Typically a single-node graph with tool-calling loop |
|
||||
| **Key capability** | Text-in / text-out | Text-in / text-out + tool-calling + planning + role identity |
|
||||
| **Relationship** | Superset | Subset: every agent IS an actor, not every actor is an agent |
|
||||
|
||||
An agent is the most common type of actor, but the actor abstraction exists precisely to accommodate non-agent participants in graphs (tool nodes, external system adapters, sub-graph orchestrators).
|
||||
|
||||
### Actor Roles in the Plan Lifecycle
|
||||
|
||||
Actors fill specialized roles within the plan lifecycle:
|
||||
|
||||
| Role | Purpose | Required |
|
||||
|------|---------|----------|
|
||||
| **Strategy actor** | Produces the initial decision tree during the Strategize phase | Yes |
|
||||
| **Execution actor** | Carries out decisions during the Execute phase | Yes |
|
||||
| **Estimation actor** | Provides effort/cost estimates before execution | No |
|
||||
| **Invariant actor** | Reconciles invariant violations during execution | No |
|
||||
| **Orchestrator actor** | Top-level actor that a session is bound to | Implicit |
|
||||
|
||||
Each role is filled by an actor reference (namespaced name) in the action configuration. The same actor definition can fill multiple roles across different actions.
|
||||
|
||||
### Nodes in an Actor's Graph
|
||||
|
||||
An actor's graph contains two types of nodes:
|
||||
|
||||
1. **Actor nodes** (`type: agent`) — references to other actors by name. These provide intelligence, reasoning, and conversational capability.
|
||||
|
||||
2. **Tool nodes** (`type: tool`) — deterministic, non-LLM steps that directly invoke a tool. Tool nodes can reference named registered tools or define anonymous inline tools.
|
||||
|
||||
Actors provide intelligence; tools provide capability. Both participate as first-class nodes in the same graph, connected by edges with optional conditional routing.
|
||||
|
||||
### Capability Acquisition
|
||||
|
||||
Actors acquire capabilities (tools) exclusively through skills:
|
||||
|
||||
1. An actor's YAML configuration lists skill references in its `skills:` section.
|
||||
2. At activation, the runtime resolves each skill to its flattened tool set.
|
||||
3. The merged tool surface is made available for both LLM tool-calling within agent nodes and as named tool nodes in the actor's graph.
|
||||
|
||||
There is no mechanism for an actor to gain tool capabilities outside the skill system.
|
||||
|
||||
## Constraints
|
||||
|
||||
- Every custom actor must be defined in a YAML configuration file with a namespaced name.
|
||||
- Every custom actor is implemented as a LangGraph StateGraph — there is no "non-graph" actor type.
|
||||
- Actors must only reference other actors and tools by fully-qualified namespaced name.
|
||||
- Circular actor references are prohibited and must be detected at registration time.
|
||||
- Actor capability acquisition must go through the skill system — direct tool references outside skills are not permitted for capability assignment.
|
||||
- All actors must maintain the text-in/text-out conversational contract, regardless of internal complexity.
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
- A single abstraction covers all scales from simple LLM wrappers to complex multi-stage pipelines, eliminating conceptual fragmentation.
|
||||
- The actor-as-graph principle means there is one composition model, one configuration format, and one runtime execution model for all conversational participants.
|
||||
- Hierarchical composition enables reuse — sub-actors are independently defined, tested, and composed into larger workflows.
|
||||
- The actor/agent distinction preserves precision (agents have specific capabilities) while the actor generalization ensures nothing conversational is excluded.
|
||||
- New types of conversational participants (e.g., external system adapters) fit naturally into the model without new abstractions.
|
||||
|
||||
### Negative
|
||||
- Even trivially simple LLM wrappers are technically graphs, adding conceptual overhead for users who just want "an LLM that answers questions."
|
||||
- Named reference composition requires all sub-actors to be independently registered, increasing configuration surface for deep hierarchies.
|
||||
- The text-in/text-out constraint excludes non-conversational processing (e.g., pure data transformation) from the actor model, requiring tool nodes instead.
|
||||
|
||||
### Risks
|
||||
- Users may conflate "actor" and "agent" despite the formal distinction, leading to configuration errors (e.g., treating a composite workflow as if it were a single LLM agent).
|
||||
- Deeply nested actor hierarchies could become difficult to debug when errors propagate through multiple graph layers.
|
||||
- The "everything is a graph" principle could discourage simpler mental models that are sufficient for basic use cases.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
**Separate abstractions for agents, workflows, and orchestrators** — Define distinct types (Agent, Workflow, Pipeline, Orchestrator) with different configuration formats and composition rules. Increases conceptual load, fragments the configuration model, and requires mapping between types when composing. The actor-as-graph unification is strictly more powerful and simpler. Rejected.
|
||||
|
||||
**Agent-only model (no actor generalization)** — All conversational participants are "agents." This conflates LLM-backed reasoning with graph orchestration and makes it unclear how to model non-LLM nodes or external system wrappers. The actor/agent distinction preserves precision. Rejected.
|
||||
|
||||
**Code-defined actors (no YAML)** — Define actors in Python instead of YAML. Provides maximum flexibility but sacrifices declarative configuration, CLI management (`agents actor add/show/list`), and the ability for non-developers to compose workflows. YAML configuration with code escape hatches (inline Python in tool nodes) is the correct balance. Rejected as the primary model.
|
||||
|
||||
**Flat actor model (no hierarchical composition)** — Actors cannot reference other actors; all graph nodes must be tool nodes or direct LLM nodes. This eliminates the "orchestrator of orchestrators" pattern, prevents sub-graph reuse, and forces users to flatten complex workflows into single monolithic graphs. Rejected.
|
||||
|
||||
## Compliance
|
||||
|
||||
- **Actor-as-graph tests**: Verify that all custom actor configurations (including single-LLM actors) produce valid LangGraph StateGraph instances.
|
||||
- **Composition tests**: Verify that actor graphs correctly resolve named actor references, detect circular references, and enforce load order.
|
||||
- **Role binding tests**: Validate that actions correctly bind strategy, execution, estimation, and invariant roles to registered actors.
|
||||
- **Capability binding tests**: Confirm that actor activation resolves skill references and produces the correct merged tool surface.
|
||||
- **Conversational contract tests**: Verify that all actors (simple and composite) accept text input and produce text output regardless of internal graph complexity.
|
||||
|
||||
## Related ADRs
|
||||
|
||||
| ADR | Title | Relationship |
|
||||
|-----|-------|-------------|
|
||||
| [ADR-010](ADR-010-actor-and-agent-architecture.md) | Actor and Agent Architecture | Defines the actor implementation model (LangGraph StateGraph), role specialization, and graph construction |
|
||||
| [ADR-011](ADR-011-tool-system.md) | Tool System | Tools serve as atomic execution nodes within actor graphs alongside actor nodes |
|
||||
| [ADR-012](ADR-012-skill-system.md) | Skill System | Skills are the mechanism through which actors acquire tool capabilities |
|
||||
| [ADR-022](ADR-022-langchain-langgraph-integration.md) | LangChain/LangGraph Integration | Actors are implemented as LangGraph StateGraph instances; LangGraph is the graph runtime |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | Agent Skills appear as tool nodes in actor graphs and extend actor knowledge |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tools appear as tool nodes in actor graphs via skill composition |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Skills are the unit of capability assignment to actors; the skill-actor binding model |
|
||||
|
||||
## Acceptance
|
||||
|
||||
### Votes For
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Votes Against
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
|
||||
### Abstentions
|
||||
|
||||
| Voter | Comment |
|
||||
|-------|---------|
|
||||
|
||||
**Total: 0**
|
||||
+7
-1
@@ -112,10 +112,16 @@ These ADRs address external integrations, operational interfaces, and deployment
|
||||
| [ADR-023](ADR-023-server-mode.md) | Server Mode | Client/server deployment with shared namespaces and remote execution. |
|
||||
| [ADR-024](ADR-024-configuration-system.md) | Configuration System | TOML global config with dot-path keys, YAML entity config, resolution chain. |
|
||||
| [ADR-025](ADR-025-observability-and-logging.md) | Observability and Logging | structlog JSON output with context binding, optional LangSmith tracing. |
|
||||
| [ADR-026](ADR-026-agent-client-protocol.md) | Agent Client Protocol (ACP) | Versioned client-server contract for sessions, plans, registries, and event streaming. |
|
||||
| [ADR-027](ADR-027-language-server-protocol.md) | Language Server Protocol (LSP) Integration | IDE plugin as LSP server using ACP for backend operations. |
|
||||
| [ADR-028](ADR-028-agent-skills-standard.md) | Agent Skills Standard (AgentSkills.io) | SKILL.md-based progressive disclosure skills integrated as tool sources and actor graph nodes. |
|
||||
| [ADR-029](ADR-029-model-context-protocol.md) | Model Context Protocol (MCP) Adoption | MCP tool discovery, registry integration, skill composition, and actor-graph usage. |
|
||||
| [ADR-030](ADR-030-skill-abstraction-definition.md) | Skill Abstraction Definition | Canonical definition of a skill as a composable collection of tools from four sources (MCP, Agent Skills, built-in, custom). |
|
||||
| [ADR-031](ADR-031-actor-abstraction-definition.md) | Actor Abstraction Definition | Canonical definition of an actor as anything conversational — single LLM, composed graph, or hierarchical orchestrator. |
|
||||
|
||||
## Creating a New ADR
|
||||
|
||||
1. Assign the next sequential number (e.g., `ADR-026`).
|
||||
1. Assign the next sequential number (e.g., `ADR-032`).
|
||||
2. Create a file named `ADR-0NN-<kebab-case-title>.md` in this directory.
|
||||
3. Copy the template structure from any existing ADR.
|
||||
4. Fill in the metadata table with `Status: Proposed`, the current date, author(s), and leave approver(s) blank.
|
||||
|
||||
+73
-3
@@ -8,6 +8,20 @@ In **server mode**, CleverAgents becomes a collaborative hub where teams can sha
|
||||
|
||||
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:
|
||||
|
||||
### Standards Alignment
|
||||
|
||||
CleverAgents deliberately adopts open, versioned protocols wherever possible so that clients, tools, and skills can interoperate without bespoke integrations. Two guiding principles govern protocol adoption:
|
||||
|
||||
* **Prefer open protocols** — align with community standards to keep integrations portable and reduce vendor lock-in.
|
||||
* **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:
|
||||
|
||||
* **Agent Client Protocol (ACP)** — defines the versioned client-server contract for sessions, plan lifecycle, registry access, and event streaming across all Presentation-layer clients (CLI, TUI, Web, IDE). This makes clients interchangeable and enables reliable remote execution in server mode.
|
||||
* **Model Context Protocol (MCP)** — 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.
|
||||
* **Language Server Protocol (LSP)** — the standard for IDE integration. The CleverAgents IDE plugin is an LSP server that surfaces plan-aware code actions, diagnostics, and context lookups, communicating with the backend exclusively through ACP. This provides editor-agnostic IDE support without bespoke plugins.
|
||||
* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))** — 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.
|
||||
|
||||
**CleverAgents** provides:
|
||||
|
||||
* A **first-class plan lifecycle** (Action templates driving Strategize/Execute/Apply phases) for breaking down and tracking complex work,
|
||||
@@ -37,13 +51,17 @@ While CleverAgents leverages LangGraph and LangChain for the underlying LLM runt
|
||||
* **Virtual Resource**: A resource representing an abstract equivalence identity that links physical resources sharing the same content, hash, or name. Has no location; cannot be directly read or written. Equivalence relationships update when underlying physical resources diverge.
|
||||
* **Resource Binding**: The association between a tool and the resources it operates on, declared via typed resource slots. Slots resolve through contextual binding (from the plan's project), static binding (hardcoded at registration), or parameter binding (passed at invocation).
|
||||
* **Resource Registry**: The persistent catalog of all registered resources and their DAG relationships (parent/child links). One of the core registries, alongside the Tool Registry, Skill Registry, Actor Registry, and Provider Registry.
|
||||
* **Skill**: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing MCP server / Agent Skills Standard tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`.
|
||||
* **Tool**: The atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover`/`activate`/`execute`/`deactivate`). Sources: MCP servers, Agent Skills Standard folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`.
|
||||
* **Skill**: A composable, namespaced collection of tools assembled by referencing named tools, defining inline anonymous tools, including other skills, or exposing Model Context Protocol (MCP) server tools and Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) tools. Actors reference skills by name to acquire capabilities. Namespaced as `[[server:]namespace/]name`.
|
||||
* **MCP (Model Context Protocol)**: A standard for exposing tools and resources over a server boundary via JSON-RPC. CleverAgents discovers MCP tools through the MCPToolAdapter and registers them in the Tool Registry with extended capability metadata. MCP tools can be composed into skills and used as tool nodes in actor graphs.
|
||||
* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))**: A standard for packaging instruction-driven, multi-step workflows as `SKILL.md` files with optional `scripts/`, `references/`, and `assets/` directories, using progressive disclosure. In CleverAgents, Agent Skills are surfaced as tools inside skills and loaded on demand by the actor runtime. Within actor graphs they appear as tool nodes and may orchestrate multiple MCP tools during execution.
|
||||
* **Tool**: The atomic unit of execution: a namespaced, independently registered callable operation. Defined by JSON Schema inputs/outputs, capability metadata (`read_only`, `writes`, `checkpointable`), and a four-stage lifecycle (`discover`/`activate`/`execute`/`deactivate`). Sources: Model Context Protocol (MCP) servers, Agent Skills ([https://AgentSkills.io](https://AgentSkills.io)) folders, built-ins, or custom Python. Namespaced as `[[server:]namespace/]name`.
|
||||
* **Validation**: A Tool subtype adding: a `mode` (`required` | `informational`) controlling whether failure blocks execution; a structured JSON return with mandatory `passed` boolean, optional `data`, and optional `message`. Always read-only (`writes = false`, `checkpointable = false`). May wrap an existing Tool via `wraps` + `transform` to reuse its implementation. Shares the Tool naming namespace — no name collisions allowed. Usable anywhere a Tool is expected, but not vice versa. Managed via `agents validation add/attach/detach`; listed, inspected, and removed through standard `agents tool` commands. Always attached to a resource, optionally scoped to a project or plan.
|
||||
* **Anonymous Tool**: An inline tool definition embedded in a skill YAML or actor graph node. Same schema as a named tool but unregistered, unnamespaced, and scoped only to its defining context.
|
||||
* **Actor**: A YAML-configured conversational unit — either a single LLM/agent or a composed LangGraph of actors and tool nodes. Specialized roles: strategy actor, execution actor, estimation actor, invariant reconciliation actor. Namespaced as `[[server:]namespace/]name`.
|
||||
* **Session**: A persistent conversation thread tied to an orchestrator actor. Maintains message history across plans and serves as the user's natural-language interface.
|
||||
* **Server**: An optional shared backend providing multi-user storage, namespace resolution, and remote plan execution.
|
||||
* **ACP (Agent Client Protocol)**: A versioned client-server protocol that defines authentication, session lifecycle, plan operations, registry access, and event streaming for all Presentation-layer clients (CLI, TUI, Web, IDE plugin). In local mode ACP maps to in-process service facade calls; in server mode it is implemented by the REST API over HTTPS. Ensures clients are interchangeable and supports third-party clients.
|
||||
* **LSP (Language Server Protocol)**: A standard for IDE integration. The CleverAgents IDE plugin runs as an LSP server that translates code actions and diagnostics into plan operations and validation results, communicating with the backend through ACP. This enables editor-agnostic IDE support without bespoke plugins per editor.
|
||||
* **Namespace**: The scoping segment in the name format `[[server:]namespace/]name`. Defaults to `local/` when omitted. `local/` is reserved for local-only items (no server applies). Non-`local/` namespaces with server omitted assume the default configured server. `<username>/` and `<orgname>/` are server-stored. Built-in LLM actors use provider prefixes (e.g., `openai/`, `anthropic/`). Built-in resource types are unnamespaced.
|
||||
* **Decision**: A persisted choice point in a plan's decision tree, created during Strategize or Execute. Records the question, chosen option, alternatives, confidence score, rationale, context snapshot, and downstream dependencies. Types: `prompt_definition`, `invariant_enforced`, `strategy_choice`, `subplan_spawn`, `subplan_parallel_spawn`, among others. Execute-phase decisions are constrained by Strategize-phase decisions and arise from runtime discoveries. Supports targeted correction with selective subtree recomputation.
|
||||
* **Invariant**: A natural-language constraint on plan execution scoped to global, project, action, or plan level. Precedence: plan > action > project > global. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as `invariant_enforced` decisions that propagate to child plans.
|
||||
@@ -6681,6 +6699,9 @@ This enables a pattern where:
|
||||
|
||||
#### What an Actor Is
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The canonical definition of an actor — anything conversational, actor-as-graph principle, hierarchical composition, and the actor/agent distinction — is formalized in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
|
||||
|
||||
An **actor** is the abstraction that generalizes "agent" into "anything conversational."
|
||||
|
||||
* It can be as small as a single LLM agent.
|
||||
@@ -6805,6 +6826,9 @@ This enables hierarchical composition where:
|
||||
|
||||
#### Actor vs Agent (Relationship)
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The formal actor/agent distinction — actors as the general abstraction, agents as a specialized subset — is defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
|
||||
|
||||
* **Agent**: an actor that is specifically an LLM with tools and reasoning behaviors.
|
||||
* **Actor**: may be an agent, but may also be:
|
||||
|
||||
@@ -6830,6 +6854,9 @@ A robust actor schema should include:
|
||||
|
||||
#### Actor Composition and Graphs
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
Hierarchical actor composition, the actor-as-graph principle, and graph node types are defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md).
|
||||
|
||||
Actors can reference:
|
||||
|
||||
* other actors (by namespaced name)
|
||||
@@ -6843,6 +6870,9 @@ This is central to enabling both:
|
||||
|
||||
#### Nodes in the Graph: Actors and Tools
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The two graph node types (actor nodes and tool nodes) and their relationship to the skill and tool systems are defined in [ADR-031: Actor Abstraction Definition](adr/ADR-031-actor-abstraction-definition.md) and [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
|
||||
|
||||
Graph nodes can be any of:
|
||||
|
||||
* an **actor** (another LLM agent or composite workflow, referenced by name),
|
||||
@@ -7854,7 +7884,9 @@ This approach means:
|
||||
#### MCP Integration Details
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The MCP integration strategy, concept mapping, and extended capabilities are defined in [ADR-022: LangChain/LangGraph Integration](adr/ADR-022-langchain-langgraph-integration.md).
|
||||
MCP adoption, tool-to-skill mapping, and actor-graph usage are defined in [ADR-029: Model Context Protocol (MCP) Adoption](adr/ADR-029-model-context-protocol.md).
|
||||
|
||||
CleverAgents integrates with the Model Context Protocol (MCP) to discover and invoke external tools, then normalizes them into the Tool Registry with extended capability metadata and sandbox-aware execution. MCP tools are composed into skills and appear as tool nodes in actor graphs, giving them the same lifecycle, change-tracking, and checkpoint semantics as built-in tools.
|
||||
|
||||
##### MCP Concepts Mapping
|
||||
|
||||
@@ -7919,6 +7951,11 @@ This ensures MCP tools respect sandbox boundaries even though they have no aware
|
||||
|
||||
#### Agent Skills Integration Details
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The Agent Skills standard integration is defined in [ADR-028: Agent Skills Standard (AgentSkills.io)](adr/ADR-028-agent-skills-standard.md).
|
||||
|
||||
Agent Skills follow the Agent Skills standard from [https://AgentSkills.io](https://AgentSkills.io), which defines the `SKILL.md` structure and the progressive disclosure model used by the runtime. Within actor graphs, Agent Skills appear as tool nodes — the actor runtime loads the skill's instructions into the LLM context when the node activates, enabling the agent to follow multi-step procedures that may invoke MCP tools, built-in tools, or other Agent Skills during execution.
|
||||
|
||||
##### Discovery and Progressive Disclosure
|
||||
|
||||
Agent Skills follow a three-tier progressive disclosure model that maps directly to the tool lifecycle:
|
||||
@@ -8592,6 +8629,9 @@ agents plan use local/implement-feature local/api-service
|
||||
|
||||
#### What a Skill Is
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The canonical definition of a skill — its four tool sources, flattening model, and role as the unit of capability assignment — is formalized in [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
|
||||
|
||||
A **skill** is a namespaced, reusable **collection of tools** that is registered in the system via its own YAML configuration file and managed through `agents skill` CLI commands. Skills are the unit of capability composition in CleverAgents — they define *what an actor can do* by assembling tools into coherent, reusable bundles.
|
||||
|
||||
A skill is **not** a single tool. It is a **container** that references one or more tools (by name from the Tool Registry) and/or defines anonymous inline tools, along with metadata describing the collection's purpose, capabilities, and safety characteristics. Tools are independently registered, callable operations (see the **Tools** section above). Skills organize them into reusable groups.
|
||||
@@ -8606,6 +8646,9 @@ A skill is **not** a single tool. It is a **container** that references one or m
|
||||
|
||||
#### The Skill / Tool Distinction
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The formal distinction between skills (containers) and tools (atomic operations), and the source-agnostic flattening model, are defined in [ADR-030: Skill Abstraction Definition](adr/ADR-030-skill-abstraction-definition.md).
|
||||
|
||||
```kroki-plantuml
|
||||
@startuml
|
||||
skinparam packageStyle rectangle
|
||||
@@ -9022,6 +9065,21 @@ A server is an optional mode that enables:
|
||||
|
||||
**It is possible to run a client with no server at all.** Server is optional.
|
||||
|
||||
#### Agent Client Protocol (ACP)
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The Agent Client Protocol is defined in [ADR-026: Agent Client Protocol (ACP)](adr/ADR-026-agent-client-protocol.md).
|
||||
|
||||
ACP is the versioned contract between every Presentation-layer client (CLI, TUI, Web, IDE plugin) and the CleverAgents backend. It defines canonical operations for:
|
||||
|
||||
* **Session lifecycle** — create, resume, list, export, import.
|
||||
* **Plan lifecycle** — use, execute, apply, cancel, status, tree, artifacts.
|
||||
* **Registries** — list / show / add / update / remove for actors, skills, tools, validations, resources, projects, and actions.
|
||||
* **Context operations** — context show / inspect / simulate, context policy updates.
|
||||
* **Event streaming** — plan state changes, tool execution events, validation results, and structured log events.
|
||||
|
||||
In **local mode** ACP maps directly to in-process service facade calls (no network). In **server mode** ACP is implemented by the REST API over HTTPS with token-based authentication. This duality means every client works identically regardless of deployment mode, and third-party clients can rely on a stable, versioned surface.
|
||||
|
||||
#### Plan Execution Location
|
||||
|
||||
Where a plan executes depends on the project type:
|
||||
@@ -25012,6 +25070,18 @@ DS -down-> IDX
|
||||
@enduml
|
||||
```
|
||||
|
||||
#### Standards and Protocols in the Architecture
|
||||
|
||||
!!! adr "Architecture Decision"
|
||||
The four protocol standards and their architectural roles are defined across [ADR-026: Agent Client Protocol (ACP)](adr/ADR-026-agent-client-protocol.md), [ADR-027: Language Server Protocol (LSP) Integration](adr/ADR-027-language-server-protocol.md), [ADR-028: Agent Skills Standard (AgentSkills.io)](adr/ADR-028-agent-skills-standard.md), and [ADR-029: Model Context Protocol (MCP) Adoption](adr/ADR-029-model-context-protocol.md).
|
||||
|
||||
Each adopted standard maps to an explicit architectural boundary:
|
||||
|
||||
* **ACP (Agent Client Protocol)** — connects Presentation-layer clients (CLI, TUI, Web, IDE) to the Service Facade / REST API. Covers sessions, plans, registries, and event streaming. In local mode it resolves to in-process calls; in server mode it is the HTTPS contract. This keeps clients interchangeable and supports third-party client development.
|
||||
* **LSP (Language Server Protocol)** — the IDE plugin is an LSP server that maps editor code actions and diagnostics to plan operations and validation results, pulling all data through ACP. This enables editor-agnostic IDE support without per-editor plugin maintenance.
|
||||
* **MCP (Model Context Protocol)** — external MCP servers reside in the Infrastructure layer. The MCPToolAdapter bridges them into first-class Tools in the Domain model with extended capability metadata. MCP tools are composed into skills and used as tool nodes in actor graphs, giving the system standardized tool discovery and invocation.
|
||||
* **Agent Skills ([https://AgentSkills.io](https://AgentSkills.io))** — Agent Skills are ingested into the Skill Registry and loaded by the actor runtime via progressive disclosure. Inside actor graphs they appear as tool nodes whose execution is instruction-driven — the agent follows multi-step procedures that may call MCP tools, built-ins, or other Agent Skills. This adds portable, reusable workflows that complement schema-driven MCP tools.
|
||||
|
||||
#### Architectural Principles
|
||||
|
||||
1. **Hexagonal Architecture (Ports and Adapters)**: The domain layer defines abstract repository interfaces (ports). The infrastructure layer provides concrete implementations (adapters). This allows swapping SQLite for PostgreSQL, FAISS for Qdrant, or local execution for remote server execution without touching domain logic.
|
||||
|
||||
@@ -44,6 +44,12 @@ nav:
|
||||
- ADR-023 Server Mode: adr/ADR-023-server-mode.md
|
||||
- ADR-024 Configuration System: adr/ADR-024-configuration-system.md
|
||||
- ADR-025 Observability & Logging: adr/ADR-025-observability-and-logging.md
|
||||
- ADR-026 Agent Client Protocol (ACP): adr/ADR-026-agent-client-protocol.md
|
||||
- ADR-027 Language Server Protocol (LSP) Integration: adr/ADR-027-language-server-protocol.md
|
||||
- ADR-028 Agent Skills Standard (AgentSkills.io): adr/ADR-028-agent-skills-standard.md
|
||||
- ADR-029 Model Context Protocol (MCP) Adoption: adr/ADR-029-model-context-protocol.md
|
||||
- ADR-030 Skill Abstraction Definition: adr/ADR-030-skill-abstraction-definition.md
|
||||
- ADR-031 Actor Abstraction Definition: adr/ADR-031-actor-abstraction-definition.md
|
||||
|
||||
theme:
|
||||
name: material
|
||||
|
||||
Reference in New Issue
Block a user