Getting Started

You are building a Persi agent within Persuit: it has users, workspaces, tools, and a UI. PAI is the layer that makes that agent durable. This guide uses a small standalone app to show the same contracts without the rest of Persuit.

What you will have

• A server agent that answers on a durable thread (tools come next in Tools)
• An HTTP API the browser talks to
• A thread that stores the conversation
• A React chat that streams the reply

The path

1. First app — define an agent, mount it on Express, send a message from Node.
2. React chat — the same agent in a browser.

After that, the guides cover tools, identity, files, sandboxes, and tests.

How these docs are organized

1. Getting started — a working agent in one sitting.
2. Guides — one short page per feature. Nested pages (Testing, Tools, React) are the working set when the short page is not enough.
3. API reference — every public export, named as you import it. Use it to audit what exists.

Four words

Keep these four words. Almost every PAI API is one of them:

• Agent — what the model is allowed to do (instructions, tools, identity).
• App — createPai({ agents }). One process can host several agents.
• Thread — one durable conversation. Messages, tool calls, and files live here.
• Run — one turn of model work on a thread (a send).

Identity is decided on the server. The client never picks the workspace. Your Express resolveIdentity function is that decision.

browser  →  Express (who is this?)  →  PAI (run the agent)  →  thread
                ↑
          your session / JWT

A production-shaped stack

The getting-started app uses in-memory storage so it runs with no database. Persi's multi-process deployment uses production providers, with files and sandboxes configured as needed:

You do not change the agent when you change providers.

Next

Build the first app.