CumulusDocs
Open Studio
On this page

Customer SDKs

Use the Cumulus SDK to define an agent, connect your backend tools, manage publication changes, start calls and retrieve results. The SDK publishes conversation configuration to Cumulus; your business code stays in your application.

Choose your language

LanguagePackageStart here
Python 3.10+cumulus-sdk 0.2.11 — typed customer HTTP API access.Python SDK guide
TypeScript / JavaScript, Node 22+@cumulus/sdk 0.3.4 — HTTP client, agent authoring, server handlers and call helpers; ESM and CommonJS.Build a voice agent

Both clients connect to the customer API. The TypeScript package also supplies the definition builders, authoring CLI and HTTP-handler adapters shown in the module references. A Python application can use the Python client and implement the same customer callback contracts in its framework.

Install TypeScript / JavaScript

Obtain the authorized SDK archive from your Cumulus contact and install it in your application:

sh
npm install /absolute/path/to/cumulus-sdk-0.3.4.tgz

Keep the lockfile so your teammates install the same artifact. Package credentials install the library; your workspace API key authorizes runtime requests.

Build a voice agent in your application provides a complete service-desk integration. Its source download includes local tests and uses Node 22.13 or newer for its SQLite repository.

Connect TypeScript to your workspace

Set the API origin, without /api/v1, and inject CUMULUS_API_KEY through your server's secret configuration:

sh
export CUMULUS_API_URL=https://api.cumuluslabs.io

If Cumulus provides a separate development API URL, use that origin instead.

typescript
import { Cumulus } from '@cumulus/sdk';

const baseUrl = process.env.CUMULUS_API_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error('Set the API URL and key');

const client = new Cumulus({ baseUrl, apiKey });
const page = await client.agents.list({ query: { limit: 20 } });
for (const agent of page.agents) console.log(agent.ref.id, agent.name);

Confirm the selected environment before changing an agent or placing a call. Keep this client and its API key on your server. A browser application should call your authenticated backend.

Use the Python SDK

Install cumulus-sdk==0.2.11 from the Cumulus package registry using the package credentials supplied for your workspace. The Python SDK guide gives the installation commands, a complete connection example and typed request/result handling.

Import Cumulus and PlatformError from cumulus. The Python client accepts path, query, body and idempotency_key arguments and returns Pydantic models. Use the customer HTTP API reference to choose an operation and inspect its fields.

TypeScript modules

ImportWhat it providesReference
@cumulus/sdkTyped HTTP requests, responses, errors and event streaming.Client
@cumulus/sdk/agentAgent and tool definitions, bindings, previews, draft updates and publication.Definitions and authoring
@cumulus/sdk/serverHTTP handlers for customer tools, inbound context, events and private integrations.Customer-server handlers
@cumulus/sdk/runtimePrepared calls, bounded waits, pagination, event watching and number assignment.Calls and results

Start with the tutorial to understand how these pieces work together. Use the SDK reference for exact signatures, options, return values and callback contracts. The HTTP API reference documents the underlying endpoints separately.

Use your existing backend

Tool implementations can run in your existing language and framework. Cumulus sends an authenticated HTTP request; your application validates it, performs the authorized operation and returns a response. The TypeScript server helpers are optional adapters for those contracts.

For direct HTTP integrations, Using the API covers authentication, request bodies, events and retries, with cURL and client examples. For Python API access, use the Python SDK guide. To receive callbacks in your backend, follow the customer HTTP contracts.

Make changes safely

Preview changes, apply against the expected draft revision and keep the resulting receipt. If a command's outcome is unknown, reuse its original request and idempotency key while reconciling it. Sending a new key can repeat the operation.

Publication and recovery explains the full workflow. SDK errors explains refusals and interrupted requests. If you used the earlier TypeScript transport client, read the migration guide.

Content version d9fa3d07Customer SDKMarkdown source
Choose and install an SDK · Cumulus developer docs