Execute (text-only) actions

An execute-only action runs work and hands data back to the agent. There is no UI: when the agent invokes the action, it awaits your execute(params) function, takes whatever you return, and uses that data in its next chat message.

Reach for an execute-only action when the result is information the agent should reason over or relay in text: creating a record, calling an API, looking up a value. If you instead need to render an interactive component in the chat stream, see Execute and Render actions.

Action handler options

Property	Type	Default	Required	Description
execute	(params: any) => Promise<any>	N/A	Yes	Handler for your async task; must return a Promise with data.
render	<see Render Options below>	N/A	No	Optional UI: either a built-in component key or a custom render function to inject interactive UI.
awaitUserInput	boolean	false	No	When true, the agent will pause and wait for user interaction before continuing.
timeout	number	5000	No	Milliseconds 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

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}`
          };
        }
      }
    });
});

Related

• Execute and Render actions: return an interactive Chatterblock UI instead of text-only data.
• Connecting actions in your application: wire an action key and schema into your product code.