Build actions

Agent Builder

The Agent Builder is the recommended way to build what your Product Agent can do inside your product: actions and the code behind them, task agents, navigation routes, and the cards the agent draws in chat. It runs in your coding tool (Claude Code, Codex, or Cursor). You describe the experience you want. The builder opens your app in a local browser, puts the agent on your page, writes the code, tests it by talking to the agent, and creates the actions and task agents in your Foldspace account.

You don’t need to be a developer. The builder runs the commands; your part is to sign in, talk to the agent, and say yes or no when it asks.

Choose how to build

	Agent Builder (recommended)	Agent Studio
You work in	Claude Code, Codex, or Cursor	The Foldspace dashboard
You describe	The experience, in your own words: “show a customer’s open deals”	Each action’s name, instructions, and input schema, field by field
The code behind each action	Written, loaded, and tested for you against your real app	Written by your developers and registered in your app
You end with	A working experience you have tried on your own page	Action definitions, ready for code

To build by hand instead, start with Authoring actions, Defining inputs, and Task Agents, then wire the code with Connect actions.

What the Agent Builder is made of

Part	What it does	Where it lives
The start prompt	Tells your coding tool to set up Foldspace and then keep building	foldspace.ai/start
The setup playbook	Connects the Foldspace tools, confirms your account and agent, picks a folder, and creates the project	foldspace.ai/agents.md
Foldspace MCP server	Gives your coding tool your agent: its actions, task agents, navigation routes, and conversation starters	`https://api.foldspace.ai/mcp` (sign in with your Foldspace account)
Foldspace Docs MCP server	Search over these docs, so your coding tool checks how Foldspace behaves instead of guessing	`https://docs.foldspace.ai/mcp` (no sign-in)
The project	A folder on your computer, named `foldspace-<agent-key>`, holding the code behind your actions and the build manual	Created from the `@foldspace_npm/harness` package
The Claude Code plugin	Installs both MCP servers in one step	`foldspace-agent-builder`

The build rules your coding tool follows ship inside the project, in node_modules/@foldspace_npm/harness/CLAUDE.md. The project’s own CLAUDE.md (Claude) or AGENTS.md (Codex, Cursor) points to it, so every coding tool works from the same manual, and upgrading the project upgrades the rules.

Most builds start where sign-up ends.

Sign up and name your product. Foldspace creates your agent and discovers the key use cases for your product. The use cases are saved to your agent, so the builder reads them later through the Foldspace MCP server.
On the “You’re all set.” screen, choose your tool. Under Start building with, click Claude Code, Codex, or Cursor. The screen also lists how many use cases were found, with a link to open them. Prefer to paste? Click Copy prompt.
Press Enter. Your coding tool opens a new session with the prompt typed in, and nothing runs until you send it. In an empty folder you made for your agent, it sets up right there. Anywhere else, it creates a new folder, or reuses the one it made for this agent before. It never sets up inside another project or git repository.
Sign in to Foldspace. The builder connects to Foldspace through the Foldspace MCP server and opens Foldspace’s sign-in page in your browser. Sign in with your Foldspace account. This one sign-in lets the builder create and update actions, task agents, and navigation routes in your account.
Give it your product’s web address, for example app.example.com. It asks once. If your account has several agents, it also asks which one.
Sign in to your product in the test window. The builder opens your product in a separate Chrome window on your computer and puts the agent on the page. Everything in that window is local to your machine until you publish.

If the use cases weren’t saved at sign-up, the screen says Use cases will be found when you start building, and the builder discovers them itself.

Start from foldspace.ai/start

Already signed up, or building on a second computer? Open foldspace.ai/start and choose Open in Claude, Open in Codex, or Open in Cursor. It opens your coding tool with the same prompt, and the build continues from step 3 above. To paste the prompt yourself, use it as written:

Read https://foldspace.ai/agents.md and follow it to set up my Foldspace agent. Then keep going with the project's own instructions (its CLAUDE.md or AGENTS.md) and help me build a new experience for my product agent. I already have a Foldspace account, and my agent already exists.

Each coding tool handles a newly added server differently:

Claude installs the Foldspace tools, opens sign-in in your browser, and waits for you. When the project is in a different folder, it asks to move the session there: click Trust workspace, then tell it to continue.

Connect the Foldspace tools yourself

The start prompt connects the tools for you. To connect them ahead of time, install the plugin in Claude Code:

claude plugin marketplace add https://github.com/foldspace-ai/plugins

claude plugin install foldspace-agent-builder@foldspace-plugins

