# Connect actions

Register a handler in your code for an action defined in Agent Studio, so the agent can run real logic in your product.

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.

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

```javascript
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](/guides/executing-actions/)** — run logic and return data the agent relays in its next reply.
- **[UI components in chat](/guides/in-chat-ui/)** — render an interactive component in the chat and send the user's input back to the agent.

:::note
See the **Developer Guide → [Coding Actions](https://foldspace.readme.io/docs/ai-actions-2)** for full implementation details.
:::

:::tip
Think of Studio as the **blueprint** for an action, and your application code as the **engine** that runs it.
:::

## Next steps

- [Execute actions](/guides/executing-actions/): what runs when the agent calls your handler, and how to return data.
- [UI components in chat](/guides/in-chat-ui/): render an interactive component from an action.