Agents

An agent profile is the unit you govern: a model, a system prompt, the tools it may use, and hard caps on what one run may spend and do. These endpoints create, configure, and run them.

The Agent API is slug-free — ACP resolves your workspace from the key — so every path starts at /api/v1/agents.

https://api.agenticcontrolplane.com/api/v1/agents

All endpoints require a valid gsk_ key (Authentication). Writes return { "ok": true, … }; reads return the resource.

The agent profile object

The caps are not advisory — they’re enforced at runtime. A misconfigured prompt can’t outspend maxBudgetCents or loop past maxToolRounds.

List agents

GET /api/v1/agents

Returns every profile in the workspace, newest first.

curl -s "$ACP/api/v1/agents" \
  -H "Authorization: Bearer $ACP_KEY"

{
  "ok": true,
  "profiles": [
    { "id": "a7Kf9_Qe2", "name": "Release Notes Writer", "model": "claude-sonnet-4-6", "maxBudgetCents": 50, "...": "..." }
  ]
}

Get an agent

GET /api/v1/agents/{id}

curl -s "$ACP/api/v1/agents/a7Kf9_Qe2" \
  -H "Authorization: Bearer $ACP_KEY"

{ "ok": true, "profile": { "id": "a7Kf9_Qe2", "name": "Release Notes Writer", "...": "..." } }

Returns 404 if no profile with that ID exists in this workspace.

Create an agent

POST /api/v1/agents

name and model are required; everything else takes the defaults above.

curl -sX POST "$ACP/api/v1/agents" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Campsite Scout",
    "model": "claude-haiku-4-5",
    "systemPrompt": "Watch for campsite cancellations and report them.",
    "enabledTools": ["http.get", "notifications.sendEmail"],
    "maxBudgetCents": 25,
    "maxToolCalls": 30,
    "maxDurationMs": 600000
  }'

{ "ok": true, "id": "Rk3p_Lm8" }

Update an agent

Two ways, depending on how strict you want to be.

PUT — replace fields

PUT /api/v1/agents/{id}

Send any subset of the writable fields; each present field is written, absent fields are left untouched. Permissive — unknown fields are ignored.

curl -sX PUT "$ACP/api/v1/agents/Rk3p_Lm8" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxBudgetCents": 40 }'

PATCH — validated update

PATCH /api/v1/agents/{id}

The strict path, and the one to prefer for automation. The body is validated at the boundary: unknown fields are rejected, model must be a recognized model, and numeric caps must fall within sane bounds. A bad request fails with 400 instead of silently writing garbage. PATCH is rate limited and audit-logged.

curl -sX PATCH "$ACP/api/v1/agents/Rk3p_Lm8" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "maxToolCalls": 50, "model": "claude-sonnet-4-6" }'

{ "ok": true }

Use PUT for a quick interactive tweak; use PATCH when a script or pipeline is doing the writing and you want the guardrails.

Delete an agent

DELETE /api/v1/agents/{id}

curl -sX DELETE "$ACP/api/v1/agents/Rk3p_Lm8" \
  -H "Authorization: Bearer $ACP_KEY"

{ "ok": true }

Returns 404 if the profile doesn’t exist.

Run an agent

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

Kicks off a governed run. Pass an input, optional context, and stream to get SSE events. Every tool call inside the run is checked against your workspace policy, and the whole run obeys the profile’s caps.

curl -sX POST "$ACP/api/v1/agents/a7Kf9_Qe2/run" \
  -H "Authorization: Bearer $ACP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": "Draft release notes for everything merged this week." }'

The request and response shape — input, context injection, streaming events, and run status — are documented in full on Run triggers.

Common errors

Next