Source: https://docs.cumuluslabs.io/
Content version: 4fbba15f

# Build with Cumulus

Connect a voice agent to your application: define its conversation, give it tools that use your business systems, publish a version and start a call. Cumulus runs the conversation. Your application supplies the business logic and decides which changes it permits.

For example, a service agent can ask what needs repair, look up appointments through your scheduling API and request a booking after the caller confirms. Your backend makes the reservation; Cumulus records the conversation, tool results and call outcome.

## Start with the customer SDK {#choose-path}

[Build a voice agent in your application](/docs/sdk-tutorial) takes you from an installed SDK to a complete service-desk example. Define the agent and a tool, implement the tool in your backend, validate locally, publish and connect a dedicated test number. The example includes source code and tests.

Choose the [Python SDK](/docs/sdk-python) for typed HTTP API access, or **`@cumulus/sdk` 0.3.4** for TypeScript and JavaScript, which also includes agent-authoring and server helpers. [Compare and install the SDKs](/docs/sdks), then follow the guide for your language. Your tool server can use your existing language and framework; it communicates with Cumulus over HTTP.

| What you need | Where to go |
| --- | --- |
| A complete first integration | [Customer SDK tutorial](/docs/sdk-tutorial) |
| Exact SDK functions, options and types | [Customer SDK reference](/docs/sdk-reference) |
| HTTP endpoints, request bodies and responses | [Customer HTTP API reference](/docs/api-reference) |
| Authentication, requests and retries | [Using the API](/docs/api) |
| A connected coding assistant | [Cumulus MCP](/docs/mcp) |

## What belongs in your application {#who-uses-it}

Your application owns the agent source, tool implementations, business records and authorization for actions such as booking or updating an account. A tool definition describes what the agent can request. Its implementation authenticates that request, checks your business rules and performs the operation.

Cumulus stores and runs the published conversation. Publishing sends configuration, not the implementation of your tool. You can add the tool routes to your existing backend; you do not need a separate service for every tool.

The SDK's [customer-server handlers](/docs/sdk-reference/server) help receive tool requests, resolve initial call context and process signed events. If you use another language, implement the same [HTTP contracts](/docs/sdk-http-contracts) in your framework.

## Build, publish and run {#lifecycle}

An **agent** contains the conversation you are building. Its **draft** is editable. A **publication** is an immutable version of that conversation. A **run** is one execution of a publication, such as a call or a cloud task.

1. **Define and connect.** Describe the conversation and tool contracts. Bind tool URLs, secret references and phone resources for your environment.
2. **Review the change.** Validate the definition and preview remote changes before updating the draft. Revision checks protect changes made by a teammate.
3. **Publish.** Validate the draft and publish the intended revision. Keep the returned agent, version and receipt.
4. **Connect a number and call.** Assign an imported number explicitly, then start a call against the intended publication. Publishing alone does not change a number's assignment.
5. **Read the outcome.** Follow the run and inspect its transcript, tool results and end reason. Retrieve recording and analysis separately when they are ready.

The [tutorial](/docs/sdk-tutorial) walks through this sequence. [Work with Studio and recover changes](/docs/sdk-lifecycle) explains later edits, conflicts and interrupted operations. Studio is another way to inspect and edit the same agents.

## Connect useful behavior {#use-cases}

- **Business tools:** [Define a tool](/docs/sdk-definitions) and [implement its HTTP handler](/docs/sdk-server), including success and failure responses.
- **Environment setup:** [Bind endpoints, credentials and phone resources](/docs/sdk-bindings) without putting secret values into the definition.
- **Calls and results:** [Prepare a call, wait for its state and read outputs](/docs/sdk-runtime). A completed call does not by itself establish that a booking succeeded.
- **Private keypad input:** [Verify or tokenize private input](/docs/sdk-private). Tokenization produces a token; your payment system performs any charge.
- **Knowledge and follow-up:** [Connect knowledge](/docs/knowledge) and [process after-call work](/docs/after-call-operations) when your application needs them.

## Get access {#start-building}

You need a Cumulus workspace, its API URL and an API key with permission for your operations. Package access installs the SDK; the workspace key authorizes requests. Keep both credentials on your server.

Use a development environment and synthetic records while building. A phone integration also needs an imported number and permission to dial. Your Cumulus contact provides workspace and package access; [book a demo](https://calendar.app.google/McaFEvZ5eyagACi56) if you are getting started.