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
| Language | Package | Start 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:
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:
export CUMULUS_API_URL=https://api.cumuluslabs.io
If Cumulus provides a separate development API URL, use that origin instead.
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
| Import | What it provides | Reference |
|---|---|---|
@cumulus/sdk | Typed HTTP requests, responses, errors and event streaming. | Client |
@cumulus/sdk/agent | Agent and tool definitions, bindings, previews, draft updates and publication. | Definitions and authoring |
@cumulus/sdk/server | HTTP handlers for customer tools, inbound context, events and private integrations. | Customer-server handlers |
@cumulus/sdk/runtime | Prepared 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.