Skip to content
Foldspace Docs
Talk to an engineer

Agent Studio

Authoring actions

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.

Writing the Description and Instructions

Section titled “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; keep Instructions about intent.
  • Tune from evidence, not guesses. When Evals show a misroute or a bad extraction, edit the description or a field description and re-run, rather than rewriting blind.

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”

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 for the full workflow.

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, versioning, and rollback

Section titled “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 for the full model.

Next steps

Section titled “Next steps”