# Agents Council Integration for QwenClaw

## Overview

This skill integrates **Agents Council** into QwenClaw, enabling multi-agent collaboration while maintaining full RAG (Retrieval-Augmented Generation) capabilities.

**Version:** 1.6.0  
**Category:** Multi-Agent Orchestration  
**Dependencies:** agents-council

---

## What is Agents Council?

**Agents Council** is the simplest way to bridge and collaborate across AI Agent sessions like Claude Code, Codex, Gemini, Cursor, or Qwen Code. It allows your agents to combine their strengths to solve complex tasks without extra infrastructure.

### Key Features

- ✅ **Centralized agent communication** via MCP stdio server
- ✅ **Session Preservation** - Start agents with specific context, resume when done
- ✅ **Human Participation** - Monitor or join discussions via desktop app
- ✅ **Private & Local** - State stored at `~/.agents-council/state.json`
- ✅ **Flexibility** - Markdown or JSON text output

---

## Installation

### 1. Install Agents Council

```bash
# Using npm
npm install -g agents-council

# Or using bun
bun add -g agents-council
```

### 2. Add MCP Server to Qwen Code

```bash
# Add Agents Council MCP server
claude mcp add council npx agents-council@latest mcp

# Or with specific agent name
claude mcp add council -s user -- npx agents-council@latest mcp -n Opus
```

### 3. Update QwenClaw Configuration

Add to `~/.qwen/settings.json`:

```json
{
  "mcpServers": {
    "council": {
      "command": "npx",
      "args": ["agents-council@latest", "mcp"]
    },
    "qwenclaw": {
      "command": "bun",
      "args": ["run", "start", "--web"],
      "cwd": "~/qwenclaw"
    }
  }
}
```

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                   QWENCLAW DAEMON                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  RAG Engine  │  │ Agent Skills │  │  Tools API   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                          │
                          │ MCP
                          ▼
┌─────────────────────────────────────────────────────────┐
│                  AGENTS COUNCIL                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │   Qwen Code  │  │ Claude Code  │  │   Codex      │  │
│  │    Agent     │  │    Agent     │  │    Agent     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
│                          │                               │
│                  ┌───────┴───────┐                       │
│                  │ Council Hall  │                       │
│                  │  (Desktop)    │                       │
│                  └───────────────┘                       │
└─────────────────────────────────────────────────────────┘
                          │
                          │ RAG
                          ▼
┌─────────────────────────────────────────────────────────┐
│                    VECTOR STORE                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Documents   │  │   Skills     │  │   Sessions   │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
```

---

## Usage

### From Qwen Code CLI

```
/council start          - Start Agents Council
/council status         - Check council status
/council summon claude  - Summon Claude to council
/council summon codex   - Summon Codex to council
/council discuss        - Start multi-agent discussion
/council monitor        - Open Council Hall desktop app
```

### Programmatic Usage

```typescript
import { AgentsCouncil } from './agents-council-integration';

const council = new AgentsCouncil();

// Start council
await council.start();

// Summon agents
await council.summon('claude');
await council.summon('codex');

// Start discussion
const result = await council.discuss({
  topic: "Review this architecture",
  context: "We need to scale to 1M users...",
  agents: ['claude', 'codex', 'qwen'],
});

console.log(result.summary);
```

---

## RAG Integration

### Full RAG Capabilities Maintained

| Feature | Status | Description |
|---------|--------|-------------|
| **Vector Store** | ✅ Enabled | SQLite/Chroma/Pinecone support |
| **Document Retrieval** | ✅ Enabled | Semantic search across documents |
| **Skill Context** | ✅ Enabled | Share skill context across agents |
| **Session Memory** | ✅ Enabled | Persistent sessions with RAG |
| **Cross-Agent RAG** | ✅ Enabled | Share retrieved context between agents |

### RAG Configuration

```json
{
  "rag": {
    "enabled": true,
    "vectorStore": {
      "type": "sqlite",
      "path": "~/.qwen/qwenclaw/vector-store.db"
    },
    "embedding": {
      "model": "qwen-embedding",
      "dimensions": 768
    },
    "retrieval": {
      "topK": 5,
      "threshold": 0.7,
      "shareAcrossAgents": true
    }
  }
}
```

---

## Multi-Agent Workflows

### Workflow 1: Code Review Council

```typescript
const council = new AgentsCouncil();

