Agents

Agents are the core building block of Cortex. Each agent has a name, a system prompt (its "soul"), a set of capabilities, and an assigned LLM. Agents can be executed, delegated to, and self-improved.

Base path: /api/agents

All endpoints require Authorization: Bearer <token>.

List Agents

GET /api/agents

Returns all agents visible to the authenticated user.

Query parameters:

Parameter	Type	Description
`category`	string	Filter by category (e.g. `development`, `qa`, `research`)
`status`	string	Filter by status: `active`, `inactive`, `draft`
`search`	string	Full-text search on name and description
`limit`	number	Default `20`, max `100`
`offset`	number	Default `0`

Response:

json

{
  "success": true,
  "data": [
    {
      "id": "ag_01J...",
      "name": "qa-tester",
      "displayName": "QA Tester",
      "description": "Validates code and reports issues",
      "category": "qa",
      "model": "claude-sonnet-4-6",
      "status": "active",
      "capabilities": ["code_review", "test_generation"],
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 47 }
}

curl:

bash

curl "https://api.cortex.acrobi.com/api/agents?category=development&status=active" \
  -H "Authorization: Bearer <token>"

Create Agent

POST /api/agents

Request body:

json

{
  "name": "backend-coder",
  "displayName": "Backend Coder",
  "description": "Implements backend features in TypeScript",
  "category": "development",
  "model": "claude-sonnet-4-6",
  "systemPrompt": "You are a senior backend engineer...",
  "capabilities": ["code_generation", "database_design"],
  "status": "active"
}

Field	Type	Required	Description
`name`	string	Yes	Unique kebab-case identifier
`displayName`	string	Yes	Human-readable name
`description`	string	No	Short description
`category`	string	Yes	`business`, `development`, `qa`, `research`, `operations`, `specialized`
`model`	string	No	LLM model ID (defaults to org default)
`systemPrompt`	string	No	Full system prompt text
`capabilities`	string[]	No	List of capability identifiers
`status`	string	No	`active` (default), `inactive`, `draft`

Response: 201 Created

json

{
  "success": true,
  "data": {
    "id": "ag_01J...",
    "name": "backend-coder",
    "displayName": "Backend Coder",
    "createdAt": "2026-04-03T12:00:00Z"
  }
}

curl:

bash

curl -X POST "https://api.cortex.acrobi.com/api/agents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-coder",
    "displayName": "Backend Coder",
    "category": "development",
    "model": "claude-sonnet-4-6"
  }'

Get Agent

GET /api/agents/:name

Returns full agent detail including system prompt and capabilities.

Response:

json

{
  "success": true,
  "data": {
    "id": "ag_01J...",
    "name": "backend-coder",
    "displayName": "Backend Coder",
    "description": "Implements backend features",
    "category": "development",
    "model": "claude-sonnet-4-6",
    "systemPrompt": "You are a senior backend engineer...",
    "capabilities": ["code_generation"],
    "status": "active",
    "isSystem": false,
    "createdAt": "2026-04-03T12:00:00Z",
    "updatedAt": "2026-04-03T12:00:00Z"
  }
}

Update Agent

PATCH /api/agents/:name

Partial update — only include fields you want to change.

Request body:

json

{
  "displayName": "Senior Backend Coder",
  "model": "claude-opus-4-6",
  "status": "active"
}

Response: 200 OK — returns updated agent object.

Delete Agent

DELETE /api/agents/:name

Deletes an agent. System agents (isSystem: true) cannot be deleted.

Response:

json

{ "success": true }

WARNING

This permanently deletes the agent and its execution history. Use status: "inactive" to soft-disable instead.

List Agent Skills

GET /api/agents/:name/skills

Returns all skills currently assigned to the agent.

Response:

json

{
  "success": true,
  "data": [
    {
      "id": "sk_01J...",
      "name": "web-search",
      "description": "Search the web for information",
      "assignedAt": "2026-04-01T10:00:00Z"
    }
  ]
}

Assign Skill

POST /api/agents/:name/skills

Request body:

json

{ "skillId": "sk_01J..." }

Response: 201 Created

json

{ "success": true }

Unassign Skill

DELETE /api/agents/:name/skills/:skillId

Response:

json

{ "success": true }

Update Agent SOUL

The SOUL is the agent's core identity — its values, communication style, and behavioral constraints. This is separate from the task-specific system prompt.

PATCH /api/agents/:name/soul

Request body:

json

{
  "soul": "You are honest, direct, and always cite your sources. You admit uncertainty rather than fabricating answers. You ask clarifying questions when requirements are ambiguous."
}

Response: 200 OK — returns updated agent object.

