Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.profclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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: '...' };
  },
});