Python SDK - Cominty Docs

The Cominty Python SDK wraps the chat API: start a conversation with an agent, stream its progress, continue the thread, manage threads, cancel or export a message, upload and download files, and store memory files an agent can read back later. Since 1.2.0, it also configures what an admin configures in the console: list MCP integrations, create agents, upload skills, and index local files as a source. Chat and threads are scoped to a single end user (user_id) that you set once on the client. Memory files are scoped to a namespace you choose, shared by the API key. See Memory namespaces. Building in JavaScript or TypeScript? The JavaScript SDK tracks the same API.

Quickstart

Task-by-task examples, each with runnable code on GitHub.

Guides

Concepts behind capabilities, memory namespaces, and tool-round caps.

Use cases

Recipes that show what a capability changes.

Reference

Every resource, model, event, and exception.

GitHub

Source, issues, and the full examples/ directory.

API reference

The HTTP endpoints the SDK calls, with a live playground.

Package cominty-sdk (

) · import cominty_sdk · Python 3.9+ · style async-only (httpx), fully typed.

Install

pip install cominty-sdk        # or: uv add cominty-sdk

The resources for MCP, agents, skills, sources, and documents need version 1.2.0 or later. To require it, use pip install "cominty-sdk>=1.2.0".

Authenticate

You need two credentials, both from platform.cominty.ai:

Get your API key

Open the API keys page and create a key. A key created now starts with sk-cmt-. Copy it when you create it: it is shown once. Use the string as is. Do not add a second sk-cmt- prefix. A key created before the prefix existed has no sk-cmt- and still works.

Get your user id

Open your avatar → Profile. It looks like user_31HPTBuBvX20xlQNAbvxjOxPbKB.

Export both

export COMINTY_API_KEY="sk-cmt-..."
export COMINTY_USER_ID="user_..."

With both set, AsyncCominty() picks them up automatically. No arguments needed.

Pick an agent_id from platform.cominty.ai/agents (for example __cominty_agents::agent.chat). See Built-in agents for what Chat, Hive, and Planner can do.

Your first call

import asyncio
from cominty_sdk import AsyncCominty

async def main():
    async with AsyncCominty() as client:          # reads COMINTY_API_KEY + COMINTY_USER_ID
        run = await client.chat.start(
            agent_id="__cominty_agents::agent.chat",
            message="What is Cominty?",
        )
        print(await run.text())

asyncio.run(main())

Core concepts

Client: one user per client

AsyncCominty is bound to a single user_id, validated at construction. Chat and thread requests send it. Memory requests do not. Resource methods never take user_id. Use it as an async context manager (async with) or call await client.close() when done. See Client for all settings.

Resources: chat, threads, memory, and configuration

client.chat starts and continues conversations, streams progress, cancels or exports a message, and uploads/downloads files. client.threads lists, fetches, updates, and archives threads. client.memory creates, lists, reads, updates, and deletes memory files in a namespace you choose. See Memory namespaces and Resources.Five more resources configure the organization (SDK 1.2.0): client.mcp lists MCP integrations, client.agents manages custom agents and their models, client.skills manages skills, client.sources turns local files into an indexed source, and client.documents resolves a cited document. See Custom agents, Skills, and Sources.

The API key: an admin of its organization

An API key acts as an admin of its own organization. What it creates is owned by the user who created the key. It never sees another member’s private agents, skills, or drives, and a read by id raises NotFoundError. See What an API key can do.

Runs: the assistant's in-progress reply

chat.start and chat.send return a run: the assistant’s reply as it is being produced. Iterate it for live progress events, or just await run.text() for the final answer. A run’s stream is single-use. See The run handle.

Capabilities: what the agent can use

Web search, document search, MCP connections, skills, media generation, and memory are capabilities. They follow the agent’s setup by default. Change them for a whole thread with thread_capabilities (chat.start only), or for one message with message_scope. See Capabilities and the reference.

SDK 1.0.0 removes disabled_tools, source_ids, document_ids, and memory_namespace. See Migrate from SDK 0.5.0.

Configuration

Setting	Argument	Env var	Default
API key	`api_token`	`COMINTY_API_KEY`	required
End user	`user_id`	`COMINTY_USER_ID`	required
Base URL	`base_url`	`COMINTY_BASE_URL`	`https://ds.cominty.com`
Timeout	`timeout`	-	`60` (seconds)

Resolution order is explicit argument → environment variable → default. The SDK does not auto-load .env files. api_token and COMINTY_API_KEY hold the key string exactly as the platform gave it to you, sk-cmt-... included. A wrong or archived key comes back as a 403 and raises PermissionError. For the detail text of each case, see Authentication errors.

Quickstart

Guides

Use cases

Reference

GitHub

API reference

​Install

​Authenticate

​Your first call

​Core concepts

​Configuration

Install

Authenticate

Your first call

Core concepts

Configuration