Then run /mcp, pick foldspace, and finish sign-in in the browser. The plugin needs git on your machine. It is a Claude Code plugin only; Codex and Cursor connect the MCP servers directly, and the build rules reach every tool through the project either way.

Without the plugin, add the servers to your coding tool:

claude mcp add --scope user --transport http foldspace https://api.foldspace.ai/mcp

claude mcp add --scope user --transport http foldspace-docs https://docs.foldspace.ai/mcp

codex mcp add foldspace --url https://api.foldspace.ai/mcp

codex mcp add foldspace-docs --url https://docs.foldspace.ai/mcp

The first command also starts sign-in.

Merge this into ~/.cursor/mcp.json, keeping the servers already there:

{
  "mcpServers": {
    "foldspace": { "url": "https://api.foldspace.ai/mcp" },
    "foldspace-docs": { "url": "https://docs.foldspace.ai/mcp" }
  }
}

For VS Code, Windsurf, and Antigravity, see Vibe coding.

What your first session builds

The first session ends at something you can see on your own page, in three levels:

Level	You see
Agent live	The agent on your own product page, before it has a single action
Your settings	Your own account, plan, or settings on a card, with real values
Look up records	A search from your own words, returning rows from your account

How it gets there:

A separate Chrome window opens at your product’s login. Sign in there. The builder notices on its own. This window is a test window with its own browser profile; it keeps your sign-in for next time.
The agent appears on your page. The builder sends you a screenshot and asks you to say hello to it.
It offers three or four experiences to start with, recommended first, from the use cases discovered at sign-up, your product’s own menu, and the conversation starters set up at sign-up. The first ones only read data.
You agree the experience in plain words before it creates anything, for example: “Show my plan and credits needs one new action on your agent and one card to show it in. Sound right?”
It builds and tests it, then hands the test window back to you to try.

While the builder works in the test window, a pill at the foot of the page says Foldspace is building. Leave the window alone until the builder says it’s ready.

Build an action

An action has two halves. The action lives in Agent Studio and tells the agent when to use it. The code behind it lives in your project, in agent/actions/<action_key>.ts, and does the work. The builder writes both.

For each action, the builder:

Finds the call your app makes. It watches your app in the test window, read-only, and captures a real response for the data the action needs. It never guesses an endpoint or a field name.
Creates the action as a draft in Agent Studio, with every parameter typed, marked required or not, and described by where its value comes from. That description is how the agent chains actions: a required accountId described as coming from find_account makes the agent call find_account first.
Writes the code behind it from the draft’s schema, and registers it in agent/actions/index.ts. The key must equal the action’s key in Agent Studio; a mismatch doesn’t error, the action never fires.
Loads it into the test window and checks that the agent registered it.
Asks you before publishing the action. Once published, it asks the agent the question itself and checks that the reply, and the card, show real data from your account.

The code behind an action returns data and nothing else:

import { apiFetch, rankBy } from "../utils";

type Project = { id: string; name: string };

export const find_project = {
  execute: async (params: { query?: string }) => {
    const query = typeof params?.query === "string" ? params.query.trim() : "";

    const result = await apiFetch<{ items?: Project[] }>("/YOUR-API-PATH");
    if (!result.ok) {
      return { success: false, error: result.error, reason: result.reason };
    }

    const matches = rankBy(result.data.items ?? [], query, {
      searchKeys: ["name"],
      idOf: (project) => project.id,
    });

    return { success: true, query, matches };
  },
};

A few rules the builder holds every action to:

It returns facts, never instructions. “Try again” or “ask the user for the full name” in a response can make the model act on its own. What the agent does next belongs in the action’s instructions in Agent Studio.
No results is a result. A search that finds nothing returns success: true with zero matches, not an error.
A failed or signed-out call is never drawn as zeros. Every failure carries a reason (signed_out, forbidden, not_found, rate_limited, timeout, unreachable, config, server), and the card shows that state.

For the handler API in depth, see Connect actions and Execute actions.

Build a task agent

A task agent handles one reasoning job that code can’t: extracting, summarizing, classifying, or normalizing. It isn’t for API calls, creating or updating records, routing, or parsing a response whose shape you already know; those stay in code.

The builder creates the task agent in Agent Studio, asks you before publishing it, and calls it from the code behind an action with getAgent().runTask({ taskKey, data }). A task agent must be published before code can call it. data carries facts; the instructions live on the task agent, never in the call.

A typical pairing: the action gathers a meeting’s facts from your API in code, then a task agent writes the summary from them. Ask for it in your own words, for example “Prepare me for my next meeting with a customer.”

For the Agent Studio side (instructions, output schema, model, logs), see Task Agents. For runTask() options, see Task Agent API.

