# Execute actions

Write the execute() handler that runs your action's logic and returns data the agent uses in its next reply.

`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](/guides/in-chat-ui/) under **Agentic UI**.

:::note[Prerequisites]
You've [defined an action](/user-guides/authoring-actions/) in Agent Studio and [connected a handler](/guides/connecting-actions/) for it.
:::

## 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` | `(data, host, header, callback, cancel) => void` | N/A | No | Optional. Draw an interactive component in the chat from the data `execute` returns — see [UI components in chat](/guides/in-chat-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`). |

<Mermaid chart={`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.

```javascript
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

- [UI components in chat](/guides/in-chat-ui/): render an interactive component in the chat instead of returning plain data.
- [Connecting actions in your application](/guides/connecting-actions/): wire an action key and schema into your product code.