> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Workers, triggers and tools > 7 tools: heliyos_workers_list, heliyos_workers_get, heliyos_workers_create, heliyos_workers_update, heliyos_workers_delete, heliyos_triggers_list, heliyos_workers_tools_list. | Tool | What it does | Kind | | - | - | - | | [`heliyos_workers_list`](#heliyos-workers-list) | List workers | Read | | [`heliyos_workers_get`](#heliyos-workers-get) | Get a worker | Read | | [`heliyos_workers_create`](#heliyos-workers-create) | Create a worker | Write | | [`heliyos_workers_update`](#heliyos-workers-update) | Update a worker | Write | | [`heliyos_workers_delete`](#heliyos-workers-delete) | Delete a worker | Destructive | | [`heliyos_triggers_list`](#heliyos-triggers-list) | List worker triggers | Read | | [`heliyos_workers_tools_list`](#heliyos-workers-tools-list) | List tools a worker can use | Read | Write and destructive tools change your workspace. Clients that support it ask before they run. ## List workers `heliyos_workers_list` · **Read** · Idempotent Lists the workspace's workers (AI agents): the built-in default ones and custom ones, each with its id, type, active flag, description and triggers. Returns every worker in one page (a workspace has a handful). Use heliyos\_workers\_get for a worker's instructions, heliyos\_runs\_list with worker\_id for its runs. Returns structuredContent \{workers:\[\{id, name, type, is\_active, ...}]}. ### Inputs **type** `string` Only built-in (default) or only custom workers. One of `default`, `custom`. **is\_active** `boolean` Only active (true) or only inactive (false) workers. **response\_format** `string` (default: concise) "concise" (default) returns one row per worker; "detailed" returns each worker's triggers too. One of `concise`, `detailed`. ### Returns A readable text summary, plus `structuredContent` with `workers`. ### API endpoints * [Get a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/get-a-worker.md) · `GET /v1/platform/agents/{id}` * [List workers](https://docs.heliyos.ai/api-reference/workers-and-runs/list-workers.md) · `GET /v1/platform/agents` ## Get a worker `heliyos_workers_get` · **Read** · Idempotent Fetches one worker by id: name, type, active flag, description, triggers and instructions (cut at 1500 characters in concise). "detailed" adds the full instructions, the tools it may call, read-only and memory flags, file scope and times. Returns structuredContent \{worker}. ### Inputs **worker\_id** `string` *required* worker\_id: a 24-character hex id. A 24-character hex id. **response\_format** `string` (default: concise) "concise" (default) returns the worker with shortened instructions; "detailed" returns full instructions, tools, flags and times. One of `concise`, `detailed`. ### Returns A readable text summary, plus `structuredContent` with `worker`. ### API endpoints * [Get a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/get-a-worker.md) · `GET /v1/platform/agents/{id}` ## Create a worker `heliyos_workers_create` · **Write** Creates a custom worker (AI agent) with a name, instructions and, optionally, triggers that start it: on every new task, when mentioned in chat, on named events, or on a cron schedule. It starts active unless is\_active is false, and its runs use credits and can change records or send email (consequential actions wait for approval in Heliyos), so confirm with the user first. Names are unique; a repeat fails with CONFLICT. Before calling: heliyos\_triggers\_list for valid event names and heliyos\_workers\_tools\_list for the tool\_names it may use (both are checked; unknown names are refused). Files are configured in the Heliyos web app. Returns structuredContent \{worker}. ### Inputs **name** `string` *required* Worker name, unique in the workspace. Up to 200 characters. **instructions** `string` *required* What the worker does and how, in Markdown. Up to 50000 characters. **description** `string` One line shown in the worker catalog. Up to 2000 characters. **is\_active** `boolean` Default true. **read\_only** `boolean` true: the worker may read but never change data. Default false. **memory\_enabled** `boolean` true: the worker keeps memory across runs. Default from the workspace. **triggers** `object[]` When the worker runs. Replaces the current triggers; on a default worker its built-in triggers stay. Event names must come from heliyos\_triggers\_list. Up to 50 items. **item properties** **type** `string` *required* task\_created (every new task), mention (@worker in chat), event (named events) or scheduled (cron). One of `task_created`, `mention`, `event`, `scheduled`. **events** `string[]` event only: event names such as "task.created" or "deal.updated". Up to 200 items. **cron** `string` scheduled only: 5-field cron, for example "0 8 \* \* 1-5". **timezone** `string` scheduled only: IANA zone, for example "Europe/Berlin". Default UTC. Up to 64 characters. **tool\_names** `string[]` The tools the worker may call, by name from heliyos\_workers\_tools\_list (Heliyos tools and integration actions alike). Unknown names are refused. Custom workers only. Up to 500 items. ### Returns A readable text summary, plus `structuredContent` with `worker`. ### API endpoints * [Get a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/get-a-worker.md) · `GET /v1/platform/agents/{id}` * [Create a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/create-a-worker.md) · `POST /v1/platform/agents` ## Update a worker `heliyos_workers_update` · **Write** · Idempotent Changes a worker by id; what you leave out is kept. Custom workers: name, instructions, description, is\_active, read\_only, memory\_enabled, triggers and tool\_names. Default (built-in) workers: only instructions, description, is\_active, memory\_enabled and triggers; the rest is ignored. `triggers` REPLACES the worker's own triggers (a default worker keeps its built-in ones) and `tool_names` REPLACES its tools: pass every tool it should keep (heliyos\_workers\_get detailed shows the current ones, heliyos\_workers\_tools\_list the valid names). Set is\_active false to pause a worker. Returns structuredContent \{worker}. ### Inputs **worker\_id** `string` *required* worker\_id: a 24-character hex id. A 24-character hex id. **name** `string` Worker name, unique in the workspace. Up to 200 characters. **instructions** `string` What the worker does and how, in Markdown. Up to 50000 characters. **description** `string` One line shown in the worker catalog. Up to 2000 characters. **is\_active** `boolean` false pauses the worker; true resumes it. **read\_only** `boolean` true: the worker may read but never change data (custom workers only). **memory\_enabled** `boolean` Whether the worker keeps memory across runs. **triggers** `object[]` When the worker runs. Replaces the current triggers; on a default worker its built-in triggers stay. Event names must come from heliyos\_triggers\_list. Up to 50 items. **item properties** **type** `string` *required* task\_created (every new task), mention (@worker in chat), event (named events) or scheduled (cron). One of `task_created`, `mention`, `event`, `scheduled`. **events** `string[]` event only: event names such as "task.created" or "deal.updated". Up to 200 items. **cron** `string` scheduled only: 5-field cron, for example "0 8 \* \* 1-5". **timezone** `string` scheduled only: IANA zone, for example "Europe/Berlin". Default UTC. Up to 64 characters. **tool\_names** `string[]` The tools the worker may call, by name from heliyos\_workers\_tools\_list (Heliyos tools and integration actions alike). Unknown names are refused. Custom workers only. Up to 500 items. ### Returns A readable text summary, plus `structuredContent` with `worker`. ### API endpoints * [Get a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/get-a-worker.md) · `GET /v1/platform/agents/{id}` * [Update a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/update-a-worker.md) · `PATCH /v1/platform/agents/{id}` ## Delete a worker `heliyos_workers_delete` · **Destructive** · Idempotent Permanently deletes one custom worker by id and its schedules. Default (built-in) workers cannot be deleted; pause them with heliyos\_workers\_update is\_active false. Past runs are kept. This cannot be undone: confirm with the user first. Returns structuredContent \{worker\_id, deleted}. ### Inputs **worker\_id** `string` *required* worker\_id: a 24-character hex id. A 24-character hex id. ### Returns A readable text summary, plus `structuredContent` with `worker_id`, `deleted`. ### API endpoints * [Get a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/get-a-worker.md) · `GET /v1/platform/agents/{id}` * [Delete a worker](https://docs.heliyos.ai/api-reference/workers-and-runs/delete-a-worker.md) · `DELETE /v1/platform/agents/{id}` ## List worker triggers `heliyos_triggers_list` · **Read** · Idempotent Lists the events a worker can subscribe to (the names to put in an event trigger's `events` on heliyos\_workers\_create / heliyos\_workers\_update), each with what it means and the object it is about. Also lists the mention and schedule kinds. Call it before creating a worker that reacts to events. Returns every trigger in one page. Returns structuredContent \{triggers:\[\{name, kind, label, description, object\_type, ...}]}. ### Inputs **kind** `string` Only event, mention or schedule triggers. One of `event`, `mention`, `schedule`. **object\_type** `string` Only triggers about this object: company, people, deals, task, note, interaction, review, signal, ... Up to 50 characters. ### Returns A readable text summary, plus `structuredContent` with `triggers`. ### API endpoints * [List triggers](https://docs.heliyos.ai/api-reference/workers-and-runs/list-triggers.md) · `GET /v1/platform/workers/triggers` * [List actions](https://docs.heliyos.ai/api-reference/workers-and-runs/list-actions.md) · `GET /v1/platform/workers/tools` ## List tools a worker can use `heliyos_workers_tools_list` · **Read** · Idempotent Lists the tools a worker may be given (the names to put in `tool_names` on heliyos\_workers\_create / heliyos\_workers\_update): Heliyos's own tools (source builtin) and the actions of the workspace's connected integrations (source action, for example sending email through the connected mailbox). Each has a risk class; communicate, write\_crm and external tools do things people will want to review. Call it before creating a worker. Returns every tool in one page. Returns structuredContent \{tools:\[\{name, label, description, source, risk, provider}]}. ### Inputs **source** `string` Only Heliyos's own tools (builtin) or only integration actions (action). One of `builtin`, `action`. **provider** `string` Only one integration's actions, for example gmail or hubspot. Up to 100 characters. **search** `string` Plain words matched against names, labels and descriptions. Up to 200 characters. **response\_format** `string` (default: concise) "concise" (default) returns name, label, description, source and risk; "detailed" returns each tool's input schema too. One of `concise`, `detailed`. ### Returns A readable text summary, plus `structuredContent` with `tools`. ### API endpoints * [List triggers](https://docs.heliyos.ai/api-reference/workers-and-runs/list-triggers.md) · `GET /v1/platform/workers/triggers` * [List actions](https://docs.heliyos.ai/api-reference/workers-and-runs/list-actions.md) · `GET /v1/platform/workers/tools` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.