agentum-cloud-sdk

Типизированный async-клиент для Agentum Cloud — облака ваших документов с поиском и ответами на естественном языке (RAG). Загружаете файлы (PDF, DOCX, изображения, аудио), а затем ищете по ним и задаёте вопросы — ИИ отвечает с ссылками на источники.

Тонкая обёртка над httpx поверх REST /v1. Полные type hints, py.typed.

Установка

pip install agentum-cloud-sdk

Обновление до свежей версии: pip install -U agentum-cloud-sdk.

Требуется Python 3.13+.

Токен

1. Войдите в приложение app.agentums.ru (через Яндекс).
2. Настройки → API-токены → Создать — скопируйте токен ak_… (показывается один раз).

Токен привязан к вашему аккаунту и подписке. Держите его в секрете (как пароль); если скомпрометирован — отзовите в настройках и создайте новый.

Быстрый старт

import asyncio
from agentum_cloud import AgentumClient


async def main() -> None:
    async with AgentumClient(
        base_url="https://api.cloud.agentums.ru",
        api_key="ak_ваш_токен",
    ) as cloud:
        # Загрузить документ
        with open("contract.pdf", "rb") as f:
            obj = await cloud.upload("contract.pdf", f.read())

        # Дождаться, пока документ проиндексируется
        await cloud.wait_until_ready(obj.id)

        # Спросить — ответ с цитатами из ваших файлов
        answer = await cloud.ask("Какой срок действия договора?")
        print(answer.answer)
        if answer.primary:  # закреплённый главный файл под запрос («найди X» → вот он)
            print(f"  главный файл: {answer.primary.filename}")
        for c in answer.citations:
            print(f"  источник: {c.filename}")

        # Продолжить разговор: вернув session_id, получаем ответ с оглядкой на сказанное.
        # Без него «а подробнее?» ушло бы на сервер отдельным диалогом и отвечалось с нуля.
        more = await cloud.ask("а подробнее?", session_id=answer.session_id)
        print(more.answer)


asyncio.run(main())

Агентный режим (стрим)

agent_chat возвращает поток событий: агент сам решает, какими инструментами воспользоваться (поиск, конвертация, перевод, сборка PDF), и по пути шлёт токены ответа.

from contextlib import aclosing

from agentum_cloud import AgentumClient


async def main() -> None:
    async with AgentumClient(base_url="https://api.cloud.agentums.ru", api_key="ak_…") as cloud:
        # aclosing обязателен: только он закроет HTTP-ответ, если выйти из цикла через break
        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}]")
                elif ev.type == "paused":
                    # Опасное действие ждёт подтверждения — стрим на этом закончился
                    await confirm(cloud, ev)
                    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)

session_id из start/done продолжает диалог: agent_chat(..., session_id=sid). История доступна через list_chats() / get_chat(id); у агентных сессий kind == "agent", и их id можно передать обратно в agent_chat как session_id.

Что умеет

Клиент покрывает продуктовый контракт /v1 целиком. Ниже — по разделам; полное описание каждого метода лежит в его докстроке (help(cloud.имя_метода)).

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

Имена. Облако предлагает имя и папку, а решает пользователь: accept_folder, apply_ai_name, restore_name, lock_name.

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

Преобразования. convert_targets → convert · pdf_op (15 операций) · image_op · assemble_pdf · zip_objects · reorganize. Все асинхронные: возвращают task_id, готовность — соответствующий *_status, все они дают один JobStatus.

Осмысление. summarize · suggested_questions · protocol_questions → build_protocol (протокол встречи отдельным файлом) · диаризация: diarize, get_diarization, get_transcript, rename_speakers (он же энроллмент голоса), list_voice_profiles.

Поиск и ответы. search (вектор + полнотекст + имя с расширением) · ask (session_id продолжает разговор, object_ids сужает до конкретных файлов) · chat (без агента и инструментов) · extract_attachment (текст файла без сохранения) · classify_intent · command · rewrite · transcribe · generate_document.

Агент. agent_chat / agent_continue (стрим, см. выше) · agent_status · agent_task · память: list_agent_memory, forget_agent_memory, clear_agent_memory · роли: list_agent_profiles, activate_agent_profile, create_agent_profile.

Организация. Папки (list_collections, create_collection, update_collection, move_object, set_primary_object) · темы (list_themes, create_theme) · публичные ссылки (create_share, list_shares, revoke_share и чтение по токену: get_shared, list_shared_objects, get_shared_raw, upload_to_share) · скрытая зона (unlock_hidden → hidden_token= в списках и поиске).

Дела. Поручения (list_tasks, update_task) · уведомления (list_notifications, mark_notifications_read) · календарь (list_events, create_event, agenda, create_calendar_feed, import_ics).

Аккаунт и расход. get_usage / get_usage_history / get_usage_breakdown / get_quota · get_settings / update_settings · list_models · get_referral · свои LLM и хранилище (save_llm_integration, save_s3_integration, test_integration, migrate_storage) · свои Telegram-боты (list_bots, create_bot, list_bot_chats, list_bot_subscribers) · health / health_deep.

Все методы — корутины, кроме agent_chat/agent_continue: они возвращают асинхронный генератор, так что await не нужен — сразу async for (внутри aclosing). Клиент — async-context-manager (async with).

Заметки

• Данные изолированы по аккаунту: токен видит только файлы вашего аккаунта. Файлы, загруженные через Telegram-бота, доступны здесь же после привязки бота к аккаунту.
• Базовый URL прода — https://api.cloud.agentums.ru.
• Загрузка асинхронна. upload отвечает status="pending" до обработки: искать по содержимому сразу после загрузки бесполезно, дождитесь wait_until_ready.
• Список по умолчанию прячет четыре класса файлов — удалённые, вложения чата, заметки и скрытые. «Файл загрузился, но его нет» почти всегда объясняется этим: посмотрите list_objects(trashed=True).
• Ретраи осторожные, и это осознанно. 504 не повторяется (это дедлайн сервера — повтор лишь сожжёт токены), неидемпотентный POST не перезапускается по таймауту ответа, агентный стрим идёт мимо ретраев вовсе. Автоматически повторяется только запрос, который заведомо не дошёл до сервера.
• Вне SDK намеренно остались браузерные потоки входа, вебхуки чужих систем и управление аккаунтом с биллингом — они живут на сессии приложения, а не на ak_-токене.

Лицензия

MIT — см. LICENSE.