> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cominty.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Async, fully-typed Python client for the Cominty chat API

The Cominty Python SDK wraps the chat API: start a conversation with an agent,
stream its progress, continue the thread, and manage threads. Everything is
scoped to a single end user (`user_id`) that you set once on the client.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/sdk/quickstart">
    Task-by-task examples, each with runnable code on GitHub.
  </Card>

  <Card title="Reference" icon="book" href="/sdk/reference">
    Every resource, model, event, and exception.
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/cominty/python-sdk">
    Source, issues, and the full `examples/` directory.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    The HTTP endpoints the SDK calls, with a live playground.
  </Card>
</CardGroup>

<Info>
  **Package** `cominty-sdk` (PyPI) · **import** `cominty_sdk` · **version** 0.3.0 ·
  **Python** 3.9+ · **style** async-only ([`httpx`](https://www.python-httpx.org/)),
  fully typed.
</Info>

## Install

```bash theme={null}
pip install cominty-sdk        # or: uv add cominty-sdk
```

## Authenticate

You need two credentials, both from [platform.cominty.ai](https://platform.cominty.ai):

<Steps>
  <Step title="Get your API key">
    Open the **API keys** page and create a key.
  </Step>

  <Step title="Get your user id">
    Open your avatar → **Profile**. It looks like
    `user_31HPTBuBvX20xlQNAbvxjOxPbKB`.
  </Step>

  <Step title="Export both">
    ```bash theme={null}
    export COMINTY_API_KEY="<your API key>"
    export COMINTY_USER_ID="user_..."
    ```

    With both set, `AsyncCominty()` picks them up automatically — no arguments
    needed.
  </Step>
</Steps>

Pick an `agent_id` from [platform.cominty.ai/agents](https://platform.cominty.ai/agents)
(for example `__cominty_agents::agent.chat`).

## Your first call

```python theme={null}
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

<AccordionGroup>
  <Accordion title="Client — one user per client" icon="user">
    `AsyncCominty` is bound to a single `user_id`, validated at construction and
    applied to **every** request. Resource methods never take `user_id`. Use it
    as an async context manager (`async with`) or call `await client.close()`
    when done. See [Client](/sdk/reference#client) for all settings.
  </Accordion>

  <Accordion title="Resources — chat and threads" icon="layers">
    `client.chat` starts and continues conversations and streams progress.
    `client.threads` lists, fetches, updates, and archives threads — all scoped
    to the client's user. See [Resources](/sdk/reference#resources).
  </Accordion>

  <Accordion title="Runs — the assistant's in-progress reply" icon="activity">
    `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](/sdk/reference#the-run-handle).
  </Accordion>

  <Accordion title="Tools — on by default" icon="wrench">
    Web search, company-document retrieval, and any MCP servers connected to the
    agent are enabled automatically. You only ever turn things **off**, with
    `disabled_tools`. See [`disabled_tools`](/sdk/reference#disabled-tools).
  </Accordion>
</AccordionGroup>

## 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.