Files

T

jcfs 56c73914f8 Add AGENTS.md with agent guidelines and API documentation

Includes:
- Agent architecture overview
- Available agent types (Augment Agent)
- ACP (Agent Communication Protocol) message format and types
- Complete REST API reference for all endpoints:
  - Health, Boards, Columns, Tasks APIs
  - Agents API (launch, stop, status, logs, types)
  - Orchestrator API (queue, trigger, task control)
- Session resumption guide
- Error response format
- Custom agent creation guide
- Development notes

Note: API docs must be updated when endpoints change.

2026-01-10 10:16:58 +00:00

12 KiB

Raw Blame History

Kandev Agents Guide

⚠️ IMPORTANT: API documentation in this file must be updated whenever the API changes. When modifying any endpoint, request/response types, or ACP messages, update this document accordingly.

Overview

Kandev uses Docker containers to run AI agents that execute tasks from the Kanban board. Agents communicate with the backend using the Agent Communication Protocol (ACP), a JSON-based streaming protocol.

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   HTTP Client   │────▶│  Kandev Backend  │────▶│ Docker Container│
│  (Frontend/CLI) │     │   (Port 8080)    │     │   (AI Agent)    │
└─────────────────┘     └────────┬─────────┘     └────────┬────────┘
                                 │                        │
                                 │◀───────────────────────┘
                                 │    ACP Messages (stdout)
                                 ▼
                        ┌──────────────────┐
                        │   Event Bus      │
                        │ (In-Memory)      │
                        └──────────────────┘

Available Agent Types

Augment Agent (`augment-agent`)

The primary AI coding agent powered by Auggie CLI.

Property	Value
Image	`kandev/augment-agent:latest`
Working Directory	`/workspace`
Memory Limit	4096 MB
CPU Cores	2.0
Timeout	1 hour
Capabilities	code_generation, code_review, refactoring, testing, shell_execution

Required Environment Variables:

AUGMENT_SESSION_AUTH - Augment CLI session authentication (from ~/.augment/session.json)
TASK_DESCRIPTION - The task for the agent to execute

Optional Environment Variables:

AUGGIE_SESSION_ID - Resume a previous session (for follow-up tasks)

Mounted Volumes:

{workspace} → /workspace - The project directory
{augment_sessions} → /root/.augment/sessions - Session persistence

Agent Communication Protocol (ACP)

Agents communicate by writing JSON messages to stdout. Each line must be a complete JSON object.

Message Format

{
  "type": "progress",
  "agent_id": "uuid",
  "task_id": "uuid",
  "timestamp": "2026-01-10T12:00:00Z",
  "data": { ... }
}

Message Types

`progress` - Progress Updates

{
  "type": "progress",
  "data": {
    "progress": 50,
    "message": "Analyzing codebase...",
    "current_file": "src/main.go",
    "files_processed": 10,
    "total_files": 20
  }
}

`log` - Log Messages

{
  "type": "log",
  "data": {
    "level": "info",
    "message": "Starting code review",
    "metadata": { "file": "main.go" }
  }
}

Levels: debug, info, warn, error

`result` - Task Completion

{
  "type": "result",
  "data": {
    "status": "completed",
    "summary": "Task completed successfully",
    "artifacts": [
      { "type": "report", "path": "/workspace/report.md" }
    ]
  }
}

Status: completed, failed, cancelled

`error` - Error Messages

{
  "type": "error",
  "data": {
    "error": "Failed to parse file",
    "file": "broken.go",
    "details": "syntax error on line 42"
  }
}

`status` - Agent Status Changes

{
  "type": "status",
  "data": {
    "status": "running",
    "message": "Agent initialized"
  }
}

Status: started, running, paused, stopped

`heartbeat` - Keep-Alive

{
  "type": "heartbeat",
  "data": {}
}

REST API Reference

Base URL: http://localhost:8080/api/v1

Health Check

GET /health

Response:

{
  "status": "ok"
}

Boards API

Create Board

POST /boards

Request:

{
  "name": "My Project",
  "description": "Project tasks"
}

Response: 201 Created

{
  "id": "uuid",
  "name": "My Project",
  "description": "Project tasks",
  "created_at": "2026-01-10T12:00:00Z",
  "updated_at": "2026-01-10T12:00:00Z"
}

List Boards

GET /boards

Response:

{
  "boards": [...],
  "total": 5
}

Get Board

