Python SDK

The ChatBotKit Python SDK is the official async Python library for building conversational AI applications on ChatBotKit. It provides typed access to the platform API, streaming responses, generated request and response types, and optional agent helpers for tool-using workflows.

Key Features

• Async by Default: Built on httpx and designed for modern async Python applications
• Comprehensive API Coverage: Access bots, conversations, datasets, integrations, tasks, partners, usage, and platform resources
• Streaming Support: Iterate over JSONL stream events as they arrive
• Generated Types: Use chatbotkit.types for request, response, and stream item models
• Agent Helpers: Install the optional agent extra to run tool-using agents with Python handlers
• Production Ready: Supports custom base URLs, timeouts, headers, transports, and partner run-as options

Installation

Install the SDK from PyPI:

To use the optional agent helpers, install the agent extra:

You can also install directly from the source repository:

Requirements:

• Python 3.10 or higher
• A ChatBotKit API secret key

Quick Start

The simplest way to get started is with a stateless conversation completion. The SDK is async, so use it inside an event loop:

Passing None as the conversation ID uses the stateless completion endpoint. Pass an existing conversation ID when you want ChatBotKit to continue a stored conversation.

Client Architecture

Create a ChatBotKit client with your API key and access platform resources as attributes:

The client manages an underlying httpx.AsyncClient. Use async with ChatBotKit(...) as cbk when possible, or call await cbk.aclose() when you are done.

API Route Mapping

The Python SDK follows the same shape as the ChatBotKit API:

• API route: /api/v1/bot/list -> SDK method: cbk.bot.list()
• API route: /api/v1/bot/create -> SDK method: cbk.bot.create()
• API route: /api/v1/dataset/record/create -> SDK method: cbk.dataset.record.create()
• API route: /api/v1/conversation/complete -> SDK method: cbk.conversation.complete()

This makes it straightforward to move between the API reference, examples, and SDK calls.

Responses and Streaming

Every resource method returns an awaitable response. Await it to parse the JSON body into a typed object:

Call .stream() to iterate over stream items as they arrive:

Working with Bots

Bots are AI agents configured with backstory, model settings, datasets, skillsets, and integrations.

Conversations

Use conversations for chat interactions. You can run stateless completions or create persistent conversation records.

For one-off completions, pass None as the conversation ID:

Datasets

Datasets store knowledge that bots and agents can search.

Integrations

Integrations are available under cbk.integration and follow the same list, create, fetch, update, and delete patterns. Some integrations also expose operations such as setup, initiate, or sync.

Agent Helpers

Install chatbotkit[agent] to use the optional agent helpers. They let you define Python tools, validate tool inputs with Pydantic models, and stream agent execution events.

Configuration Options

Options can be passed as keyword arguments or with ClientOptions:

Error Handling

Failed requests raise APIError, which includes the API message, code, status, and URL.

Types

The chatbotkit.types module contains generated request, response, and stream item types. Each type provides from_dict and to_dict helpers, and resource methods accept either generated objects or plain dictionaries.

Resources

• PyPI Package: chatbotkit
• SDK Repository: https://github.com/chatbotkit/python-sdk
• Examples: Python SDK examples
• API Reference: ChatBotKit API