> ## Documentation Index
> Fetch the complete documentation index at: https://docs.circuit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating agent actions

> How to create agent actions that present structured input forms and trigger prompts with user-provided values.

An **action** is a structured interaction you can add to an agent. Instead of typing a free-form question, users click a button, fill in a form, and the agent runs a prompt using those values. Actions are useful for repeatable tasks where you want a consistent input format.

## Action types

Circuit supports two action types:

| Type              | Description                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| **Form template** | Presents a form with fields. The user fills in the form and the agent runs a prompt using the values. |
| **File upload**   | Prompts the user to upload files, optionally with additional form fields.                             |

## Anatomy of an action

Every action has four parts:

1. **Title and description** — what the user sees on the button and in the action's summary.
2. **Icon** — a visual identifier for the action.
3. **Form fields** — the inputs the user fills in (text, number, email, select, textarea, checkbox, date, or attachment).
4. **Prompt template** — the instruction sent to the agent when the form is submitted, with `{{variable}}` placeholders that get replaced by the form values.

## Creating an action

<Steps>
  <Step title="Open agent configuration">
    Navigate to the agent you want to edit and open its configuration. Go to the **Actions** tab.
  </Step>

  <Step title="Add a new action">
    Click **Add action** and choose the action type (form template or file upload).
  </Step>

  <Step title="Set title, description, and icon">
    Give the action a clear title that describes what it does. The description is optional but helps users understand when to use it.
  </Step>

  <Step title="Define form fields">
    Add the fields your action needs. For each field, configure:

    * **Label** — what the user sees
    * **Type** — text, number, email, select, textarea, checkbox, date, or attachment
    * **Required** — whether the field must be filled in
    * **Placeholder** — optional hint text
    * **Validation** — optional constraints like min/max values, length limits, or select options
  </Step>

  <Step title="Write the prompt template">
    Write the prompt that the agent will receive when the action is submitted. Use `{{field_name}}` to insert form values. For example:

    ```
    Convert {{value}} from {{source_unit}} to {{target_unit}}. Show your work.
    ```

    The prompt template is regular text — you can include any instructions you'd give the agent in a normal chat message.
  </Step>

  <Step title="Save">
    Save the action. It will appear as a button in the agent's interface immediately.
  </Step>
</Steps>

## Form field types

| Type           | Use for                                    |
| -------------- | ------------------------------------------ |
| **text**       | Short free-text input                      |
| **number**     | Numeric values                             |
| **email**      | Email addresses                            |
| **select**     | Choosing from a predefined list of options |
| **textarea**   | Longer free-text input                     |
| **checkbox**   | Yes/no toggles                             |
| **date**       | Date values                                |
| **attachment** | File uploads                               |

## Tips

* **Keep prompt templates specific.** The more precise your template, the more consistent the agent's output. Include format instructions, constraints, and expected output structure.
* **Use validation.** Setting min/max values and required fields prevents incomplete submissions and reduces agent errors.
* **Chain actions with follow-ups.** An action can reference up to five other actions as follow-ups. This lets you build multi-step workflows where one action leads naturally into the next.

<Note>
  Creating and editing actions requires admin permissions on the agent. Users with viewer access can run actions but not modify them.
</Note>