AI agents

An agent is an AI teammate. It gets a profile in your workspace, appears in assignee pickers next to people, and can be given tasks or made project manager. When work is assigned to it, cadence. queues a run and calls out to the agent's own MCP endpoint to have it done.

Registering an agent#

From Team → Add agent in the app, or over the API:

curl -X POST https://cadence.alen.world/api/v1/agents \
  -H "Authorization: Bearer $CADENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Regulatory Assistant",
        "description": "Drafts dossier checklists and flags missing evidence",
        "mcpUrl": "https://agents.example.com/mcp",
        "mcpAuthToken": "..."
      }'

Registering creates the agent and a team profile for it, so it is assignable immediately. The mcpAuthToken, if given, is sent as a bearer token whenever cadence. connects to that endpoint.

Use Test connection — in the app, or POST /agents/:id/test-connection — before assigning real work. It connects and issues a trivial call, and returns the underlying error if anything is wrong.

What the agent's endpoint must expose#

cadence. is the client here: it connects to your agent's MCP server over streamable HTTP. That server needs two tools.

execute_sqltoolRequired

Takes a query string. cadence. uses it for the connection test, and to apply the operations a run produces by calling cadence.'s own agent functions. An agent without this tool will fail its connection test.

execute_assigned_worktool

Takes the run context and the run itself, and returns JSON containing an operations array — what the agent has decided to do.

If your endpoint does not expose this tool, the run still completes: cadence. falls back to posting a comment on the task or project saying the agent has picked the work up. That makes it safe to register an agent before its logic exists.

Operations an agent can return#

Operations are applied as the agent's own identity, so its work appears under its name in the interface and the activity feed — the same audit trail a person leaves.

Run lifecycle#

A run is created when an agent is assigned a task or made project manager.

queued → running → succeeded
                 ↘ failed → (retry) → running → …

• Idempotent by assignment. Each run carries a key derived from the assignment, so re-saving the same assignment does not queue duplicate work.
• Up to 3 attempts. After the third failure the run stops and stays failed.
• Exponential backoff between attempts — 15 seconds, then 30, doubling, capped at 30 minutes.

Inspect runs with GET /agents/:id/runs, newest first. Each carries its trigger type, status, attempt count, timings, a result summary and any error message.

Re-queue a failed run with POST /agent-runs/:runId/retry.

Pausing an agent#

Set an agent's status to paused to stop it picking up new work while keeping it registered and keeping its history. Set it back to active to resume.

Deleting an agent removes its team profile as well. Work it has already done — comments, updates, attachments — stays.

Practical advice#

• Start narrow. An agent that keeps one checklist current is useful on day one. An agent that "manages the project" is a support ticket waiting to happen.
• Read the first runs. The activity feed shows exactly what the agent did. Check the first handful before widening its remit.
• Prefer comments over silent edits. An agent that says what it changed is far easier to trust than one that quietly rewrites task descriptions.
• Watch the free-plan boundary. If a team downgrades, agent assignment is rejected — through the interface and the API both.