# Authoring actions

Define the capabilities your agent can call to do real work inside your product, then publish them so the agent can use them.

<Mermaid chart={`flowchart LR
    A["Author action<br/>in Agent Studio"] --> B["Define inputs<br/>& schema"]
    B --> C["Developer connects<br/>handler in code"]
    C --> D["Agent calls action<br/>at runtime"]
    style A fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style B fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style C fill:#e8ecff,stroke:#1842ef,color:#0a0e1a
    style D fill:#1842ef,stroke:#1842ef,color:#ffffff
`} />

**Path:** Agent Studio → Actions

Actions are things the agent can *do* — not just say. Each action connects to a function in your product: an API call, a page navigation, or a form submission. You define and test actions here; your developers then [wire them to your product's logic](/guides/connecting-actions/).

:::tip[New to actions?]
This page is the reference for the Actions editor. For the full path from writing an action to watching it run live, read [The action lifecycle](/user-guides/action-lifecycle/) first.
:::

## Action list

<ActionsListScreen />

The Actions table shows every action with:

- **Display Name** — the human-readable name (e.g., "Create New Project").
- **Action Key** — the programmatic identifier (e.g., `create_project`).
- **State** — `Published` (live and available to the agent) or `Draft` (not yet active).
- **Type** — the action type (e.g., API call).
- **Live version / Latest version** — version numbers; if they differ, a newer draft exists that hasn't been published yet.
- **Modified Date** — when the action was last edited.

## Create an action

Click **Create Action** in the top-right. The action editor opens with four tabs: **Instructions**, **User Input**, **Evaluations**, and **How To Embed?**

### Instructions tab

<ActionEditorScreen />

The primary configuration tab:

| Field | Purpose |
| :--- | :--- |
| **Description** | Explain what the action does and what it returns, so the AI knows when to use it. Be specific — e.g., *"Retrieves details for a specific deal, such as its stage, value, and assigned owner."* |
| **Instructions** | Tell the AI *when* to trigger this action, especially if it depends on context or user intent. E.g., *"Use when the user asks for deal status or details about a specific opportunity."* |
| **Action Key** | A unique identifier used to call the action in the SDK. Auto-generated from the action name, but editable. Copy it with the clipboard icon. |
| **Confirmation Message** | Optional. Enable the toggle and write a message shown to the user before the action executes — useful for destructive or irreversible actions. |
| **Advanced** | Expand for additional configuration options. |

The **Foldspace AI assistant** on the right can help you build actions — use its starter prompts ("Help me create a new action", "Show me examples of common actions", "What are actions and how do they work?") for guidance.

:::tip[Confirmation messages]
Wrap an input parameter in double curly braces to substitute the user's value into the message — for example, `Are you sure you want to invite {{email}}?`
:::

#### Writing the Description and Instructions

These two prompts are what the agent reads to decide whether to call your action. They do different jobs, keep them distinct:

- **Description answers "what does this do?"** Write it for the agent, in plain, specific terms, and always say what the action *returns*. Vague descriptions are the most common reason an action never fires. Prefer *"Retrieves the stage, value, and owner for a specific deal"* over *"Gets deal info."*
- **Instructions answer "when should I use this?"** Spell out the user intents and phrasings that should trigger it, and just as importantly, when *not* to. This is where you disambiguate actions that look similar (for example, "look up a deal" vs. "create a deal").

Good prompting practices:

- **One clear job per action.** If a description needs "and" several times, it's probably two actions.
- **Name the trigger intents explicitly.** "Use when the user asks for deal *status* or *details* about a specific opportunity."
- **Distinguish look-alikes.** When two actions could match, state the boundary in both Instructions so the agent picks correctly.
- **Don't restate the schema in prose.** Field-level guidance belongs in the [input descriptions](/user-guides/defining-inputs/); keep Instructions about intent.
- **Tune from evidence, not guesses.** When [Evals](/user-guides/evals/) show a misroute or a bad extraction, edit the description or a field description and re-run, rather than rewriting blind.

:::note[The agent also draws on your Knowledge Base]
At runtime the agent automatically pulls relevant [Knowledge Base](/user-guides/knowledge-base/) content and uses it to *operationalize* the action, not just to answer questions. If you keep an article describing how a job should be done well (for example, what makes a good **Create Campaign** — sensible budget pacing, naming conventions, required dates), the agent applies that guidance when it fills and runs the action. You don't link the article to the action; write the best practice in Knowledge and the agent retrieves it by relevance.
:::

### User Input tab

Define the parameters the agent should collect from the user (or infer from context) before calling the action. See [Defining inputs](/user-guides/defining-inputs/) for the full schema reference.

### Evaluations tab

Test that the agent ties **user intent to this action** — that real phrasings route here and the schema fields get extracted correctly — before you publish. Generate test prompts or write your own, run them, and inspect the raw argument extraction. See [Evals](/user-guides/evals/) for the full workflow.

### How To Embed? tab

Shows the code snippet for calling this action from your product's frontend via the Foldspace SDK. This is where developers pick up — see [Connecting actions](/guides/connecting-actions/).

## Publishing, versioning, and rollback

Every save creates a new version; actions must be **Published** before the agent can use them. Use the **Publish** button in the top-right when the action is ready and its handler is deployed. If the live version and latest version differ, a draft exists that hasn't been published yet.

To **roll back**, open the version dropdown, select a previous known-good version, and publish it — that immediately becomes Live again. Old versions are never deleted, so a rollback is always one publish away. See [Publishing & versioning](/user-guides/publishing-versioning/) for the full model.

## Next steps

- [Define inputs with a schema](/user-guides/defining-inputs/) so the agent can extract user data into structured fields.
- [Connect the action in your application](/guides/connecting-actions/) to make it execute (for developers).
- See the whole flow end to end in [The action lifecycle](/user-guides/action-lifecycle/).
- Measure how often the action runs, and how it performs, in [Actions](/user-guides/analytics/actions/).