# Protocol-Based Agent Architecture

## Overview

Deliberate supports a **hybrid architecture** combining multiple protocols:

1. **Direct CLI Execution** ✅ - Implemented and working
2. **MCP (Model Context Protocol)** ✅ - Implemented for Claude and Codex
3. **ACP (Agent Communication Protocol)** 🔜 - Future support for Gemini

**Current Status:** Deliberate uses both CLI and MCP adapters depending on the use case.
- **CLI adapters**: Fast, simple execution for planning and review
- **MCP adapters**: Rich tool/resource access for execution phases

## Protocol Comparison

### 1. Direct CLI Execution ✅ (Current)

**How it works:**
- Spawn subprocess with CLI tool
- Pass task via stdin (Gemini) or argument (Claude, Codex)
- Parse stdout for results

**Pros:**
- Simple, direct integration
- Works today with minimal setup
- CLI handles all agent logic
- Natural fit for subprocess model

**Cons:**
- CLI-specific quirks (stdin vs args)
- Limited structured communication
- No standard protocol
- Hard to debug intermediate steps

**Current Implementation:**
```python
# Gemini: stdin piping
proc = await asyncio.create_subprocess_exec(
    "gemini", "--yolo",
    stdin=asyncio.subprocess.PIPE,
    stdout=asyncio.subprocess.PIPE,
)
await proc.communicate(input=task.encode())

# Claude: with JSON schema
proc = await asyncio.create_subprocess_exec(
    "claude", "--dangerously-skip-permissions", "-p",
    "--output-format", "json",
    "--json-schema", json.dumps(schema),
    task
)
```

### 2. ACP (Agent Communication Protocol)

**What is ACP:**
- HTTP/JSON-RPC based protocol
- Designed for agent-to-agent communication
- Open standard (Apache License)
- Developed by Zed Editor, with Linux Foundation governance

**Gemini CLI Support:**
- Gemini CLI v0.2.0+ supports ACP
- Command: `gemini --experimental-acp`
- Runs as HTTP server responding to JSON-RPC requests
- Reference implementation for the protocol

**How it works:**
```bash
# Start Gemini in ACP mode
gemini --experimental-acp
# Server listens on HTTP port, accepts JSON-RPC requests
```

**JSON-RPC Format:**
```json
{
  "jsonrpc": "2.0",
  "method": "agent.run",
  "params": {
    "agent": "gemini",
    "input": [
      {
        "role": "user",
        "parts": [{"type": "text", "content": "Review this code..."}]
      }
    ]
  },
  "id": 1
}
```

**Pros:**
- Standardized protocol
- HTTP-based (familiar, debuggable)
- Session management built-in
- Streaming support
- Status tracking

**Cons:**
- Requires HTTP server lifecycle management
- More complex than direct CLI
- Experimental in Gemini CLI
- Protocol still evolving

