@cxpa/sdk/agent

Exports

Symbol	Kind	Purpose
`triggerRun`	function	Start a platform-managed run (async — returns `runId` immediately).
`triggerRunAndWait`	function	Start a run and block until it terminates or a wait window elapses; returns the agent output inline.
`triggerRunAndDownload`	function	Start a run and stream the runtime's binary response back as a `ReadableStream` — for agents whose output is a file.
`registerRun`	function	Register an externally-triggered run and receive a credentials token.
`ingestRun`	function	Report status for a standalone agent.
`createAgentClient`	factory	Build a runtime client bound to a single `(runId, agentApiKey)`.

`triggerRun(options)`

Wraps POST /api/agents/{agentId}/runs/trigger.

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

const { runId, status } = await triggerRun({
  baseUrl: process.env.CXPA_API_URL!,
  ingestApiKey: process.env.CXPA_INGEST_KEY!,
  agentId: 42,
  input: { url: 'https://example.com' },
})

`triggerRunAndWait(options)`

Wraps POST /api/agents/{agentId}/runs/trigger-and-wait. Synchronous variant of triggerRun — the call blocks until the run reaches a terminal state or the server-side wait window elapses, then returns either the full Run row (with output_data) or a { timedOut: true } placeholder.

Use it for agents whose value is the output payload itself: PDF reports, generated documents, AI-rendered responses.

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

const result = await triggerRunAndWait({
  baseUrl: process.env.CXPA_API_URL!,
  ingestApiKey: process.env.CXPA_INGEST_KEY!,
  agentId: 42,
  input: { topic: 'Q3 financial summary' },
  timeoutMs: 120_000, // server further caps at agent's max-run-duration
})

if (result.timedOut) {
  // Wait window elapsed; the run is still in flight. Fall back to polling.
  console.log('still running:', result.runId)
} else if (result.status === 'completed') {
  // result.output_data carries the agent payload
} else {
  // 'failed' | 'cancelled'
  throw new Error(`Run ${result.status}: ${result.error}`)
}

When to choose this over `triggerRun`

Use `triggerRun`	Use `triggerRunAndWait`
Caller doesn't need output inline	Caller hands the output straight to the end user
Run may take longer than ~5 minutes	Run completes in seconds or low minutes
You'll poll or wait for a callback yourself	You want one HTTP request that returns the result

`triggerRunAndDownload(options)`

Wraps POST /api/agents/{agentId}/runs/trigger-and-download. For agents whose output is a generated file (PDF report, spreadsheet export, rendered image) rather than a JSON payload. The platform streams the runtime's response body straight through and never buffers it.

Only valid for platform-managed agents with output_kind = 'file_download' whose runtime supports streaming binary output. The platform records run metadata only (filename, mime type, byte count); the file bytes are not stored.

import { triggerRunAndDownload } from '@cxpa/sdk/agent'
import { writeFile } from 'node:fs/promises'
import { Readable } from 'node:stream'

const result = await triggerRunAndDownload({
  baseUrl: process.env.CXPA_API_URL!,
  ingestApiKey: process.env.CXPA_INGEST_KEY!,
  agentId: 42,
  input: { topic: 'Q3 financial summary' },
})

await writeFile(result.filename, Readable.fromWeb(result.body))
// `result.runId`, `result.contentType`, `result.contentLength` available too.

The returned body is a ReadableStream<Uint8Array> — pipe it once. In a server-side handler the stream is typically forwarded straight to the caller's own HTTP response so the user's browser saves the file without any intermediate buffering on your side.

When to choose this over `triggerRunAndWait`

Use `triggerRunAndWait`	Use `triggerRunAndDownload`
Output is a JSON payload	Output is a binary file (PDF, spreadsheet, image)
You want `output_data` inline in JSON	You want the bytes streamed to disk or to a browser

`registerRun(options)`

Wraps POST /api/agents/{agentId}/runs/register.

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

const { runId, credentialsToken, expiresInSeconds } = await registerRun({
  baseUrl: process.env.CXPA_API_URL!,
  ingestApiKey: process.env.CXPA_INGEST_KEY!,
  agentId: 42,
  externalRunId: 'run_abc123',
})

Pass credentialsToken to the runtime alongside the agent API key; the runtime uses both to resolve credentials.

`ingestRun(options)`

Wraps POST /api/agents/{agentId}/runs/ingest. For managed_by = 'standalone' agents only.

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

await ingestRun({
  baseUrl,
  ingestApiKey,
  agentId,
  externalRunId: 'exec_001',
  status: 'completed',
  output: { pages: 42 },
  outputs: 42,
})

`createAgentClient(options)`

Returns a client bound to one (runId, agentApiKey). Use it from inside a runtime task.

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

const cxpa = createAgentClient({
  baseUrl,
  apiKey: triggerPayload.agentApiKey,
  runId:  triggerPayload.runId,
  credentialsToken: triggerPayload.credentialsToken,
})

Methods

Method	HTTP under the hood
`started()`	`POST /callback { type: 'started' }`
`output({ output, outputs? })`	`POST /callback { type: 'output' }` (intermediate)
`complete({ output, outputs? })`	`POST /callback { type: 'output', complete: true }`
`fail({ message, name?, stack? })`	`POST /callback { type: 'output', failed: true, error }`
`waiting({ tokenId, description, output? })`	`POST /callback { type: 'waiting' }`
`resolveCredential(connectionId)`	`GET /api/credentials/{id}/resolve`

resolveCredential requires credentialsToken to have been passed at construction.

Exports

triggerRun(options)

triggerRunAndWait(options)

When to choose this over triggerRun

triggerRunAndDownload(options)

When to choose this over triggerRunAndWait

registerRun(options)

ingestRun(options)

createAgentClient(options)