Agents

An agent profile is the unit you govern. It holds a model, a system prompt, the tools the agent may use, and limits on what one run may spend and do. These endpoints create, configure, and run profiles.

The Agent API needs no workspace slug. ACP reads the workspace from your key, so every path starts at /api/v1/agents.

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

Every endpoint needs a valid gsk_ key (Authentication). Writes return { "ok": true, … }. Reads return the resource.

The agent profile object

On a run started through the API, maxBudgetCents and maxToolRounds are enforced inside the run. A bad prompt cannot outspend the first or loop past the second. maxToolCalls and maxDurationMs are stored and reported (see stopReason), but they are not hard stops on API-triggered runs today. They are checked between steps only on runs launched from the dashboard.

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

There are two ways. Pick by how strict you want the check to be.

PUT: replace fields

PUT /api/v1/agents/{id}

Send any subset of the writable fields. Fields you send are written, and fields you leave out stay as they were. 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}

Use this one from scripts. The body is validated: 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 writing bad data. 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 manual tweak. Use PATCH when a script or pipeline does the writing.

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

Starts a run. Pass an input, an optional context, and stream if you want SSE events. Each tool call in the run is checked against your workspace policy. Only deny is enforced on API runs, so a tool your policy would ask about runs without a hold.

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 full request and response shape (input, context, streaming events, run status) is on Run triggers.

Common errors

Next

curl -fsSL https://agenticcontrolplane.com/install.sh | bash

irm https://agenticcontrolplane.com/install.ps1 | iex