Build actions

Connect actions

An action has two halves. In Agent Studio, you define what it is — a name, a description, and the input schema the agent fills in from the user’s request. In your code, you implement what it does. Connecting an action wires those halves together: you register a handler under the action’s key, and the agent calls it whenever it routes a request to that action.

flowchart LR
  subgraph STUDIO["Agent Studio"]
      D[Define action<br/>name & description]
      S[Set input schema<br/>& response mock]
      P[Publish version]
  end
  subgraph CODE["Your application"]
      C[Take action key<br/>& schema]
      I[Register handler<br/>under that key]
      W[Run logic, return<br/>data or render UI]
  end
  D --> S --> P
  P -- "key, schema,<br/>expected output" --> C
  C --> I --> W

What you need from Studio

To connect an action, take three things from its definition in Agent Studio:

Item	What it is
Action Key	The action’s unique identifier (e.g. `create_task`, `invite_user`). You register your handler under this exact key.
Input Schema	The fields the agent extracts and passes to your handler as `params` (e.g. `email`, `name`, `organizationRoleType`).
Expected Output	What the action should do, plus any data the agent should use in its reply — for example, a link to deep-link the user to a page.

Register a handler

Register handlers on the agent with addActionHandlers. Each key matches an Action Key from Studio, and the agent calls that handler with the schema fields as params:

foldspace("when", "ready", () => {
  foldspace.agent({ /* …common setup… */ })
    .addActionHandlers({
      create_task: {
        execute: async (params) => {
          // `params` matches the action's input schema, e.g. { title, body }
          // …do the work, then return data for the agent…
        },
      },
    });
});

What goes inside the handler depends on what the action should return:

Execute actions — run logic and return data the agent relays in its next reply.
UI components in chat — render an interactive component in the chat and send the user’s input back to the agent.

Next steps

Execute actions: what runs when the agent calls your handler, and how to return data.
UI components in chat: render an interactive component from an action.