PAIAPI Reference
Audit the public APIs. Grouped by package, named as you import them.
Learn in Getting started and the guides. Come here to see what exists and the constructor / hook signature. Package child pages are the audit surface when a public API changes.
Every public schema (identity, tool input/output, suspend, resume) is Zod.
Call these first
| Import | From | Guide |
|---|---|---|
createPai | @pai/core | Define an agent |
createPaiExpressReceiver | @pai/express | Serve |
createPaiHttpClient | @pai/client-http | First app |
createPaiReact | @pai/react | React |
defineAgent | @pai/core | Define an agent |
defineTool | @pai/core | Tools |
Pai.agent("main").useChat() | binding | Chat |
@pai/core
Server. Do not import this in the browser.
| Export | Purpose |
|---|---|
defineAgent | Agent: model, identity, instructions, tools, commands |
defineTool | Server tool, client-routed tool, or suspend tool |
defineCommand | UI/server operation, no model turn |
defineSubagentTool | Parent tool that runs a child agent |
createPai | App registry. Options include scopeKey, userKey, mapError, live |
InferPaiContract / InferAgentContract | Contract types for the client |
createAgentRuntime | One agent, no HTTP. Prefer createPai |
composeLifecycle | Run hooks |
createContextCompaction | Built-in compaction |
defineCapability | Named capability (sandbox uses this) |
HTTP and clients
| Package | Export | Purpose |
|---|---|---|
@pai/express | createPaiExpressReceiver | Mount createPai on Express |
@pai/receiver-http | createHttpAgentReceiver | Framework-neutral routes |
@pai/client-http | createPaiHttpClient | Browser/Node HTTP + SSE |
@pai/client | createAgentClient, Thread | Transport-agnostic thread API |
@pai/client | ThreadBusyError | Send while the thread is busy |
@pai/receiver-socketio | createPaiSocketIoServer | Socket.IO door |
@pai/client-socketio | createPaiSocketIoClient | Socket.IO client |
Same createPai app. HTTP/SSE is the default.
@pai/react
| Callable | Purpose |
|---|---|
createPaiReact | Root, Provider, agent() — package import |
Pai.agent("main").useChat() | Transcript, send, stop |
useComposer() | Draft text and attachments |
Pai.agent("main").useThreads() | Thread list |
Pai.agent("main").useThread() | Handle, useClient |
Tool | Tool cards |
useClientTool | Browser tools |
useFileUrl | Attachment URLs |
useSubagent | Child-thread ref |
Full @pai/react page · Chat · Tool UI
Persistence and live
| Package | Export | Purpose |
|---|---|---|
@pai/storage-mongo | createMongoThreadStore | Production threads. Call initialize() |
@pai/storage-inmemory | createInMemoryThreadStore | Tests and the first app |
@pai/storage | ThreadStore | Provider contract |
@pai/files-mongo | createMongoFileProvider | GridFS attachments |
@pai/files-inmemory | createInMemoryFileProvider | Tests |
@pai/files | FileProvider | Provider contract |
@pai/realtime-redis | createRedisThreadLiveProvider | Cross-process watch |
@pai/realtime-inmemory | createInMemoryThreadLiveProvider() | Tests (no extra options) |
@pai/realtime | ThreadLiveProvider | Provider contract |
In-memory thread storage is the createPai default. See Serve.
Sandbox
| Package | Export | Purpose |
|---|---|---|
@pai/sandbox | sandboxTools, sandboxCapability | Agent tools + binding |
@pai/sandbox-gke | createGkeSandboxProvider | GKE provider |
@pai/sandbox/memory | createInMemorySandbox | Tool tests |
Testing
| Package | Export | Purpose |
|---|---|---|
@pai/test-utils | runTool | One execute |
@pai/test-utils | createTestUtils | Mock model + selectors |
@pai/test-utils | createTestRuntime, stubTools | Runtime tests |
@pai/test-utils | runAgentEval | Evals |
@pai/react-test-utils | createReactTestUtils | toolProps, createClientHarness |
Other
| Package | Export | Purpose |
|---|---|---|
@pai/cli | pai generate client, pai generate skills | Typed client folder; compiled skills module |
@pai/observability | createPaiOpenTelemetry | Traces |
@pai/langfuse | createLangfuseSpanProcessor | Langfuse export |
@pai/skills | defineSkills | Skill catalog and skill tool |
@pai/skills/generate | generateSkills | Compile skill folders from Node |
@pai/skills-office | officeSkills | Word, Excel, and PowerPoint skills (need a sandbox) |
@pai/protocol | PaiMessage, ThreadState, AgentContract | Shared contracts |
@pai/code-mode | codeModeTool | Model-written scripts over allowed tools |