PAI

PAI is a TypeScript framework for building durable AI agents with React, HTTP, CLI, and in-process clients.

The normal path is small:

const agent = defineAgent({ ... });
const pai = createPai({
  agents: { main: agent },
  scopeKey: (identity) => identity.workspaceId,
});
app.route("/api/pai", createPaiHonoReceiver({ pai, resolveIdentity }));

const paiClient = createPaiHttpClient({ url: "http://localhost:3001/api/pai" });
const assistant = paiClient.agent("main");
const thread = assistant.thread(assistant.newThreadId());
const run = await thread.send("Draft a report");

await run.waitUntilIdle();

PAI keeps durable state in threads. A thread is the source of truth for messages, pending actions, files, queued items, and run status. Clients can render the latest thread state without knowing how the server stores or streams it.

Start Here

• Getting Started: build a minimal HTTP-backed agent.
• React: create/open threads and render chat in a browser app.
• Concepts: understand agents, runtimes, threads, runs, and clients.
• Contract Types: share agent types without importing server runtime code.

Documentation Map

• Getting Started: the shortest path to a working app.
• Agent: define agent behavior, context, tools, commands, and lifecycle hooks.
• Runtime: run agents in-process for CLIs, jobs, tests, and custom servers.
• Server: expose agents over HTTP frameworks.
• Client: use threads, runs, live state, files, queueing, and errors.
• React: build typed UI over threads.
• Error Handling: surface safe errors and correlate them with trusted server diagnostics.
• Agent Testing: test tools, runtime workflows, and model decisions.
• React Testing: test React renderers, hooks, chat UIs, and client tools.
• Observability: trace runs, model steps, tools, and runtime work.
• Concepts: durable mental models and invariants.
• Recipes: complete copyable examples.
• Advanced: transport, runtime, and protocol internals.
• API Reference: exact public package surfaces.

Core Guides

• Define An Agent
• Serve An Agent
• Create A Client
• Threads
• React Setup
• React Codegen
• Error Handling
• Agent Testing
• React Testing
• Tools
• Suspend And Resume
• Client Tools
• Scope And Access

Recipes

• Production Workspace App
• Human Input UI Patterns
• Client Tool
• CLI / In-Process Agent
• Busy Thread Queueing

Advanced

• How It Works: runtime pipeline, lifecycle phases, state projections, and queueing.
• Providers: storage, realtime, and files.
• Transports: HTTP/SSE, custom transports, watch delivery, and protocol conformance.
• Contract Types: type-only imports, client-safe packages, and generated bindings.

API Reference

Use the API Reference once you know the concepts and need exact shapes.