Skip to content
Foldspace Docs
Talk to an engineer

Build actions

Execute actions

execute is the code behind an action. When the agent invokes the action, it awaits your execute(params) function and uses whatever you return in its next chat message. There’s no UI — just logic that runs and data that comes back.

Reach for this whenever the result is information the agent should reason over or relay: creating a record, calling an API, looking up a value. To draw an interactive component in the chat instead, see UI components in chat under Agentic UI.

Action handler options

Section titled “Action handler options”
PropertyTypeDefaultRequiredDescription
execute(params: any) => Promise<any>N/AYesHandler for your async task; must return a Promise with data.
render(data, host, header, callback, cancel) => voidN/ANoOptional. Draw an interactive component in the chat from the data execute returns — see UI components in chat.
awaitUserInputbooleanfalseNoWhen true, the agent will pause and wait for user interaction before continuing.
timeoutnumber5000NoMilliseconds to abort the execute call (default 5000).
sequenceDiagram
  participant U as User
  participant A as Agent
  participant H as execute(params)
  participant API as Your API
  U->>A: Natural-language request
  A->>A: Extract params from intent
  A->>H: Call action handler
  H->>API: fetch / POST / query
  API-->>H: Response data
  H-->>A: Return result object
  A->>U: Chat message using returned data

Example

Section titled “Example”

This create_task action POSTs the agent-supplied params to an API and returns the created record. Return every field the agent might need later in the conversation: here, including a link means the agent can answer a follow-up like “What’s the link?” without another call.

foldspace("when", "ready", () => {
  foldspace.agent({ /* …common setup… */ })
    .addActionHandlers({
      create_task: {
        execute: async (params) => {
          const {title, body} = params;
          const response = await fetch('https://jsonplaceholder.typicode.com/posts', {
            method: 'POST',
            body: JSON.stringify({
              title,
              body,
              userId: 'playground',
            }),
            headers: {
              'Content-type': 'application/json; charset=UTF-8',
            },
          });
          const data = await response.json()


          // Return all relevant fields so the agent can reference them later
          return {
            id: data.id,
            title: data.title,
            body: data.body,
            userId: data.userId,
            // Include a link property—if the user asks "What's the link?", the agent can supply this
            link: `https://jsonplaceholder.typicode.com/posts/${data.id}`
          };
        }
      }
    });
});
Section titled “Related”