Agents API

List agents

GET /api/v1/agents?project_id=...

Response:

{
  "items": [
    {
      "id": "...",
      "name": "web-01",
      "framework": "django",
      "engines": ["celery"],
      "schedulers": ["celery-beat"],
      "state": "online",
      "last_seen_at": "...",
      "protocol_version": "v1",
      "capabilities": { ... }
    }
  ]
}

Mint token

POST /api/v1/agents/mint-token

Role: admin. Body:

{
  "project_id": "...",
  "name": "billing-worker-02"
}

Response (token shown once - save it):

{
  "agent_id": "...",
  "name": "billing-worker-02",
  "token": "z4j_agent_...",
  "brain_ws_url": "wss://z4j.example.com/ws"
}

Uniqueness: (project_id, name) must be unique. Duplicate name returns 409 conflict_duplicate_name.

Revoke token

POST /api/v1/agents/{id}/revoke

Role: admin. The next reconnect attempt by that agent fails with 401.

Delete agent

DELETE /api/v1/agents/{id}

Role: admin. Removes the agent row. Past events and tasks remain linked via agent_id (now dangling for audit).

Get detail

GET /api/v1/agents/{id}

Returns full capabilities, framework version, engine versions, buffer stats.

Restart agent

POST /api/v1/agents/{id}/restart

Role: admin. Sends a command: restart_agent - the agent process reconnects with fresh adapter state. It does not restart the host process.