PAIcreatePaiExpressReceiver()
Express adapter for a createPai app.
createPaiExpressReceiver is the HTTP door for a createPai() app. Each registered agent is served under its registry id (/api/pai/main/...).
import express from "express";
import { createPaiExpressReceiver } from "@pai/express";
app.use(
"/api/pai",
createPaiExpressReceiver({
pai,
resolveIdentity: ({ request }) => ({
identity: {
userId: request.headers.get("x-user-id") ?? "dev-user",
workspaceId: request.headers.get("x-workspace-id") ?? "dev",
},
}),
}),
);resolveIdentity runs on every request. Never take workspaceId from the JSON body. See Identity.
Import
import { createPaiExpressReceiver } from "@pai/express";Signature
function createPaiExpressReceiver<TPai, THostContext = undefined>(
input: CreatePaiExpressReceiverOptions<TPai, THostContext>,
): PaiExpressReceiver;Parameters
input: CreatePaiExpressReceiverOptions
pai: Pai
The app from createPai.
resolveIdentity: (input) => { identity } | Record<agentId, resolver>
Trusted identity for the request. One function, or one per agent id.
access?: Partial<Record<agentId, "full" | "read" | "none">>
Hide specialists from the browser. Default "full".
getContext?: (request, response) => THostContext | Promise<THostContext>
Trusted host context passed to resolveIdentity. Required when
THostContext is not undefined. JSON routes validate the body before
resolving context; file uploads resolve identity before parsing multipart.
requestLimits?: HttpAgentRequestLimits
Byte limits for JSON, multipart, file and metadata bodies. See HTTP request limits.
deriveFileUrlFallback?: boolean
Derive a URL for the file read endpoint when the file provider cannot
mint one. Defaults to false; use with same-origin or cookie-authenticated
file requests.
keepAliveMs?: number
Idle SSE keep-alive interval. 0 disables keep-alives.
httpTelemetry?: HttpAgentTelemetryOptions
Enable HTTP operation spans with true, or select operations with
{ enabled, operations }. Defaults to disabled. Incoming trace context
is propagated independently of HTTP span creation.
mapHttpError?: HttpAgentErrorMapper
Safe client details for recognized failures.
onHttpError?: false | HttpAgentErrorHandler
Trusted exception plus matching safe error. Omit for PAI's default reporter.
logger?: PaiLogger | false
Defaults to the createPai logger. See Errors.
logLevel?: "debug" | "info" | "warn" | "error"
Each registered agent is mounted at /:agentId. Use access to hide agents or expose an agent as read-only:
createPaiExpressReceiver({
pai,
resolveIdentity,
access: {
assistant: "full",
reviewer: "read",
},
});Returns
A PaiExpressReceiver.
An Express Router. Call close() on shutdown to close the createPai app
once. Runtime lifecycle belongs to that app.