Foldspace Actions: Product Playbook

1. Overview

Actions are a core capability in Foldspace that allow AI agents to perform meaningful operations inside your product, rather than just responding with text.

This playbook serves as the standard for designing these interactions. It covers the available capabilities, how to choose the right interaction model, and the lifecycle of testing and optimizing agent behaviors.

2. Core Concepts: What are Actions?

Actions are deterministic, product-owned capabilities that allow a Foldspace agent to take action on behalf of a user. Unlike open-ended AI responses, Actions are designed for reliability, trust, and repeatable execution.

Requirements

An Action must:

Be Bounded: Have a clear and specific purpose.
Explicit Intent: Be executed based on clear user requests.
Product Grounded: Be rooted in your product’s logic, permissions, and UI.
Predictable: Produce a user-visible, consistent outcome.

[!IMPORTANT] Guiding Principle: If an interaction does not move the user forward, change their state, or reduce effort, it should not be an Action.

3. Use Cases: When to Build

From a user perspective, Actions should be deployed to assist with:

Category	Description
Navigation	Taking users directly to specific pages, tabs, or views.
Workflow Resolution	Assisting in complex, multi-step processes.
Operations	Executing CRUD (Create, Read, Update, Delete) operations.
Analysis	Summarizing or analyzing complex data sets.
Interoperability	Connecting workflows across different tools or systems.

4. Interaction Types & Architecture

Interaction types define how an Action is experienced by the user within the Foldspace interface. Note that all types can be triggered via Text or Voice.

Interaction Matrix

Interaction Type	Description	Ideal For
Text Action	Agent responds or executes using text.	Summaries, lightweight tasks.
Chatter Block	A structured UI component in the chat.	Graphs, User cards, Maps, System entities.
Navigation	Moves user to a specific page or state.	Orientation and discovery.
Tandem Mode	Real-time shared state/context.	Complex forms, collaborative flows.
Share Current Tab	Agent reads visible page (Read-Only).	Troubleshooting and analysis.

5. Design Guidelines & Best Practices

A. Text Action

Best for quick, one-step tasks or summaries that don't depend on UI context.

Do: Keep inputs minimal, execute immediately, and confirm success/failure.
Don't: Use for tasks requiring review or complex structured output.
Example: "Invite user [email]", "Turn on dark mode".

B. Chatter Block

Best for structured responses where the user doesn't need to be on a specific page.

Do: Use for data benefiting from visual structure (tables, lists). Allow follow-up actions from the block.
Don't: Use if the user must interact with a live screen to make a decision.

C. Navigation

Best for helping users find features or reducing discovery friction.

Do: Use when UI context is required for the next step.
Don't: Use navigation as the end goal itself; it is a means to an outcome.

D. Tandem Mode (Shared State)

Best for complex forms, multi-step flows, and configuration.

Do: Use when correctness matters (e.g., tax forms). Guide users step-by-step.
Example: "Fill out this expense report for me."

6. The Definition Framework

Before engineering an Action, validate the need using this three-step framework.

Step 1: Manual Walkthrough

Identify points of friction, "click tax," or areas where users hesitate. Actions should address real friction, not hypothetical improvements.

Step 2: Problem Classification

Does the user need help:

Doing an action?
Understanding information?
Finding a feature?
Completing a flow correctly?

Step 3: Action Design Checklist

Pain Point: What specific user pain does this remove?
Frequency: Is this frequent enough to warrant an Action?
Context: Does it require a specific page/UI context?
Discovery: How will users find it (proactive vs. reactive)?
Clarity: Will the user understand the outcome before execution?
Permissions: Are specific permissions required?

[!CAUTION] Red Flag: If an Action adds complexity instead of removing it, it must be redesigned.

7. Lifecycle: Testing & Optimization

Intent Testing

Use the Agent Playground to:

Test different phrasings (utterances).
Validate that the intent is recognized correctly.
Ensure the correct Action triggers (and not a generic response).

Optimization Levers

Refine Description: Clarify intent to reduce overlap with other Actions.
Improve Instructions: Tightening execution rules and success criteria.
Add Supporting AI: Use Knowledge Base for heavy lifting (reasoning) so the Action remains simple.

Metrics to Watch

Usage Rate: Is it being found?
Success/Failure Rate: Is it completing?
Latency: Is it fast enough?
Repeated Follow-ups: Are users re-asking? (Sign of low trust).

Closing Principle: Actions are about helping users reach outcomes faster, with less effort and more confidence. That is the standard every Foldspace Action should meet.