Skip to main content

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.

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:
TypeDescription
Form templatePresents a form with fields. The user fills in the form and the agent runs a prompt using the values.
File uploadPrompts 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

1

Open agent configuration

Navigate to the agent you want to edit and open its configuration. Go to the Actions tab.
2

Add a new action

Click Add action and choose the action type (form template or file upload).
3

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.
4

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
5

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.
6

Save

Save the action. It will appear as a button in the agent’s interface immediately.

​
Form field types

TypeUse for
textShort free-text input
numberNumeric values
emailEmail addresses
selectChoosing from a predefined list of options
textareaLonger free-text input
checkboxYes/no toggles
dateDate values
attachmentFile 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.
Creating and editing actions requires admin permissions on the agent. Users with viewer access can run actions but not modify them.