Python SDK

pip install agentum-cloud-sdk

Тонкая обёртка над httpx поверх REST /v1: полные type hints, py.typed, все методы — корутины. Клиент открывается как async-контекст:

async with AgentumClient(base_url="https://api.cloud.agentums.ru", api_key="ak_…") as cloud:
    ...

Покрытие контракта проверяется тестом на нашей стороне: маршрут, у которого нет метода в клиенте, роняет сборку. Отставание SDK от API — не то, что вы узнаёте первым.

Что умеет

Файлы. upload · add_link (страница или видео по URL) · upload_archive · wait_until_ready · list_objects / list_objects_page · get_object · rename_object · reprocess_object · корзина: delete_object → restore_object / delete_object_permanent / empty_trash.

Содержимое. get_content (временная ссылка) · get_raw / get_thumbnail / get_page_image (байты через API — у них наш CORS) · get_text_content · save_content (с base_version — защита от гонки редакторов) · list_revisions / restore_revision · черновики · get_summary · translate.

Преобразования. convert_targets → convert · pdf_op (15 операций) · image_op · assemble_pdf · zip_objects · reorganize.

Осмысление. summarize · suggested_questions · protocol_questions → build_protocol · диаризация: diarize, get_diarization, get_transcript, rename_speakers.

Поиск и ответы. search · ask · chat · extract_attachment · classify_intent · command · rewrite · transcribe · generate_document.

Агент. agent_chat / agent_continue · agent_status · agent_task · память · роли.

Организация. Папки · темы · публичные ссылки · скрытая зона.

Дела. Поручения · уведомления · календарь.

Аккаунт. get_usage / get_quota · get_settings · list_models · свои LLM и хранилище · свои Telegram-боты · health.

Описание каждого метода — в его докстроке: help(cloud.ask).

Агент

agent_chat возвращает асинхронный генератор, а не корутину: await не нужен, сразу async for — и обязательно внутри aclosing.

from contextlib import aclosing

async with aclosing(cloud.agent_chat("собери все счета за июнь в один PDF")) as stream:
    async for ev in stream:
        if ev.type == "token":
            print(ev.delta, end="", flush=True)
        elif ev.type == "tool_start":
            print(f"\n[{ev.name}]")

aclosing не украшение: только он закроет HTTP-ответ, если выйти из цикла через break.

Два правила потока

paused — конец потока

События done после него не будет. Агент упёрся в опасное действие (перезапись файла, необратимая операция) и ждёт решения. Продолжают через agent_continue, передавая решения по всем инструментам из события одним вызовом: не упомянутый инструмент молча не выполнится.

error — не конец потока

За кадром с ошибкой могут прийти ещё токены и done. Выйти из цикла по error — потерять хвост ответа.

async def confirm(cloud, ev) -> None:
    decisions = [(t.tool_call_id, input(f"{t.name} {t.args}? [y/n] ") == "y") for t in ev.tools]
    async with aclosing(
        cloud.agent_continue(run_id=ev.run_id, session_id=ev.session_id, decisions=decisions)
    ) as stream:
        async for ev in stream:
            if ev.type == "token":
                print(ev.delta, end="", flush=True)

Чего в SDK нет намеренно

Браузерные потоки входа, вебхуки чужих систем и управление аккаунтом с биллингом. Они живут на сессии приложения, а не на ak_-токене, и клиентскому коду недоступны в принципе.