Controlling agents
ACP stores a command and delivers it as an HMAC-signed webhook to your app’s /api/acp/webhook endpoint. The local SDK updates its state. Pausing prevents the next wrapped call; it does not cancel a model request already in flight.
Available commands
| Command | Effect |
|---|---|
| pause / stop | The next wrapped call throws AgentPausedError. |
| resume / restart | Allows subsequent wrapped calls; restart does not restart your server process. |
| update_model | Sets a model override. Pass getEffectiveModel() to your model provider call. |
| update_prompt | Requires full control scope and approval. Fetch the approved prompt before the next model call. |
The dashboard API uses commandType in the request body. The delivered webhook uses command. These are different contracts.
Command API
| Method and route | Purpose |
|---|---|
| POST /api/agents/:id/commands | Create a command: { "commandType": "pause", "payload": {} } |
| GET /api/agents/:id/commands | Inspect an agent’s command history. |
| POST /api/commands/:id/approve | Approve a pending prompt update (owner or admin). |
| POST /api/commands/:id/deny | Reject a pending update (owner or admin). |
| GET /api/prompts/:agentId | Fetch the composed prompt using x-api-key. |