Quickstart

import asyncio
from cominty_sdk import AsyncCominty, events

AGENT_ID = "__cominty_agents::agent.chat"

async def main():
    async with AsyncCominty() as client:          # COMINTY_API_KEY + COMINTY_USER_ID
        ...  # the snippets below go here

asyncio.run(main())

uv sync --all-extras --dev    # examples render with `rich`
python examples/01_stream_events.py

run = await client.chat.start(agent_id=AGENT_ID, message="Research X and summarize.")
async for event in run:
    if isinstance(event, events.ToolCall):
        print("tool", event.data.name, event.status)
    elif isinstance(event, events.LlmStep):
        print("llm ", event.data.description)
    elif isinstance(event, events.Result):
        print("cost", event.data.cost.total)
print(await run.text())

run = await client.chat.start(agent_id=AGENT_ID, message="Give me one fun fact.")
print(await run.text())            # blocks until done
reply = await run.result()         # full Message (status, files, ...)

first = await client.chat.start(agent_id=AGENT_ID, message="Pick a language.")
await first.text()
second = await client.chat.send(first.thread.id, agent_id=AGENT_ID,
                                message="Now show hello-world in it.")
print(await second.text())

run = await client.chat.start(agent_id=AGENT_ID, message="Book me a room.")
await run.text()
for q in await run.questions():
    print(q.prompt, q.options)
reply = await client.chat.send(run.thread.id, agent_id=AGENT_ID, message="Tomorrow 10am")
print(await reply.text())

for t in await client.threads.list(limit=20):
    print(t.created_at, t.name, t.id)
await client.threads.list(terms=["invoice"])   # free-text search
await client.threads.list(limit=10, page=1)     # paginate (zero-based)

thread = await client.threads.get(thread_id)                          # full history
await client.threads.update(thread_id, name="Renamed", starred=True)  # partial → ThreadSummary
await client.threads.archive(thread_id)                               # soft-delete

run = await client.chat.start(
    agent_id=CUSTOM_AGENT_ID,
    message=TECHNICAL_INPUT,
    disabled_tools=["web", "company_documents", "mcp:*"],  # pure transformation
)
print(await run.text())   # bullet-point French briefing for a C-level reader

run = await client.chat.start(
    agent_id=CUSTOM_AGENT_ID,
    message="Using Linear, list the current-sprint tasks and summarize for leadership.",
    disabled_tools=["web", "company_documents"],  # keep MCP (Linear) on
)
print(await run.text())

from cominty_sdk import RateLimitError, APIError

try:
    run = await client.chat.start(agent_id=AGENT_ID, message="hi")
    print(await run.text())
except RateLimitError as e:
    print(e)                       # clear, scope-aware message
    print(e.scope, e.retry_after, e.reset_at)
except APIError as e:
    print(e.status_code, e.detail)