name: agent-registry description: Guide for managing the Agent Registry - database-backed agent configuration system. Use when asked to "configure agents", "manage skills", "set tool permissions", "create context rules", or when working with agent assignments per platform/chat. Covers dashboard UI, API endpoints, CLI commands, and MCP tools.

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

Context Types

Default Agents

API Endpoints

All endpoints require authentication via JWT token.

Agent CRUD

Skills

Tools

Context Rules

Operations

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:

{
  "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

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