The step library

Library steps are server functions shipped with Studio that an automation can use without any code — and that an agent can call as tools. Each declares an input schema (the arguments form in the inspector) and an output schema (what Insert… offers to later steps). They live under /lib/studio/automations/library/ in the functions workspace.

Most of them default their workspace and path to the subject of the run, so “update the node this automation is about” needs no arguments at all.

Read an email — read-mail

A synced raisin:Mail as text an agent can work with.

Returns subject, from, from_address, reply_to, to, date, body (plain text, HTML stripped), outgoing, conversation_id, message_id, external_id, mailbox_path, the thread (every message in the conversation, oldest first, with outgoing marked) and thread_text, thread_count, is_first_message, awaiting_reply, and the attachments: attachments[] with the text the asset pipeline extracted (OCR for images and scans, text for PDFs and Office files), attachments_text as one block, and pending_attachments for those still being processed.

Triage a conversation — triage-mail-thread

Files the conversation a mail belongs to the way the Workplace board does.

Creates the thread on first touch, updates it after. Returns thread_path, created, the resolved category_path / category_label, tag_paths / tag_labels, priority, status, awaiting_reply, and unknown_category / unknown_tags for names that do not exist — nothing is invented.

Reply to an email — reply-to-mail

An outbound mail in the mailbox’s outbox, threaded by the provider.

The mailbox’s allowed recipient domains are enforced here as in the composer. Returns outbound_path, status (draft or queued), to, cc.

Send an email — send-email

A plain email from the platform’s mail service, not from a mailbox: to, subject, body. For notifications, not for correspondence with a customer — that is Reply to an email.

Update a node — update-node

Merges properties into a node. workspace and path default to the subject. An optional expected_node_type refuses the write when the node is of another type. Returns the node after the write and changed, the keys that actually changed — an empty changed after a requested change means a strict node type refused a key.

Create a node — create-node

workspace, parent_path, node_type, optional archetype, name (derived from the title when omitted), properties. Returns the new path.

Find nodes — find-nodes

workspace, optional node_type, under_path, where (property equals), search (title contains), limit. Returns count, nodes[] with their properties, first, and listing — one line per match, path — title, the shape an agent prompt wants.

Call a URL — http-request

method, url (HTTPS only), headers, body. Returns status, headers, body (parsed when JSON).

Send a task — create-task

A task in someone’s Inbox that the automation does not wait for: assignee, title, description, task_type, optional options and attached data. The waiting kind is the Ask a person step.

Set lights, List lights, Recall a scene

Philips Hue through the connector: set a light, room or zone (power, brightness, colour, colour temperature) as one grouped write; list the inventory with state; recall a scene through the scene outbox. The target is picked by name. See Connectors and mounts.

Adding your own

A function in your package becomes a library step by declaring category: automation-library and a metadata.library block in its .node.yaml:

node_type: raisin:Function
properties:
  name: create-ticket             # must equal the folder name
  title: Create a ticket
  description: Open a ticket in the helpdesk from a conversation.
  language: javascript
  execution_mode: async
  entry_file: index.js:handler
  category: automation-library
  metadata:
    library:
      icon: ticket
      group: tool                 # tool | agent | control
      order: 50
      verb: ticket
      subject_defaults:           # fill from the run's subject
        workspace: workspace
        path: subject_path
  input_schema:
    type: object
    required: [workspace, path]
    properties:
      workspace: { title: Workspace, type: string }
      path: { title: Conversation, type: string }
      queue: { title: Queue, type: string, enum: [billing, technical] }
  output_schema:
    type: object
    properties:
      ticket_id: { type: string, title: Ticket }
      url: { type: string, title: Link }

The input schema becomes the arguments form; the output schema becomes what Insert… offers; the same function is offered to every agent as a tool. format: multiline, format: assignee and format: node-type on a string pick a better control.