Agents
Space MCP tools in the Agents scope (agents). Reach these with a wks_live_ key over space-mcp or space-api.
Tools in the agents scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants agents.
create_agent
Scope: agents:write
Make another agent in THIS space — a person in Messages with its own chat, thinking on this space's gateway, billed to this space. It can never do more than you can here: leave permissions, ask_first, can_use and space_ids out for "same as me" (your own permissions and gates, your own Can use, this space only), or ask for a SUBSET — anything wider than yours is refused by name. Its ask-first gates are at least yours. Say what it is for in instructions (it reads them from day one). Each new agent is a bill; the owner may have set this to ask them first, in which case the call queues and you call again with approved_action_id once approved. Every agent it makes in turn is held under ITS ceiling.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | What it is called in Messages. Must be unused among the owner's agents. |
instructions | string | Its standing instructions, plain English, up to 8000 characters: what it is for, how the owner likes things done. | |
permissions | object | category → action → true, a SUBSET of yours here. Omit for the same as yours. | |
ask_first | object | category → action → true: gates on top of yours (yours always apply). Omit for the same as yours. | |
can_use | object | { "<space_id>": <map> } — within what YOU may use there, and no further than YOUR step on each thing. Per kind (tables, documents, apps, pages, forms, asset_folders, automations, secrets) one of: "all" or left out (every one, at the top); a LIST ["<id>" | {"id": "<id>", "level": "<step>"}] (only those; a bare id = the top; [] = none); or EVERY ONE AT A STEP, EXCEPT — leave the kind out and pass default_levels: {"<kind>": "<step>"} with levels: {"<kind>": {"<id>": "<step>" | "hidden"}} ("hidden" = it cannot see that one; new ones arrive at the default step). Steps, bottom first — tables: read < edit < fill < change; apps: read < use < build; pages: read < content < edit < change; documents: read < comment < edit < change; forms: read < submit < edit < change; asset_folders: read < add < change; automations: read < run < edit < change; secrets: use; projects: read < update < add < change; mailboxes: read < reply < send < campaigns; phone_numbers: read < reply < text < campaigns; ad_accounts: read < draft < spend; communities: read < post < moderate < change; calendars: busy < read < add < change. tables: edit = change what existing rows say, fill = also add/remove rows, change = also columns/views/settings/delete; apps: use = records and running it, build = also its code/publishing/sharing; pages: content = swap a picture or pin a product, edit = rewrite it, change = also publish/delete; documents: comment, edit = change the words, change = share/move/delete; forms: submit = send answers through it, edit = its questions, change = publish/delete; asset_folders: add = put files and folders in it, change = rename/move/delete (a folder covers everything under it); automations: run, edit = its trigger and steps, change = switch on/off, delete; a secret is only used, never read. Omit for the same as yours. | |
space_ids | string[] | Other spaces it may act in — only ones you work in (list_my_spaces). Omit for this space only. | |
model | string | Its brain, a chat model this space allows (list_ai_models, category llm). Omit for your own model; required when you think on a sign-in. | |
compute_limit_monthly | number | Its monthly compute cap in USD, at most yours. Default: yours, or $50, whichever is lower. | |
avatar_url | string | A face for it (an image URL). |
pause_agent
Scope: agents:write
Pause an agent YOU made (create_agent) in this space: it keeps its name, chat, files, permissions and External Reach settings but stops answering — messages to it wait, its scheduled tasks are skipped (recurring ones run again at their next time), its External Reach stays silent, and its machine bills nothing. Reversible with resume_agent. You cannot pause a peer or your maker — ask the owner for those. agent_id from list_agents.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | The agent (list_agents). |
resume_agent
Scope: agents:write
Resume an agent YOU made that is paused. It comes back exactly as it was and reads what arrived while it was paused; a skipped recurring task runs at its next time, not now. A running agent is a bill again, so the owner may have this ask them first. agent_id from list_agents.
| Parameter | Type | Required | Description |
|---|---|---|---|
agent_id | string | yes | The agent (list_agents). |