**Sources:**
- [Zed Blog: Gemini CLI ACP](https://zed.dev/blog/bring-your-own-agent-to-zed)
- [ACP Documentation](https://agentcommunicationprotocol.dev/)
- [Gemini CLI ACP Support](https://zed.dev/acp/agent/gemini-cli)

### 3. MCP (Model Context Protocol)

**What is MCP:**
- Protocol for providing context to LLMs
- Developed by Anthropic
- Focused on tool/resource access
- Used by Claude Desktop, Zed, etc.

**Claude CLI Support:**
```bash
# Start Claude as MCP server
claude mcp serve [--debug] [--verbose]

# Manage MCP servers
claude mcp add <name> <command>
claude mcp list
claude mcp remove <name>
```

**Codex CLI Support:**
```bash
# Run Codex as MCP server (stdio transport)
codex mcp-server [--enable <feature>]
```

**How it works:**
- CLI runs as stdio-based server
- Client sends JSON-RPC requests
- Server provides tools/resources/prompts
- Bidirectional communication

**Pros:**
- Rich context protocol (tools, resources, prompts)
- Well-documented by Anthropic
- Supported by multiple clients (Zed, Claude Desktop)
- stdio transport (simpler than HTTP)

**Cons:**
- More complex protocol than ACP
- Requires JSON-RPC client implementation
- Designed for context, not pure agent execution
- stdio lifecycle management

## Architecture Recommendations

### Short-term: Keep Direct CLI ✅

**Rationale:**
- Works today for Claude and Gemini
- Simple, predictable
- Good for MVP and learning each CLI's capabilities
- Minimal dependencies

**Continue with:**
- Current `EnhancedCLIAdapter` approach
- Stdin piping for Gemini
- JSON schema for Claude
- Text parsing for responses

### Medium-term: Evaluate ACP for Gemini

**When to consider:**
- Need structured agent communication
- Want session management
- Streaming responses important
- Building multi-agent workflows

**Implementation approach:**
```python
class ACPAdapter(ModelAdapter):
    async def start_server(self):
        """Start gemini --experimental-acp"""
        proc = await asyncio.create_subprocess_exec(
            "gemini", "--experimental-acp",
            stdout=asyncio.subprocess.PIPE,
        )
        # Parse server URL from stdout
        # Return HTTP client

    async def run_agentic(self, task):
        """Send JSON-RPC request to ACP server"""
        response = await self.http_client.post("/", json={
            "jsonrpc": "2.0",
            "method": "agent.run",
            "params": {"agent": "gemini", "input": [...]},
            "id": 1
        })
```

### Long-term: Consider MCP for Rich Context

**When to consider:**
- Need tools/resources integration
- Want context sharing between agents
- Building IDE/editor integration
- Leveraging MCP ecosystem

**Challenges:**
- Requires JSON-RPC client library
- stdio lifecycle management
- Protocol designed for context, not execution
- More complexity

## Decision Framework

| Use Case | Recommended Protocol |
|----------|---------------------|
| Simple task execution | Direct CLI ✅ |
| Structured responses | Direct CLI + JSON schema ✅ |
| Session management | ACP |
| Streaming agent output | ACP |
| Multi-agent coordination | ACP |
| IDE/editor integration | MCP |
| Tool/resource sharing | MCP |
| Context-rich environments | MCP |

## Current Hybrid Implementation ✅

Deliberate now implements **both CLI and MCP adapters** in a hybrid architecture:

### Adapter Types

**1. CLIAdapter** (`src/deliberate/adapters/cli_adapter.py`)
- Direct subprocess execution
- Supports Claude, Gemini, and Codex CLIs
- Fast and simple
- Best for planning and review phases

**2. MCPAdapter** (`src/deliberate/adapters/mcp_adapter.py`)
- JSON-RPC communication over stdio
- Supports Claude and Codex MCP servers
- Rich tool and resource access
- Best for execution phases

### Configuration Example

```yaml
agents:
  # CLI-based agent for planning
  claude-cli:
    type: cli
    command: ["claude", "--print", "-p"]
    capabilities: [planner, executor, reviewer]

  # MCP-based agent for execution
  claude-mcp:
    type: mcp
    command: ["claude", "mcp", "serve"]
    capabilities: [executor, reviewer]

workflow:
  planning:
    agents: [claude-cli]  # Fast CLI for planning
  execution:
    agents: [claude-mcp]  # MCP for rich tool access
  review:
    agents: [claude-cli]  # CLI for quick reviews
```

### When to Use Each

| Phase | Recommended Adapter | Reason |
|-------|-------------------|--------|
| Planning | CLI | Fast, simple, doesn't need tools |
| Execution | MCP | Full tool access (git, fs, bash) |
| Review | CLI | Fast, structured output |
| Debate | CLI | Quick back-and-forth |
| Refinement | MCP | May need tool access for fixes |

### MCP Adapter Features

- **Protocol**: JSON-RPC 2.0 over stdio
- **Transport**: Subprocess with stdin/stdout pipes
- **Initialization**: Proper MCP handshake with `initialize` request
- **Tools**: Can list and use MCP tools (git, fs, bash, etc.)
- **Resources**: Can access MCP resources
- **Sampling**: Uses `sampling/createMessage` for completions
- **Lifecycle**: Async context manager for proper cleanup

### Implementation Files

- `src/deliberate/adapters/mcp_adapter.py` - MCP adapter implementation
- `src/deliberate/adapters/cli_adapter.py` - CLI adapter implementation
- `src/deliberate/orchestrator.py` - Adapter selection logic
- `tests/unit/test_mcp_adapter.py` - MCP adapter tests
- `.deliberate-mcp-hybrid.yaml` - Example hybrid configuration

### Testing

```bash
# Test MCP adapter unit tests
uv run pytest tests/unit/test_mcp_adapter.py

# Test with hybrid config
jury run "@task.txt" --config .deliberate-mcp-hybrid.yaml
```

## Implementation Priority

1. ✅ **Done:** CLI integration (Claude, Gemini, Codex)
2. ✅ **Done:** MCP adapter for Claude and Codex
3. 🔜 **Next:** Experiment with ACP for Gemini
4. 🔜 **Future:** End-to-end testing with real MCP servers

## References

**ACP:**
- [Agent Communication Protocol Docs](https://agentcommunicationprotocol.dev/)
- [Zed Blog: Gemini CLI](https://zed.dev/blog/bring-your-own-agent-to-zed)
- [Gemini CLI ACP Agent](https://zed.dev/acp/agent/gemini-cli)

**MCP:**
- [Claude MCP Documentation](https://docs.anthropic.com/en/docs/build-with-claude/mcp)
- [MCP Specification](https://spec.modelcontextprotocol.io/)

**CLIs:**
- Gemini CLI: `gemini --help`, `gemini --experimental-acp`
- Claude CLI: `claude mcp serve --help`
- Codex CLI: `codex mcp-server --help`
