diegosouzapw 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
# 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
{
"platform": "whatsapp",
"chatId": "123456789",
"environment": "local"
}
Returns: Agent role, enabled skills, allowed tools, base prompt
ai_first_list_agents
{
"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:
- Get all context rules sorted by priority (highest first)
- Match rules against context (platform, chat, environment)
- Apply skill overrides from matching rules
- 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 skillsopencode.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
- Via Dashboard: Agents tab → Add New Agent
- Via API: POST
/api/agentswith agent definition - Via Seed: Update
data/seeds/agents.ts
Adding Skills to an Agent
- Via Dashboard: Click agent → Edit Skills → Select skills
- Via API: PUT
/api/agents/:id/skillswith skill names array
Creating Context Rules
For chat-specific agent:
{
"contextType": "chat",
"contextId": "120363406740668957",
"agentId": "specialized-agent",
"priority": 100
}
For platform-wide agent:
{
"contextType": "platform",
"contextId": "whatsapp",
"agentId": "communicator",
"priority": 50
}
Troubleshooting
Agent not appearing
- Check if agent is enabled:
GET /api/agents/:id - Verify database connection
- Check logs for errors
Skills not syncing
- Run
npm run agents:sync -- --verbose --dry-run - Check skill source directory exists
- Verify skill is assigned to agent
Context not resolving
- Check context rules:
GET /api/agents/context-rules - Verify rule priorities
- Test with:
POST /api/agents/resolve-context