agent-registry

# Agent Registry Management

## Overview

The Agent Registry is a database-backed system for managing AI agent configurations. It replaces file-based configuration with a centralized, dynamic approach that supports:

- **Agent definitions** - Name, model, base prompt, enabled status
- **Skill assignments** - Which skills each agent has access to
- **Tool permissions** - Allow/deny patterns for MCP tools
- **Context rules** - Agent selection based on platform, chat, environment

## Quick Reference

### Dashboard UI

Access the Agents tab in the dashboard at `http://localhost/` → Management → Agents

Features:

- View all agents with stats (total, enabled, skills, context rules)
- Edit agent details (name, description, model, prompt)
- Manage skills (checkbox list of available skills)
- Configure tool patterns (allow/deny lists)
- View agent details with all configurations

### CLI Commands

```bash
# Sync database config to filesystem (for OpenCode)
npm run agents:sync

# Sync with verbose output
npm run agents:sync -- --verbose

# Dry run (show what would change)
npm run agents:sync -- --dry-run

# Sync for specific environment
npm run agents:sync -- --env prod

# Seed default agents
npm run agents:seed

# Force re-seed (overwrites existing)
npm run agents:seed:force

# Run database migration
npm run db:migrate
```

### MCP Tools

Two MCP tools are available for agents to self-discover their capabilities:

**ai_first_get_agent_context**

```json
{
  "platform": "whatsapp",
  "chatId": "123456789",
  "environment": "local"
}
```

Returns: Agent role, enabled skills, allowed tools, base prompt

**ai_first_list_agents**

```json
{
  "includeDetails": true
}
```

Returns: All registered agents with optional skill/tool details

## Database Schema

### Tables

| Table           | Purpose                                                   |
| --------------- | --------------------------------------------------------- |
| `agents`        | Core agent definitions (id, name, model, prompt, enabled) |
| `agent_skills`  | Skills assigned to each agent                             |
| `agent_tools`   | Tool allow/deny patterns per agent                        |
| `context_rules` | Rules for agent selection by context                      |

### Context Types

| Type          | Context ID                     | Purpose                                  |
| ------------- | ------------------------------ | ---------------------------------------- |
| `default`     | null                           | Fallback agent when no other rules match |
| `platform`    | whatsapp/slack/opencode/cursor | Platform-specific agent                  |
| `chat`        | Chat/Channel ID                | Chat-specific agent assignment           |
| `channel`     | Slack channel name             | Channel-specific agent                   |
| `environment` | local/prod                     | Environment-specific skill overrides     |

## Default Agents

| Agent        | Mode        | Skills                                                                                         | Description                                     |
| ------------ | ----------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| pm-assistant | primary     | jira-management, workflow-management, presentation-updates, message-scheduling, tool-discovery | JIRA, meetings, workflows, project management   |
| communicator | specialized | slack-formatting, whatsapp-messages                                                            | Slack/WhatsApp messaging with proper formatting |
| scheduler    | specialized | message-scheduling, tool-discovery                                                             | Calendar management, reminders                  |
| explorer     | specialized | project-architecture, tool-discovery                                                           | Fast codebase exploration                       |

## API Endpoints

All endpoints require authentication via JWT token.

### Agent CRUD

| Method | Endpoint                 | Description             |
| ------ | ------------------------ | ----------------------- |
| GET    | `/api/agents`            | List all agents         |
| GET    | `/api/agents/stats`      | Get registry statistics |
| GET    | `/api/agents/:id`        | Get agent with details  |
| POST   | `/api/agents`            | Create new agent        |
| PATCH  | `/api/agents/:id`        | Update agent            |
| DELETE | `/api/agents/:id`        | Delete agent            |
| POST   | `/api/agents/:id/toggle` | Toggle enabled status   |

### Skills

| Method | Endpoint                       | Description               |
| ------ | ------------------------------ | ------------------------- |
| GET    | `/api/agents/:id/skills`       | Get agent's skills        |
| PUT    | `/api/agents/:id/skills`       | Replace agent's skills    |
| GET    | `/api/agents/available-skills` | List all available skills |

### Tools

| Method | Endpoint                | Description                  |
| ------ | ----------------------- | ---------------------------- |
| GET    | `/api/agents/:id/tools` | Get agent's tool patterns    |
| PUT    | `/api/agents/:id/tools` | Set tool allow/deny patterns |

### Context Rules

| Method | Endpoint                        | Description            |
| ------ | ------------------------------- | ---------------------- |
| GET    | `/api/agents/context-rules`     | List all context rules |
| POST   | `/api/agents/context-rules`     | Create context rule    |
| DELETE | `/api/agents/context-rules/:id` | Delete context rule    |

### Operations

| Method | Endpoint                      | Description               |
| ------ | ----------------------------- | ------------------------- |
| POST   | `/api/agents/sync`            | Trigger filesystem sync   |
| POST   | `/api/agents/resolve-context` | Resolve agent for context |

## Context Resolution

When resolving an agent for a request:

1. Get all context rules sorted by priority (highest first)
2. Match rules against context (platform, chat, environment)
3. Apply skill overrides from matching rules
4. Return agent with effective skills and tools

Priority order: chat-specific > channel-specific > platform-specific > environment > default

## Filesystem Sync

For OpenCode/Cursor compatibility, agent configurations are synced to:

- `.claude/skills/` - Skill directories for enabled skills
- `opencode.json` - Model configuration (future)

The sync runs:

- On demand via `npm run agents:sync`
- Before OpenCode starts (in Docker entrypoint)
- Via dashboard "Sync" button

## Extending

### Adding a New Agent

1. Via Dashboard: Agents tab → Add New Agent
2. Via API: POST `/api/agents` with agent definition
3. Via Seed: Update `data/seeds/agents.ts`

### Adding Skills to an Agent

1. Via Dashboard: Click agent → Edit Skills → Select skills
2. Via API: PUT `/api/agents/:id/skills` with skill names array

### Creating Context Rules

For chat-specific agent:

```json
{
  "contextType": "chat",
  "contextId": "120363406740668957",
  "agentId": "specialized-agent",
  "priority": 100
}
```

For platform-wide agent:

```json
{
  "contextType": "platform",
  "contextId": "whatsapp",
  "agentId": "communicator",
  "priority": 50
}
```

## Troubleshooting

### Agent not appearing

1. Check if agent is enabled: `GET /api/agents/:id`
2. Verify database connection
3. Check logs for errors

### Skills not syncing

1. Run `npm run agents:sync -- --verbose --dry-run`
2. Check skill source directory exists
3. Verify skill is assigned to agent

### Context not resolving

1. Check context rules: `GET /api/agents/context-rules`
2. Verify rule priorities
3. Test with: `POST /api/agents/resolve-context`