GET /boards/:boardId

Update Board

PUT /boards/:boardId

Request:

{
  "name": "Updated Name",
  "description": "Updated description"
}

Delete Board

DELETE /boards/:boardId

Columns API

Create Column

POST /boards/:boardId/columns

Request:

{
  "name": "To Do",
  "position": 0,
  "state": "TODO"
}

Response: 201 Created

{
  "id": "uuid",
  "board_id": "uuid",
  "name": "To Do",
  "position": 0,
  "state": "TODO",
  "created_at": "2026-01-10T12:00:00Z"
}

List Columns

GET /boards/:boardId/columns

Get Column

GET /columns/:columnId

Tasks API

Create Task

POST /tasks

Request:

{
  "board_id": "uuid",
  "column_id": "uuid",
  "title": "Fix login bug",
  "description": "Users cannot login with email",
  "priority": 1,
  "agent_type": "augment-agent",
  "metadata": {}
}

Response: 201 Created

{
  "id": "uuid",
  "board_id": "uuid",
  "column_id": "uuid",
  "title": "Fix login bug",
  "description": "Users cannot login with email",
  "state": "TODO",
  "priority": 1,
  "agent_type": "augment-agent",
  "position": 0,
  "created_at": "2026-01-10T12:00:00Z",
  "updated_at": "2026-01-10T12:00:00Z",
  "metadata": {}
}

Get Task

GET /tasks/:taskId

Update Task

PUT /tasks/:taskId

Request (all fields optional):

{
  "title": "Updated title",
  "description": "Updated description",
  "priority": 2,
  "metadata": { "key": "value" }
}

Delete Task

DELETE /tasks/:taskId

Update Task State

PUT /tasks/:taskId/state

Request:

{
  "state": "IN_PROGRESS"
}

States: TODO, IN_PROGRESS, BLOCKED, COMPLETED, FAILED, CANCELLED

Move Task

PUT /tasks/:taskId/move

Request:

{
  "column_id": "uuid",
  "position": 0
}

List Tasks in Board

GET /boards/:boardId/tasks

Agents API

Launch Agent

POST /agents/launch

Request:

{
  "task_id": "uuid",
  "agent_type": "augment-agent",
  "workspace_path": "/path/to/project",
  "env": {
    "AUGMENT_SESSION_AUTH": "...",
    "TASK_DESCRIPTION": "Analyze this codebase"
  },
  "priority": 1,
  "metadata": {}
}

Response: 201 Created

{
  "id": "uuid",
  "task_id": "uuid",
  "agent_type": "augment-agent",
  "container_id": "docker-container-id",
  "status": "starting",
  "progress": 0,
  "started_at": "2026-01-10T12:00:00Z"
}

List Agents

GET /agents

Response:

{
  "agents": [...],
  "total": 3
}

Get Agent Status

GET /agents/:instanceId/status

Response:

{
  "id": "uuid",
  "task_id": "uuid",
  "agent_type": "augment-agent",
  "container_id": "docker-container-id",
  "status": "running",
  "progress": 50,
  "started_at": "2026-01-10T12:00:00Z",
  "finished_at": null,
  "exit_code": null,
  "error_message": ""
}

Agent statuses: starting, running, completed, failed, stopped

Get Agent Logs

GET /agents/:instanceId/logs?tail=100

Response:

{
  "logs": [
    {
      "timestamp": "2026-01-10T12:00:00Z",
      "message": "Starting agent...",
      "stream": "stdout"
    }
  ],
  "total": 50
}

Stop Agent

DELETE /agents/:instanceId

Request (optional body):

{
  "force": false,
  "reason": "User requested stop"
}

List Agent Types

GET /agents/types

Response:

{
  "types": [
    {
      "id": "augment-agent",
      "name": "Augment Coding Agent",
      "description": "Auggie CLI-powered autonomous coding agent",
      "image": "kandev/augment-agent",
      "capabilities": ["code_generation", "code_review", "refactoring", "testing", "shell_execution"],
      "enabled": true
    }
  ],
  "total": 1
}

Get Agent Type

GET /agents/types/:typeId

Orchestrator API

Base: /api/v1/orchestrator

Get Orchestrator Status

GET /orchestrator/status

Get Task Queue

GET /orchestrator/queue

Response:

{
  "tasks": [
    {
      "task_id": "uuid",
      "priority": 1,
      "queued_at": "2026-01-10T12:00:00Z"
    }
  ],
  "total": 5
}

