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+.
Токен
- Войдите в приложение cloud.agentums.ru (через Яндекс).
- Настройки → 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.
Что умеет
| Метод | Назначение |
|---|---|
upload(filename, data) |
загрузить документ/изображение/аудио |
wait_until_ready(object_id) |
дождаться окончания индексации |
list_objects(...) / get_object(id) |
список / детали файла (заголовок, summary, теги) |
get_summary(id) |
карточка содержания (метаданные обогащения) |
get_content(id) |
временная ссылка на оригинал (presigned URL) |
search(q) |
гибридный поиск (вектор + полнотекст + имя/расширение) по вашим файлам |
ask(query, session_id=...) |
ответ ИИ по вашим документам + цитаты и закреплённый файл (primary); session_id продолжает разговор |
translate(id, target_lang) |
перевести документ → новый объект |
transcribe(filename, data) |
расшифровка аудио в текст |
get_usage(days=...) |
расход (₽) и разбивка по статьям |
get_usage_history(days=...) |
дневной ряд расхода (₽ + токены + вызовы) для графика |
list_collections() / create_collection(...) / move_object(...) |
папки и раскладка файлов |
delete_object(id) |
удалить файл |
agent_chat(query) / agent_continue(...) |
агентный режим: стрим токенов и вызовов инструментов |
agent_status() |
доступен ли агентный режим и память |
list_chats() / get_chat(id) / delete_chat(id) |
история диалогов |
list_agent_memory() / clear_agent_memory() |
что агент запомнил о вас |
Все методы — корутины, кроме agent_chat/agent_continue: они возвращают асинхронный
генератор, так что await не нужен — сразу async for (внутри aclosing).
Клиент — async-context-manager (async with).
Заметки
- Данные изолированы по аккаунту: токен видит только файлы вашего аккаунта. Файлы, загруженные через Telegram-бота, доступны здесь же после привязки бота к аккаунту.
- Базовый URL прода —
https://api.cloud.agentums.ru.
Лицензия
MIT — см. LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for agentum-cloud-sdk 0.1.547
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| agentum_cloud_sdk-0.1.547.tar.gz | 18.1 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agentum_cloud_sdk-0.1.547-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 38.9 kB
Release files / agentum_cloud_sdk-0.1.547.tar.gz
| Download URL | agentum_cloud_sdk-0.1.547.tar.gz |
|---|---|
| Size | 18.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
97c756f7a46b8d302a7270646e469cd2c07827f81a7e1e57dae076f28d322c3e
|
|
BLAKE2b-256 checksum How to use checksums |
27b11d6f8c2a2a5b435c016e6498d423ab6cb0f966f0eed0b262c777c74365f9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.11
|
Release files / agentum_cloud_sdk-0.1.547-py3-none-any.whl
| Download URL | agentum_cloud_sdk-0.1.547-py3-none-any.whl |
|---|---|
| Size | 20.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
70baac2e8fd2a3e6b8b0428f585f7ffea27f2d00d052663fef5f16cbed3bafd1
|
|
BLAKE2b-256 checksum How to use checksums |
a4c5b5a84961a426d17e92ff1bd4d7b113d15bcd7d2d08db3f15c5117faf80f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.11
|
Security for agentum-cloud-sdk 0.1.547
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
