Workers, triggers and tools

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

​

Returns

A readable text summary, plus structuredContent with workers.

​

API endpoints

• Get a worker · GET /v1/platform/agents/{id}
• List workers · 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

​

Returns

A readable text summary, plus structuredContent with worker.

​

API endpoints

• Get a worker · 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

​

Returns

A readable text summary, plus structuredContent with worker.

​

API endpoints

• Get a worker · GET /v1/platform/agents/{id}
• Create a worker · 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

​

Returns

A readable text summary, plus structuredContent with worker.

​

API endpoints

• Get a worker · GET /v1/platform/agents/{id}
• Update a worker · 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

​

Returns

A readable text summary, plus structuredContent with worker_id, deleted.

​

API endpoints

• Get a worker · GET /v1/platform/agents/{id}
• Delete a worker · 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

​

Returns

A readable text summary, plus structuredContent with triggers.

​

API endpoints

• List triggers · GET /v1/platform/workers/triggers
• List actions · 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

​

Returns

A readable text summary, plus structuredContent with tools.

​

API endpoints

• List triggers · GET /v1/platform/workers/triggers
• List actions · GET /v1/platform/workers/tools