Trigger Task Execution

POST /orchestrator/trigger

Request:

{
  "task_id": "uuid",
  "force": false
}

Start Task

POST /orchestrator/tasks/:taskId/start

Stop Task

POST /orchestrator/tasks/:taskId/stop

Pause Task

POST /orchestrator/tasks/:taskId/pause

Resume Task

POST /orchestrator/tasks/:taskId/resume

Get Task Execution Status

GET /orchestrator/tasks/:taskId/status

Get Task Logs

GET /orchestrator/tasks/:taskId/logs

Get Task Artifacts

GET /orchestrator/tasks/:taskId/artifacts

Session Resumption

Agents can resume previous sessions for follow-up tasks:

First task - Launch agent normally, session ID stored in task metadata
Get session ID from task: GET /tasks/:taskId → metadata.auggie_session_id
Follow-up task - Launch with AUGGIE_SESSION_ID env var

Example:

# Get session ID from completed task
SESSION_ID=$(curl -s http://localhost:8080/api/v1/tasks/$TASK_ID | jq -r '.metadata.auggie_session_id')

# Launch follow-up with session resumption
curl -X POST http://localhost:8080/api/v1/agents/launch \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "'$NEW_TASK_ID'",
    "agent_type": "augment-agent",
    "workspace_path": "/path/to/project",
    "env": {
      "AUGMENT_SESSION_AUTH": "...",
      "AUGGIE_SESSION_ID": "'$SESSION_ID'",
      "TASK_DESCRIPTION": "What was my previous question?"
    }
  }'

Error Responses

All error responses follow this format:

{
  "error": "error_code",
  "message": "Human readable message",
  "details": "Additional details",
  "http_status": 400
}

Common error codes:

bad_request (400) - Invalid request body or parameters
not_found (404) - Resource not found
validation_error (400) - Validation failed
internal_error (500) - Server error

Creating Custom Agents

To create a new agent type:

Create Dockerfile in backend/dockerfiles/your-agent/
Implement ACP - Write JSON messages to stdout
Register agent in backend/internal/agent/registry/defaults.go
Build image: docker build -t kandev/your-agent:latest .

Example agent script:

#!/bin/bash
echo '{"type":"status","agent_id":"'$AGENT_ID'","task_id":"'$TASK_ID'","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","data":{"status":"started"}}'
echo '{"type":"progress","agent_id":"'$AGENT_ID'","task_id":"'$TASK_ID'","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","data":{"progress":50,"message":"Working..."}}'
# Do work here
echo '{"type":"result","agent_id":"'$AGENT_ID'","task_id":"'$TASK_ID'","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","data":{"status":"completed","summary":"Done!"}}'

Development Notes

Running Locally

cd backend
make build
./bin/kandev

Running Tests

cd backend
go test ./...

Environment Variables

Variable	Default	Description
`KANDEV_DB_PATH`	`./kandev.db`	SQLite database path
`PORT`	`8080`	HTTP server port

Last Updated: 2026-01-10

12 KiB Raw Blame History

Kandev Agents Guide

Overview

Architecture

Available Agent Types

Augment Agent (augment-agent)

Agent Communication Protocol (ACP)

Message Format

Message Types

progress - Progress Updates

log - Log Messages

result - Task Completion

error - Error Messages

status - Agent Status Changes

heartbeat - Keep-Alive

REST API Reference

Health Check

Boards API

Create Board

List Boards

Get Board

Update Board

Delete Board

Columns API

Create Column

List Columns

Get Column

Tasks API

Create Task

Get Task

Update Task

Delete Task

Update Task State

Move Task

List Tasks in Board

Agents API

Launch Agent

List Agents

Get Agent Status

Get Agent Logs

Stop Agent

List Agent Types

Get Agent Type

Orchestrator API

Get Orchestrator Status

Get Task Queue

Trigger Task Execution

Start Task

Stop Task

Pause Task

Resume Task

Get Task Execution Status

Get Task Logs

Get Task Artifacts

Session Resumption

Error Responses

Creating Custom Agents

Development Notes

Running Locally

Running Tests

Environment Variables

12 KiB

Raw Blame History

Augment Agent (`augment-agent`)

`progress` - Progress Updates

`log` - Log Messages

`result` - Task Completion

`error` - Error Messages

`status` - Agent Status Changes

`heartbeat` - Keep-Alive