Navigation lets the agent take the user to the right screen. A route is a URL template plus a description of what the page is for, in the words a user would use. There is no code behind it.

The description decides whether the route is ever offered. “Where a team keeps the work for one project, to find or share its designs” retrieves; “all files inside one project” does not.
Every route with a parameter needs a lookup action. /projects/{projectId} works only if an action can turn a project’s name into its id. The builder builds the two together, or neither.
Navigation has two switches, and both must be on: each route’s own active switch, and one switch for the agent’s navigation as a whole, which is off on a new subscription.

A new route reaches your users as soon as both switches are on, so the builder asks before turning them on.

Build an experience

An experience is what a user asks for and what they get back: one or more actions, and usually a card drawn in the chat. Name it by its outcome (“show my plan and credits”, “find a customer by name”), and the builder picks the pieces.

Cards come in two kinds:

Card	What it does	The agent
View card	Shows something: an account, a list, records that need attention	Answers follow-up questions from exactly what the card shows
Input card	Asks the user to pick one, upload, create, or approve	Waits until the user answers or closes it

Anything that writes to your product goes behind an input card the user approves. The builder samples your app’s colors, font, and corner radius so cards match your brand inside the agent’s panel.

The project ships working examples, each taken from production builds, that the builder copies from:

Ask for	Example the builder starts from
Show one account a user names	`lookup-then-view`
Turn a name into the id the next action needs	`find-by-name`
The user’s records on one card	`records-list`
Records that need attention, with reasons	`opportunities-at-risk`
Create a record from what the user said, approved on a card	`create-a-record`
Gather facts, then have a task agent write a summary	`prepare-for-a-meeting`
Starters in the Bottom Bar that change per screen	`bottom-bar`
Tell Foldspace who the signed-in user is	`who-is-the-user`

After you’ve tried the first experience, the builder offers the next steps as one choice: replacing your conversation starters with ones the agent can answer (at most three, with your yes), starters per page, identifying your users so conversations and analytics stop being anonymous, a second experience, and a short video of the agent to share.

Publish to your users

While you build, the experience runs only in the test window on your computer. The actions and task agents the builder creates are in your Foldspace account, but your users don’t see them yet: the agent offers an action only when the code behind it has loaded in the user’s browser.

When you’ve tried the experience and you’re happy with it, ask the builder to publish it (“publish this”, “push it live”). It publishes the actions, task agents, and code behind them and deploys them for you.

It asks before anything reaches your users. Publishing an action, task agent, or navigation route, and deploying the code, each wait for your yes.
Live things are never edited to test. Publishing an edit to something already live changes the live agent at once. To change a live action, the builder builds a copy beside it, named with _gen2, and switches over when the copy works.
Several builders can share one agent. Before each publish, the builder pulls what others have saved for the same agent, so nobody’s work is overwritten.

What the builder won’t do

Edit your product’s source code or your website. It works only in its own project folder.
Write anything while it browses your app. It reads only, and asks before clicking a button that could do something.
Publish, replace your conversation starters, or add hosts without your yes.
Create accounts or API keys, in Foldspace or in your product.
Store or send your sign-in token anywhere but your product’s own backend. The build refuses tokens, keys, and cookie values in the project.
Send your users out of your product. Links go through navigation, in the same tab.

Troubleshooting

Where are the use cases from sign-up? In Agent Studio, under your agent’s use cases, and on the “You’re all set.” screen behind the use cases found link. The builder reads the same list, so you can name one in your coding tool: “Build the account overview use case.”

The Foldspace tools aren’t available in this chat. The server was added after the chat started. Open a new chat in the project folder and repeat your request.

It’s signed in to the wrong account. In Claude Code, run /mcp, pick foldspace, and sign in as the right account. In Codex, run codex mcp logout foldspace, then codex mcp login foldspace. The builder names the agent it’s working on before it creates anything, so you can stop it there.

Your account has no agent. Create one at app.foldspace.ai, then tell the builder you’re done.

The agent shows on one part of your product but not another. Products that live on several hosts (app., reports., admin.) need each one added. The builder finds the other hosts and asks before adding them.

Your test conversations appear in Foldspace. That’s expected on a new agent: seeing them recorded is part of the first session. On an agent that already has real users, the builder runs in test mode to keep its conversations out of your data.

You’re picking up on another computer, or a colleague started the agent. The builder checks what Foldspace already holds for your agent and starts from the saved code when there is any.

Vibe coding: connect the Foldspace MCP servers to other editors.
Task Agents: configure, test, and tune task agents in Agent Studio.
UI components in chat: how cards render, in depth.
Authoring actions: define actions in Agent Studio by hand.