---
title: Build on Agents
description: Start and drive chats with coding agents on your daemons' projects and with agents on your computers, from code or another agent, over MCP or REST.
section: developers
order: 157
audience: [builder, agent]
sources: [services/nodejs-cloud/lib/agents/mcp.ts, services/nodejs-cloud/lib/agents/http.ts, services/nodejs-cloud/lib/agents/index.ts, services/nodejs-cloud/app/api/workspace/agents/chats]
features: []
---

A chat is one conversation with one agent that runs on your organisation's own machines: a coding agent in a project
directory a daemon offers, or an agent on one of your computers. The cloud relays messages and events; the repository
and the conversation stay on the daemon. See [Venom Agents](/docs/agents.md).

## What you can build {#build}

- **A script that hands work to a coding agent.** List a daemon's projects with `agents_project_list` (or make one with `agents_workspace_create`, cloned from a repository), start a chat with
  `agents_chat_create` and a `prompt`, then read `agents_transcript_get` until the run is done.
- **An approvals bot.** Read the transcript or the console's event stream for `approval_request` events and answer them
  with `agents_approval_decide` (`allow-once`, `allow-session`, `allow-project` or `deny`).
- **A review step.** After a run, read the files each turn changed with `agents_change_get` (`turn`: a checkpoint's
  `entryId`).

## At a glance {#glance}

Generated from the code on every docs build.

| | |
|---|---|
| MCP endpoint | `https://cloud.usevenom.dev/workspace/mcp/agents`, server name `venom-agents` |
| Connect | `claude mcp add --transport http venom-agents https://cloud.usevenom.dev/workspace/mcp/agents` |
| MCP tools | 48 (21 read, 27 write) |
| OAuth scopes | `agents:read` `agents:write` |
| REST twin | 48 routes under `https://cloud.usevenom.dev/api/v1` |
| Webhook events | none yet |

## Authentication and scopes {#scopes}

Agents needs the `agents` add-on (the Team plan and up). Without it every call answers `403 addon_required`.

- A **personal API key or an OAuth grant** acts as the member. OAuth apps need `agents:read` for the read tools and
  `agents:write` for the rest; a computer chat also needs the member's right to use that computer.
- **Any other key** has no access: a chat belongs to a person.

Only the member who started a chat sends to it. Org owners and admins read every member's chats (`all: true`).

## Worked example {#example}

```bash
curl -X POST "$VENOM_CLOUD/workspace/mcp/agents" \
  -H "Authorization: Bearer $VENOM_PERSONAL_KEY" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "agents_chat_create", "arguments": {"daemon_id": "<daemon-id>", "project": "/home/me/src/app", "prompt": "Fix the failing tests", "format": "json"}}}'
```

Then, with the chat's `id`:

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": { "name": "agents_transcript_get", "arguments": { "chat_id": "<chat-id>" } } }
```

While a run is active a new `prompt` answers `409 busy`: send it with `delivery: "steer"` or `"follow_up"` instead.
Errors worth handling: `501 projects_unavailable` (the daemon is too old to list projects), `503
session_daemon_unavailable` (the chat's daemon is offline), `409 chat_archived`, `409 member_gone`.

## Events {#events}

This product sends no org webhook events yet. Follow its changes with `workspace_change_list` where it has a change feed, or poll its list routes.

The live stream (`GET /api/workspace/agents/chats/{id}/events`) is for the signed-in browser; an agent reads the
transcript.

## REST routes {#rest}

The REST twin: 48 routes under `https://cloud.usevenom.dev/api/v1`, each calling the MCP tool named in its row with the same arguments (see [the REST twin](/docs/developers/rest)).

