Ra
943d8ad4d7
- Fixed Task.new/3 to handle both maps and keyword lists - Added robust inbox existence checking in find_available_agent - Ensure inbox creation during agent registration and task assignment - Add helper function ensure_inbox_exists to avoid crashes
288 lines
9.1 KiB
Markdown
288 lines
9.1 KiB
Markdown
# AgentCoordinator
|
|
|
|
A distributed task coordination system for AI agents built with Elixir and NATS.
|
|
|
|
## Overview
|
|
|
|
AgentCoordinator is a centralized task management system designed to enable multiple AI agents (Claude Code, GitHub Copilot, etc.) to work collaboratively on the same codebase without conflicts. It provides:
|
|
|
|
- **Distributed Task Management**: Centralized task queue with agent-specific inboxes
|
|
- **Conflict Resolution**: File-level locking prevents agents from working on the same files
|
|
- **Real-time Communication**: NATS messaging for instant coordination
|
|
- **Persistent Storage**: Event sourcing with configurable retention policies
|
|
- **MCP Integration**: Model Context Protocol server for agent communication
|
|
- **Fault Tolerance**: Elixir supervision trees ensure system resilience
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
|
│ AI Agent 1 │ │ AI Agent 2 │ │ AI Agent N │
|
|
│ (Claude Code) │ │ (Copilot) │ │ ... │
|
|
└─────────┬───────┘ └─────────┬────────┘ └─────────┬───────┘
|
|
│ │ │
|
|
└──────────────────────┼───────────────────────┘
|
|
│
|
|
┌─────────────┴──────────────┐
|
|
│ MCP Server Interface │
|
|
└─────────────┬──────────────┘
|
|
│
|
|
┌─────────────┴──────────────┐
|
|
│ AgentCoordinator │
|
|
│ │
|
|
│ ┌──────────────────────┐ │
|
|
│ │ Task Registry │ │
|
|
│ │ ┌──────────────┐ │ │
|
|
│ │ │ Agent Inbox │ │ │
|
|
│ │ │ Agent Inbox │ │ │
|
|
│ │ │ Agent Inbox │ │ │
|
|
│ │ └──────────────┘ │ │
|
|
│ └──────────────────────┘ │
|
|
│ │
|
|
│ ┌──────────────────────┐ │
|
|
│ │ NATS Messaging │ │
|
|
│ └──────────────────────┘ │
|
|
│ │
|
|
│ ┌──────────────────────┐ │
|
|
│ │ Persistence │ │
|
|
│ │ (JetStream) │ │
|
|
│ └──────────────────────┘ │
|
|
└────────────────────────────┘
|
|
```
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Elixir 1.16+ and Erlang/OTP 28+
|
|
- NATS server (with JetStream enabled)
|
|
|
|
### Setup
|
|
|
|
1. **Install Dependencies**
|
|
```bash
|
|
mix deps.get
|
|
```
|
|
|
|
2. **Start NATS Server**
|
|
```bash
|
|
# Using Docker
|
|
docker run -p 4222:4222 -p 8222:8222 nats:latest -js
|
|
|
|
# Or install locally and run
|
|
nats-server -js
|
|
```
|
|
|
|
3. **Configure Environment**
|
|
```bash
|
|
export NATS_HOST=localhost
|
|
export NATS_PORT=4222
|
|
```
|
|
|
|
4. **Start the Application**
|
|
```bash
|
|
iex -S mix
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Command Line Interface
|
|
|
|
```bash
|
|
# Register an agent
|
|
mix run -e "AgentCoordinator.CLI.main([\"register\", \"CodeBot\", \"coding\", \"testing\"])"
|
|
|
|
# Create a task
|
|
mix run -e "AgentCoordinator.CLI.main([\"create-task\", \"Fix login bug\", \"User login fails\", \"priority=high\"])"
|
|
|
|
# View task board
|
|
mix run -e "AgentCoordinator.CLI.main([\"board\"])"
|
|
```
|
|
|
|
### MCP Integration
|
|
|
|
Available MCP tools for agents:
|
|
- `register_agent` - Register a new agent
|
|
- `create_task` - Create a new task
|
|
- `get_next_task` - Get next task for agent
|
|
- `complete_task` - Mark current task complete
|
|
- `get_task_board` - View all agent statuses
|
|
- `heartbeat` - Send agent heartbeat
|
|
|
|
## Connecting to GitHub Copilot
|
|
|
|
### Step 1: Start the MCP Server
|
|
|
|
The AgentCoordinator MCP server needs to be running and accessible via stdio. Here's how to set it up:
|
|
|
|
1. **Create MCP Server Launcher Script**
|
|
```bash
|
|
# Create a launcher script for the MCP server
|
|
cat > mcp_launcher.sh << 'EOF'
|
|
#!/bin/bash
|
|
cd /home/ra/agent_coordinator
|
|
export MIX_ENV=prod
|
|
mix run --no-halt -e "
|
|
# Start the application
|
|
Application.ensure_all_started(:agent_coordinator)
|
|
|
|
# Start MCP stdio interface
|
|
IO.puts(\"MCP server started...\")
|
|
|
|
# Read JSON-RPC messages from stdin and send responses to stdout
|
|
spawn(fn ->
|
|
Stream.repeatedly(fn -> IO.read(:stdio, :line) end)
|
|
|> Stream.take_while(&(&1 != :eof))
|
|
|> Enum.each(fn line ->
|
|
case String.trim(line) do
|
|
\"\" -> :ok
|
|
json_line ->
|
|
try do
|
|
request = Jason.decode!(json_line)
|
|
response = AgentCoordinator.MCPServer.handle_mcp_request(request)
|
|
IO.puts(Jason.encode!(response))
|
|
rescue
|
|
e ->
|
|
error_response = %{
|
|
\"jsonrpc\" => \"2.0\",
|
|
\"id\" => Map.get(Jason.decode!(json_line), \"id\", null),
|
|
\"error\" => %{\"code\" => -32603, \"message\" => Exception.message(e)}
|
|
}
|
|
IO.puts(Jason.encode!(error_response))
|
|
end
|
|
end
|
|
end)
|
|
end)
|
|
|
|
# Keep process alive
|
|
Process.sleep(:infinity)
|
|
"
|
|
EOF
|
|
chmod +x mcp_launcher.sh
|
|
```
|
|
|
|
### Step 2: Configure VS Code for MCP
|
|
|
|
1. **Install Required Extensions**
|
|
- Make sure you have the latest GitHub Copilot extension
|
|
- Install any MCP-related VS Code extensions if available
|
|
|
|
2. **Create MCP Configuration**
|
|
Create or update your VS Code settings to include the MCP server:
|
|
|
|
```json
|
|
// In your VS Code settings.json or workspace settings
|
|
{
|
|
"github.copilot.advanced": {
|
|
"mcp": {
|
|
"servers": {
|
|
"agent-coordinator": {
|
|
"command": "/home/ra/agent_coordinator/mcp_launcher.sh",
|
|
"args": [],
|
|
"env": {}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Step 3: Alternative Direct Integration
|
|
|
|
If VS Code MCP integration isn't available yet, you can create a VS Code extension to bridge the gap:
|
|
|
|
1. **Create Extension Scaffold**
|
|
```bash
|
|
mkdir agent-coordinator-extension
|
|
cd agent-coordinator-extension
|
|
npm init -y
|
|
|
|
# Create package.json for VS Code extension
|
|
cat > package.json << 'EOF'
|
|
{
|
|
"name": "agent-coordinator",
|
|
"displayName": "Agent Coordinator",
|
|
"description": "Integration with AgentCoordinator MCP server",
|
|
"version": "0.1.0",
|
|
"engines": { "vscode": "^1.74.0" },
|
|
"categories": ["Other"],
|
|
"activationEvents": ["*"],
|
|
"main": "./out/extension.js",
|
|
"contributes": {
|
|
"commands": [
|
|
{
|
|
"command": "agentCoordinator.registerAgent",
|
|
"title": "Register as Agent"
|
|
},
|
|
{
|
|
"command": "agentCoordinator.getNextTask",
|
|
"title": "Get Next Task"
|
|
},
|
|
{
|
|
"command": "agentCoordinator.viewTaskBoard",
|
|
"title": "View Task Board"
|
|
}
|
|
]
|
|
},
|
|
"devDependencies": {
|
|
"@types/vscode": "^1.74.0",
|
|
"typescript": "^4.9.0"
|
|
}
|
|
}
|
|
EOF
|
|
```
|
|
|
|
### Step 4: Direct Command Line Usage
|
|
|
|
For immediate use, you can interact with the MCP server directly:
|
|
|
|
1. **Start the Server**
|
|
```bash
|
|
cd /home/ra/agent_coordinator
|
|
iex -S mix
|
|
```
|
|
|
|
2. **In another terminal, use the MCP tools**
|
|
```bash
|
|
# Test MCP server directly
|
|
cd /home/ra/agent_coordinator
|
|
mix run demo_mcp_server.exs
|
|
```
|
|
|
|
### Step 5: Production Deployment
|
|
|
|
1. **Create Systemd Service for MCP Server**
|
|
```bash
|
|
sudo tee /etc/systemd/system/agent-coordinator-mcp.service > /dev/null << EOF
|
|
[Unit]
|
|
Description=Agent Coordinator MCP Server
|
|
After=network.target nats.service
|
|
Requires=nats.service
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=ra
|
|
WorkingDirectory=/home/ra/agent_coordinator
|
|
Environment=MIX_ENV=prod
|
|
Environment=NATS_HOST=localhost
|
|
Environment=NATS_PORT=4222
|
|
ExecStart=/usr/bin/mix run --no-halt
|
|
Restart=always
|
|
RestartSec=5
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable agent-coordinator-mcp
|
|
sudo systemctl start agent-coordinator-mcp
|
|
```
|
|
|
|
2. **Check Status**
|
|
```bash
|
|
sudo systemctl status agent-coordinator-mcp
|
|
sudo journalctl -fu agent-coordinator-mcp
|
|
```
|
|
|