@cxpa/sdk

Official SDK for the CXP Agent Platform.

Two consumer roles, two subpath imports:

| Subpath | For | What it gives you | |---|---|---| | @cxpa/sdk/agent | Agent runtime code (Trigger.dev tasks, n8n workflows, standalone Node) | createAgentClient, triggerRun, registerRun, ingestRun | | @cxpa/sdk/zone | Next.js zone apps embedded in a platform agent page | createZoneClient, createZoneMiddleware, getSession | | @cxpa/sdk/types | Shared types (errors, payload shapes) | Run, RunStatus, CallbackPayload, ResolvedCredential, ApiError |

Install

npm install @cxpa/sdk

next is an optional peer dependency — install it only if you use @cxpa/sdk/zone.

Agent runtime — quickstart

import { createAgentClient } from '@cxpa/sdk/agent'

const cxpa = createAgentClient({
  baseUrl: process.env.CXPA_API_URL!,
  apiKey:  process.env.CXPA_API_KEY!,
  runId:   payload.runId,
  credentialsToken: payload.credentialsToken,
})

await cxpa.started()
const cred = await cxpa.resolveCredential(payload.connectionIds.openai.connectionId)
await cxpa.complete({ output: { result: 'done' } })

Ingest-key operations

For agent-scoped operations using ingest_api_key (not agent_api_key):

import { triggerRun, registerRun, ingestRun } from '@cxpa/sdk/agent'

// Start a platform-managed run
await triggerRun({ baseUrl, ingestApiKey, agentId, input: {...} })

// Register an externally-triggered run, get a credentialsToken
const { runId, credentialsToken } = await registerRun({
  baseUrl, ingestApiKey, agentId, externalRunId: '...', input: {...}
})

// Monitoring-only status update
await ingestRun({
  baseUrl, ingestApiKey, agentId,
  externalRunId: '...', status: 'completed',
  startedAt: '...', completedAt: '...', durationMs: 1234,
})

Zone app — quickstart

// middleware.ts
import { createZoneMiddleware } from '@cxpa/sdk/zone'

export const middleware = createZoneMiddleware({
  secret: process.env.ZONE_JWT_SECRET!,
  audience: process.env.AUDIENCE_ID!,
})

export const config = {
  matcher: ['/:orgSlug/:agentSlug/app/:path*', '/:orgSlug/:agentSlug/app'],
}

// app/page.tsx
import { getSession, createZoneClient } from '@cxpa/sdk/zone'

export default async function Page() {
  const session = await getSession()
  const cxpa = createZoneClient({
    baseUrl: process.env.PLATFORM_API_BASE_URL!,
    token:   session.token,
    agentId: session.claims.agentId,
  })

  const { runId } = await cxpa.runs.create({ payload: { url: 'https://example.com' } })
  const run = await cxpa.runs.get(runId)
  return <pre>{JSON.stringify(run, null, 2)}</pre>
}

Errors

All non-2xx responses throw ApiError:

import { ApiError } from '@cxpa/sdk'

try {
  await cxpa.complete({ output: {} })
} catch (err) {
  if (err instanceof ApiError && err.status === 401) {
    // re-auth
  }
  throw err
}

License

MIT