| Method | Path | Summary | MCP tool |
|---|---|---|---|
| GET | `/api/v1/agents/chats` | Your chats with agents (admins: all for every member's) | `agents_chat_list` |
| POST | `/api/v1/agents/chats` | Start a chat: a coding agent in a daemon's project (or a new scratch folder), or an agent on a computer, with an optional first prompt | `agents_chat_create` |
| GET | `/api/v1/agents/chats/{chat_id}` | One chat | `agents_chat_get` |
| PATCH | `/api/v1/agents/chats/{chat_id}` | Rename a chat, change its permission mode or shift its gear; a quick chat's servers | `agents_chat_update` |
| DELETE | `/api/v1/agents/chats/{chat_id}` | Archive a chat; its session is closed | `agents_chat_archive` |
| POST | `/api/v1/agents/chats/{chat_id}/messages` | Send a message: a prompt, or steer or follow up a running turn | `agents_chat_send` |
| POST | `/api/v1/agents/attachments` | Upload a file or picture for your next quick-chat message (base64) | `agents_attachment_upload` |
| DELETE | `/api/v1/agents/attachments/{file_id}` | Remove a file you uploaded and have not sent | `agents_attachment_delete` |
| GET | `/api/v1/agents/chats/{chat_id}/attachments` | A chat's files and pictures | `agents_attachment_list` |
| POST | `/api/v1/agents/chats/{chat_id}/abort` | Stop the running turn | `agents_chat_stop` |
| POST | `/api/v1/agents/chats/{chat_id}/approvals/{approval_id}` | Answer an approval the agent asked for | `agents_approval_decide` |
| POST | `/api/v1/agents/chats/{chat_id}/questions/{question_id}` | Answer a question the agent asked | `agents_question_respond` |
| GET | `/api/v1/agents/chats/{chat_id}/transcript` | The conversation so far | `agents_transcript_get` |
| GET | `/api/v1/agents/chats/{chat_id}/changes` | The turns that changed files, or one turn's file changes (turn) | `agents_change_get` |
| GET | `/api/v1/agents/gears` | The gears a chat can run in: the org's, then the daemon's own or venom's built-ins | `agents_gear_list` |
| GET | `/api/v1/agents/projects` | The project directories a daemon offers | `agents_project_list` |
| GET | `/api/v1/agents/workspaces` | The workspaces on a daemon (durable and scratch) | `agents_workspace_list` |
| POST | `/api/v1/agents/workspaces` | Make a workspace on a daemon: empty, cloned from an https URL, or scratch | `agents_workspace_create` |
| GET | `/api/v1/agents/servers` | The MCP servers a quick chat can use, and your catalog connections | `agents_server_list` |
| GET | `/api/v1/agents/skills` | The organisation's skills a quick chat can use | `agents_skill_list` |
| POST | `/api/v1/agents/connections` | Connect a catalog MCP server for quick chats (an OAuth server answers the sign-in link) | `agents_connection_create` |
| DELETE | `/api/v1/agents/connections/{server}` | Disconnect a catalog MCP server | `agents_connection_delete` |
| GET | `/api/v1/agents/bots` | Your bots: named agents with an avatar and standing instructions | `agents_bot_list` |
| POST | `/api/v1/agents/bots` | Make a bot, or a ready-made one with its routines (template) | `agents_bot_create` |
| GET | `/api/v1/agents/bots/{bot_id}` | One of your bots, with its instructions | `agents_bot_get` |
| PATCH | `/api/v1/agents/bots/{bot_id}` | Change a bot | `agents_bot_update` |
| DELETE | `/api/v1/agents/bots/{bot_id}` | Delete a bot and its routines (its chats stay) | `agents_bot_delete` |
| GET | `/api/v1/agents/bots/{bot_id}/memory` | A bot's memory note | `agents_bot_memory_get` |
| PUT | `/api/v1/agents/bots/{bot_id}/memory` | Rewrite a bot's memory note | `agents_bot_memory_update` |
| GET | `/api/v1/agents/bots/{bot_id}/outreach` | How a bot reaches out: mode, channels, caps and today's counts, pacing, quiet hours, who it may contact, what waits for you, its ledger | `agents_bot_outreach_get` |
| PATCH | `/api/v1/agents/bots/{bot_id}/outreach` | Change how a bot reaches out (owner only) | `agents_bot_outreach_update` |
| POST | `/api/v1/agents/bots/{bot_id}/outreach/decide` | Approve or decline what a bot's runs left waiting, all or some | `agents_bot_outreach_decide` |
| POST | `/api/v1/agents/bots/{bot_id}/outreach/release` | Let a bot write again to someone who replied to it | `agents_bot_outreach_release` |
| GET | `/api/v1/agents/bots/summary` | Your bots at a glance: next and last run, needs-you count, spend, working now | `agents_bot_summary_list` |
| GET | `/api/v1/agents/bots/brief` | What your bots did since you last looked | `agents_bot_brief_get` |
| DELETE | `/api/v1/agents/bots/brief` | Dismiss the brief | `agents_bot_brief_dismiss` |
| GET | `/api/v1/agents/routines` | Your bots' routines | `agents_bot_routine_list` |
| POST | `/api/v1/agents/routines` | Make a bot run by itself on a schedule, an email, a webhook or events in the workspace | `agents_bot_routine_create` |
| GET | `/api/v1/agents/routines/{routine_id}` | One of your bots' routines | `agents_bot_routine_get` |
| PATCH | `/api/v1/agents/routines/{routine_id}` | Change a bot's routine | `agents_bot_routine_update` |
| DELETE | `/api/v1/agents/routines/{routine_id}` | Delete a bot's routine | `agents_bot_routine_delete` |
| POST | `/api/v1/agents/routines/{routine_id}/run` | Run a bot's routine now | `agents_bot_routine_run` |
| POST | `/api/v1/agents/routines/{routine_id}/secret` | A new secret for a bot's webhook or email routine | `agents_bot_secret_rotate` |
| GET | `/api/v1/agents/routines/runs` | Your bots' runs, newest first | `agents_bot_run_list` |
| GET | `/api/v1/agents/routines/runs/{run_id}` | One of your bots' runs | `agents_bot_run_get` |
| GET | `/api/v1/agents/routines/runs/{run_id}/events` | Every item one of your bots' event runs took | `agents_bot_run_event_list` |
| POST | `/api/v1/agents/routines/runs/{run_id}/decide` | Approve or decline what a waiting run asks | `agents_bot_run_decide` |
| DELETE | `/api/v1/agents/workspaces/{workspace_id}` | Delete a workspace and its files on the daemon | `agents_workspace_delete` |

The console's own API under `/api/workspace/agents` mirrors the tools for the signed-in browser session; it does not
take API keys. Its routes are listed in [Chats API and MCP tools](/docs/agents/api.md).

## MCP tools {#tools}

48 tools: 21 read, 27 write. Generated from the code; "write (destructive)" is the tool's `destructiveHint`. A tool with a REST route is the same call over HTTP.

| Tool | Title | Access | Scope | REST route |
|---|---|---|---|---|
| `agents_approval_decide` | Answer an agent's approval | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/approvals/{approval_id}` |
| `agents_attachment_delete` | Remove an unsent upload | write (destructive) | `agents:write` | `DELETE /api/v1/agents/attachments/{file_id}` |
| `agents_attachment_list` | List a chat's files | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/attachments` |
| `agents_attachment_upload` | Upload a file for a quick chat | write | `agents:write` | `POST /api/v1/agents/attachments` |
| `agents_bot_brief_dismiss` | Dismiss the brief | write | `agents:write` | `DELETE /api/v1/agents/bots/brief` |
| `agents_bot_brief_get` | What your bots did | read | `agents:read` | `GET /api/v1/agents/bots/brief` |
| `agents_bot_create` | Make a bot | write | `agents:write` | `POST /api/v1/agents/bots` |
| `agents_bot_delete` | Delete a bot | write (destructive) | `agents:write` | `DELETE /api/v1/agents/bots/{bot_id}` |
| `agents_bot_get` | Read a bot | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}` |
| `agents_bot_list` | List your bots | read | `agents:read` | `GET /api/v1/agents/bots` |
| `agents_bot_memory_get` | Read a bot's memory | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}/memory` |
| `agents_bot_memory_update` | Rewrite a bot's memory | write | `agents:write` | `PUT /api/v1/agents/bots/{bot_id}/memory` |
| `agents_bot_outreach_decide` | Answer a bot's approval card | write | `agents:write` | `POST /api/v1/agents/bots/{bot_id}/outreach/decide` |
| `agents_bot_outreach_get` | How a bot reaches out | read | `agents:read` | `GET /api/v1/agents/bots/{bot_id}/outreach` |
| `agents_bot_outreach_release` | Let a bot write to someone again | write | `agents:write` | `POST /api/v1/agents/bots/{bot_id}/outreach/release` |
| `agents_bot_outreach_update` | Change how a bot reaches out | write | `agents:write` | `PATCH /api/v1/agents/bots/{bot_id}/outreach` |
| `agents_bot_routine_create` | Make a bot's routine | write | `agents:write` | `POST /api/v1/agents/routines` |
| `agents_bot_routine_delete` | Delete a bot's routine | write (destructive) | `agents:write` | `DELETE /api/v1/agents/routines/{routine_id}` |
| `agents_bot_routine_get` | Read a bot's routine | read | `agents:read` | `GET /api/v1/agents/routines/{routine_id}` |
| `agents_bot_routine_list` | List a bot's routines | read | `agents:read` | `GET /api/v1/agents/routines` |
| `agents_bot_routine_run` | Run a bot's routine now | write | `agents:write` | `POST /api/v1/agents/routines/{routine_id}/run` |
| `agents_bot_routine_update` | Change a bot's routine | write | `agents:write` | `PATCH /api/v1/agents/routines/{routine_id}` |
| `agents_bot_run_decide` | Answer what a bot asks | write | `agents:write` | `POST /api/v1/agents/routines/runs/{run_id}/decide` |
| `agents_bot_run_event_list` | List what started an event run | read | `agents:read` | `GET /api/v1/agents/routines/runs/{run_id}/events` |
| `agents_bot_run_get` | Read a bot's run | read | `agents:read` | `GET /api/v1/agents/routines/runs/{run_id}` |
| `agents_bot_run_list` | List your bots' runs | read | `agents:read` | `GET /api/v1/agents/routines/runs` |
| `agents_bot_secret_rotate` | Rotate a bot routine's secret | write | `agents:write` | `POST /api/v1/agents/routines/{routine_id}/secret` |
| `agents_bot_summary_list` | Your bots at a glance | read | `agents:read` | `GET /api/v1/agents/bots/summary` |
| `agents_bot_update` | Change a bot | write | `agents:write` | `PATCH /api/v1/agents/bots/{bot_id}` |
| `agents_change_get` | List a chat's file changes | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/changes` |
| `agents_chat_archive` | Archive a chat | write (destructive) | `agents:write` | `DELETE /api/v1/agents/chats/{chat_id}` |
| `agents_chat_create` | Start a chat | write | `agents:write` | `POST /api/v1/agents/chats` |
| `agents_chat_get` | Read a chat | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}` |
| `agents_chat_list` | List chats | read | `agents:read` | `GET /api/v1/agents/chats` |
| `agents_chat_send` | Send a message to a chat | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/messages` |
| `agents_chat_stop` | Stop a chat's run | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/abort` |
| `agents_chat_update` | Rename a chat, change its mode, gear or servers | write | `agents:write` | `PATCH /api/v1/agents/chats/{chat_id}` |
| `agents_connection_create` | Connect a catalog server | write | `agents:write` | `POST /api/v1/agents/connections` |
| `agents_connection_delete` | Disconnect a catalog server | write (destructive) | `agents:write` | `DELETE /api/v1/agents/connections/{server}` |
| `agents_gear_list` | List the gears a chat can run in | read | `agents:read` | `GET /api/v1/agents/gears` |
| `agents_project_list` | List a daemon's projects | read | `agents:read` | `GET /api/v1/agents/projects` |
| `agents_question_respond` | Answer an agent's question | write | `agents:write` | `POST /api/v1/agents/chats/{chat_id}/questions/{question_id}` |
| `agents_server_list` | List the servers a quick chat can use | read | `agents:read` | `GET /api/v1/agents/servers` |
| `agents_skill_list` | List the skills a quick chat can use | read | `agents:read` | `GET /api/v1/agents/skills` |
| `agents_transcript_get` | Read a chat's transcript | read | `agents:read` | `GET /api/v1/agents/chats/{chat_id}/transcript` |
| `agents_workspace_create` | Make a workspace on a daemon | write | `agents:write` | `POST /api/v1/agents/workspaces` |
| `agents_workspace_delete` | Delete a workspace | write (destructive) | `agents:write` | `DELETE /api/v1/agents/workspaces/{workspace_id}` |
| `agents_workspace_list` | List a daemon's workspaces | read | `agents:read` | `GET /api/v1/agents/workspaces` |

Every tool takes `format: "json"` for structured content and refuses arguments it does not list.

## Related {#related}

- [Venom Agents](/docs/agents.md) and [Chats API and MCP tools](/docs/agents/api.md).
- [Authentication and scopes](/docs/developers/auth.md), [MCP servers](/docs/developers/mcp.md) and [Errors, limits and pagination](/docs/developers/conventions.md).