await council.discuss({
  topic: "Code Review",
  context: `
    Review this pull request for:
    1. Security vulnerabilities
    2. Performance issues
    3. Code quality
    4. Best practices
  `,
  agents: ['claude', 'codex', 'qwen'],
  roles: {
    claude: 'Security expert',
    codex: 'Performance expert',
    qwen: 'Code quality expert',
  },
  ragContext: true, // Include RAG context
});
```

### Workflow 2: Architecture Design

```typescript
await council.discuss({
  topic: "System Architecture Design",
  context: "Design a scalable microservices architecture for...",
  agents: ['claude', 'codex'],
  output: 'markdown',
  ragContext: {
    documents: ['architecture-patterns.md', 'scalability-guide.md'],
    topK: 10,
  },
});
```

### Workflow 3: Debugging Session

```typescript
await council.discuss({
  topic: "Debug Production Issue",
  context: `
    Error: Connection timeout in production
    Stack trace: ${errorStack}
    Logs: ${logs}
  `,
  agents: ['claude', 'codex', 'qwen'],
  roles: {
    claude: 'Root cause analysis',
    codex: 'Fix implementation',
    qwen: 'Testing strategy',
  },
  ragContext: {
    searchQuery: 'connection timeout production',
    topK: 5,
  },
});
```

---

## Configuration

### council-config.json

Create `~/.agents-council/config.json`:

```json
{
  "council": {
    "autoStart": true,
    "desktopApp": true,
    "statePath": "~/.agents-council/state.json"
  },
  "agents": {
    "claude": {
      "enabled": true,
      "model": "claude-sonnet-4-5-20250929",
      "autoSummon": false
    },
    "codex": {
      "enabled": true,
      "model": "codex-latest",
      "autoSummon": false
    },
    "qwen": {
      "enabled": true,
      "model": "qwen-plus",
      "autoSummon": true
    }
  },
  "rag": {
    "enabled": true,
    "vectorStore": "sqlite",
    "shareAcrossAgents": true
  },
  "output": {
    "format": "markdown",
    "saveDiscussion": true,
    "discussionPath": "~/.agents-council/discussions"
  }
}
```

---

## API Reference

### AgentsCouncil Class

#### `start(): Promise<void>`

Start the Agents Council MCP server.

#### `summon(agent: string): Promise<void>`

Summon a specific agent to the council.

**Agents:**
- `claude` - Claude Code
- `codex` - OpenAI Codex
- `qwen` - Qwen Code
- `gemini` - Gemini CLI

#### `discuss(options: DiscussionOptions): Promise<DiscussionResult>`

Start a multi-agent discussion.

**Options:**
```typescript
interface DiscussionOptions {
  topic: string;
  context: string;
  agents: string[];
  roles?: Record<string, string>;
  ragContext?: boolean | RAGOptions;
  output?: 'markdown' | 'json';
  timeout?: number;
}
```

#### `monitor(): Promise<void>`

Open the Council Hall desktop app for monitoring.

#### `getStatus(): Promise<CouncilStatus>`

Get current council status.

---

## Examples

### Example 1: Simple Multi-Agent Chat

```typescript
import { AgentsCouncil } from 'qwenclaw-agents-council';

const council = new AgentsCouncil();
await council.start();

// Start discussion
const result = await council.discuss({
  topic: "Best practices for API design",
  agents: ['claude', 'qwen'],
});

console.log(result.summary);
```

### Example 2: Code Review with RAG

```typescript
const council = new AgentsCouncil();

const result = await council.discuss({
  topic: "Code Review",
  context: "Review this PR for security issues",
  agents: ['claude', 'codex'],
  ragContext: {
    searchQuery: "security best practices API",
    topK: 5,
    includeInContext: true,
  },
});

// Access RAG-retrieved documents
console.log(result.ragDocuments);
```

### Example 3: Architecture Design Session

```typescript
const council = new AgentsCouncil();

const result = await council.discuss({
  topic: "Design scalable microservices",
  context: "We need to handle 1M concurrent users",
  agents: ['claude', 'codex', 'qwen'],
  roles: {
    claude: 'Architecture expert',
    codex: 'Implementation expert',
    qwen: 'Testing expert',
  },
  output: 'markdown',
  ragContext: {
    documents: ['microservices-patterns.md', 'scaling-guide.md'],
  },
});

// Save discussion
await council.saveDiscussion(result, 'architecture-session.md');
```

---

## Troubleshooting

### Issue: "Council MCP server not found"

**Solution:**
```bash
# Install agents-council globally
npm install -g agents-council

# Or add MCP server manually
claude mcp add council npx agents-council@latest mcp
```

### Issue: "RAG context not shared"

**Solution:**
```json
// In council config
{
  "rag": {
    "shareAcrossAgents": true
  }
}
```

### Issue: "Desktop app not launching"

**Solution:**
```bash
# Install desktop dependencies
cd agents-council
bun install

# Launch desktop
council desktop
```

---

## Resources

- **Agents Council:** https://github.com/MrLesk/agents-council
- **MCP Protocol:** https://modelcontextprotocol.io/
- **QwenClaw Docs:** `README.md` in qwenclaw directory

---

## License

MIT License - See LICENSE file for details.

---

**Agents Council + Full RAG integration ready for QwenClaw!** 🏛️🤖