Skip to main content
The agents API surfaces the registered AI agent adapters and their runtime status. Agents are the execution backends that process tasks - each adapter type (Claude Code, custom, etc.) exposes capabilities, health, and stats.

​
GET /api/agents

List all active agent adapters with health and execution statistics. 
curl http://localhost:3000/api/agents \
  --cookie "profclaw_session=<token>"
Response 200 
{
  "agents": [
    {
      "type": "claude-code",
      "name": "Claude Code",
      "description": "Autonomous coding agent powered by Claude",
      "capabilities": ["code", "git", "terminal", "file-ops"],
      "configured": true,
      "healthy": true,
      "lastActivity": "2026-03-12T10:30:00Z",
      "stats": {
        "completed": 142,
        "failed": 3,
        "avgDuration": 45230
      }
    }
  ]
}
Response fields
FieldTypeDescription
typestringAdapter type identifier
namestringDisplay name
descriptionstringHuman-readable description
capabilitiesstring[]List of capability tags
configuredbooleanAdapter has required config
healthybooleanLast health check passed
lastActivityISO stringTimestamp of last task completion
stats.completednumberTotal tasks completed
stats.failednumberTotal tasks failed
stats.avgDurationnumberAverage execution time in ms

​
GET /api/agents/types

List registered adapter type identifiers. 
curl http://localhost:3000/api/agents/types
Response 200 
{
  "types": ["claude-code", "openai-assistant", "custom"]
}

​
Agent Adapter Interface

Adapters are registered via getAgentRegistry() from src/adapters/registry.ts. Each adapter implements: 
interface AgentAdapter {
  type: string;
  name: string;
  description: string;
  capabilities: string[];
  healthCheck(): Promise<{ healthy: boolean; latencyMs?: number; message?: string }>;
  execute(task: Task): Promise<TaskResult>;
}

​
Health Checks

Agent health is checked on demand when GET /api/agents is called. Each adapter runs its own healthCheck() which typically:
  1. Verifies API key is present
  2. Makes a lightweight probe request to the underlying AI service
  3. Returns healthy: boolean and latencyMs
If all adapters are unhealthy, the overall system health degrades to degraded or unhealthy (visible at GET /api/health).

​
Registering Custom Adapters

Custom adapters are registered programmatically at startup: 
import { getAgentRegistry } from './adapters/registry.js';

const registry = getAgentRegistry();
registry.register({
  type: 'my-agent',
  name: 'My Custom Agent',
  description: 'Handles specialized tasks',
  capabilities: ['custom-domain'],
  async healthCheck() {
    return { healthy: true };
  },
  async execute(task) {
    // process task
    return { success: true, output: '...' };
  },
});