Execute Agent

Triggers the agent to run a task. The agent will receive the input, execute using its configured LLM, and persist the result.

POST /api/agents/:name/execute

Request body:

json

{
  "taskId": "tk_01J...",
  "input": "Implement a pagination utility for the users table",
  "context": {
    "projectId": "proj_01J...",
    "priority": "high"
  }
}

Field	Type	Required	Description
`taskId`	string	No	Associated kanban task ID
`input`	string	Yes	The task instruction
`context`	object	No	Additional context key-values

Response: 200 OK

json

{
  "success": true,
  "data": {
    "executionId": "ex_01J...",
    "agentName": "backend-coder",
    "status": "running",
    "startedAt": "2026-04-03T12:01:00Z"
  }
}

curl:

bash

curl -X POST "https://api.cortex.acrobi.com/api/agents/backend-coder/execute" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"input": "Implement pagination for the users table"}'

Delegate to Another Agent

Delegate a subtask from one agent to another.

POST /api/agents/:name/delegate

Request body:

json

{
  "toAgent": "qa-tester",
  "taskId": "tk_01J...",
  "instruction": "Validate the pagination implementation for edge cases",
  "context": { "codeRef": "src/lib/paginate.ts" }
}

Response: 200 OK

json

{
  "success": true,
  "data": {
    "delegationId": "dl_01J...",
    "fromAgent": "backend-coder",
    "toAgent": "qa-tester",
    "status": "accepted"
  }
}

List All Executions

GET /api/agents/executions

Returns executions across all agents.

Query parameters: status, agentName, limit, offset

Response:

json

{
  "success": true,
  "data": [
    {
      "id": "ex_01J...",
      "agentName": "backend-coder",
      "taskId": "tk_01J...",
      "status": "completed",
      "startedAt": "2026-04-03T12:01:00Z",
      "completedAt": "2026-04-03T12:03:14Z",
      "durationMs": 134000
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 312 }
}

List Executions for Agent

GET /api/agents/:name/executions

Same shape as above, filtered to the specified agent.

Get Execution Detail

GET /api/agents/:name/executions/:id

Response:

json

{
  "success": true,
  "data": {
    "id": "ex_01J...",
    "agentName": "backend-coder",
    "taskId": "tk_01J...",
    "input": "Implement pagination...",
    "output": "Here is the pagination utility:\n\n```ts\n...",
    "status": "completed",
    "tokensUsed": 1842,
    "model": "claude-sonnet-4-6",
    "startedAt": "2026-04-03T12:01:00Z",
    "completedAt": "2026-04-03T12:03:14Z",
    "durationMs": 134000,
    "qualityGates": {
      "selfTest": "passed",
      "qaReview": "passed"
    }
  }
}

Agent Metrics

GET /api/agents/:name/metrics

Returns performance and usage statistics for the agent.

Query parameters: period (7d, 30d, 90d — default 30d)

Response:

json

{
  "success": true,
  "data": {
    "agentName": "backend-coder",
    "period": "30d",
    "executions": {
      "total": 84,
      "completed": 79,
      "failed": 3,
      "running": 2,
      "successRate": 0.94
    },
    "performance": {
      "avgDurationMs": 98400,
      "p50DurationMs": 82000,
      "p95DurationMs": 241000
    },
    "tokens": {
      "total": 198420,
      "avgPerExecution": 2362
    }
  }
}

Self-Improve

Triggers the agent's self-improvement loop — the agent reviews its recent executions, identifies patterns of failure or inefficiency, and updates its own system prompt.

POST /api/agents/:name/self-improve

Request body:

json

{
  "lookbackExecutions": 20,
  "focusArea": "error handling"
}

Response: 200 OK

json

{
  "success": true,
  "data": {
    "improved": true,
    "changesSummary": "Added explicit error handling guidance and clarified scope boundaries",
    "previousPromptHash": "sha256:abc...",
    "newPromptHash": "sha256:def..."
  }
}

Agents ​

List Agents ​

Create Agent ​

Get Agent ​

Update Agent ​

Delete Agent ​

List Agent Skills ​

Assign Skill ​

Unassign Skill ​

Update Agent SOUL ​

Execute Agent ​

Delegate to Another Agent ​

List All Executions ​

List Executions for Agent ​

Get Execution Detail ​

Agent Metrics ​

Self-Improve ​

Agents

List Agents

Create Agent

Get Agent

Update Agent

Delete Agent

List Agent Skills

Assign Skill

Unassign Skill

Update Agent SOUL

Execute Agent

Delegate to Another Agent

List All Executions

List Executions for Agent

Get Execution Detail

Agent Metrics

Self-Improve