Skip to content
Foldspace Developers

Authoring actions

Open in ChatGPT Open in Claude 
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.

Action list

Section titled “Action list”

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

Section titled “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

Section titled “Instructions tab”

The primary configuration tab:

FieldPurpose
DescriptionExplain 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.”
InstructionsTell 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 KeyA 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 MessageOptional. Enable the toggle and write a message shown to the user before the action executes — useful for destructive or irreversible actions.
AdvancedExpand 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.

User Input tab

Section titled “User Input tab”

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

Evaluations tab

Section titled “Evaluations tab”

Configure how the action’s result is evaluated before the agent uses it in a response — useful for validating API responses or filtering unexpected outputs.

How To Embed? tab

Section titled “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.

Publishing vs. draft

Section titled “Publishing vs. draft”

Actions must be Published before the agent can use them. Use the Publish button in the top-right when the action is ready. The version number (v1, v2…) increments each time you publish. If the live version and latest version differ, a draft exists that hasn’t been published yet.

Next steps

Section titled “Next steps”