@cxpa/sdk is the official TypeScript SDK for the CXP Agent Platform. It wraps the public HTTP API in typed helpers and ships zone-app primitives for Next.js.
Install
npm install @cxpa/sdk
Published on the public npm registry — no registry configuration or auth is needed despite the @cxpa scope.
Requires Node 18 or later. A zone app additionally needs whatever its Next.js version requires, which in practice means Node 20+.
The SDK has a single runtime dependency (jose, for JWT verification) and declares next as an optional peer dependency — install it only if you use @cxpa/sdk/zone.
Pin a range rather than floating: "@cxpa/sdk": "^0.8.0".
Subpath exports
| Subpath | Purpose |
|---|---|
@cxpa/sdk/agent | Trigger / register / ingest runs, plus the runtime-side AgentClient for callbacks and credential resolution. |
@cxpa/sdk/zone | Next.js middleware, session helpers, and a ZoneClient for zone apps. |
When to use which
- Triggering or ingesting runs from your backend →
@cxpa/sdk/agent. - Building the runtime task →
@cxpa/sdk/agent(createAgentClient). - Building a zone app →
@cxpa/sdk/zone.
Versioning
@cxpa/sdk follows semver, and is currently 0.x — while the major version is zero, breaking changes ship in a minor bump, with a migration note in CHANGELOG.md on npm. Pin at least the minor (^0.8.0) and read the changelog before moving between minors.
Errors
Both subpaths throw the same ApiError on a non-2xx response, carrying status and the platform's message. It is exported from @cxpa/sdk, @cxpa/sdk/agent and @cxpa/sdk/zone. See Errors for what each status means per endpoint.