# Архитектура Source: https://docs.ascn.ai/about-agent/architecture Каждый агент состоит из трёх частей. Понять их — значит понять, как настроить агента под любую задачу. Структура агента в боковом меню ## 1. Мозг — личность и возможности **Мозг** определяет, кто этот агент, что он знает и к чему подключён. * **Интеграции** — Gmail, Google Календарь, Диск, Slack, GitHub и другие сервисы * **Навыки** — готовые шаблоны поведения для повторяющихся задач * **Знания** — как агент себя ведёт, что знает о вас и ваши файлы * **Память** — факты, которые агент запомнил в ходе работы ## 2. Задания — что агент делает сам **Задания** — это то, что агент выполняет без вашего участия. | Тип | Когда запускается | Пример | | - | - | - | | **По расписанию** | В заданное время | Каждое утро в 8:00 — сводка писем | | **По событию** | Когда что-то происходит в сервисе | Новое письмо → черновик ответа | Задания создаются через чат — просто опишите, что нужно делать и когда. ## 3. Каналы — где вы общаетесь **Каналы** — это где агент пишет вам и где вы можете ему написать. * **Чат ASCN** — веб-интерфейс платформы * **Telegram** — личный бот * **Slack** — рабочее пространство команды ## Как всё это работает вместе Например, агент по утренней почте: 1. **Мозг** — подключён к Gmail и Календарю, знает ваш рабочий стиль 2. **Задания** — каждое утро в 8:00 собирает важные письма 3. **Каналы** — присылает сводку в Telegram Вы просыпаетесь и уже знаете, что важного пришло за ночь. Начните с настройки Мозга — подключите первую интеграцию. # Возможности Source: https://docs.ascn.ai/about-agent/capabilities Полный список того, что умеет ASCN Agent. ## Работа с почтой и календарём * Читать и анализировать входящие Gmail * Писать черновики ответов в вашем стиле * Отправлять письма по команде * Создавать и редактировать встречи в Google Календаре * Присылать брифинг перед каждой встречей ## Работа с файлами * Читать документы из Google Диска * Отвечать на вопросы по вашим файлам * Создавать и редактировать файлы в рабочем пространстве * Извлекать данные из PDF, таблиц и других форматов ## Командная работа * Работать в Slack-каналах команды * Присылать уведомления в Telegram-группы * Отслеживать активность в GitHub-репозиториях * Создавать задачи и обращения по результатам встреч ## Автоматизации Выполнять действия в заданное время или с заданной периодичностью. Реагировать на события в подключённых сервисах. ## Поиск и анализ * Поиск в интернете с анализом результатов * Мониторинг упоминаний бренда * Анализ конкурентов * Сбор трендов из Reddit, X и других источников ## Генерация контента * Писать тексты для соцсетей и блогов * Генерировать изображения * Создавать структурированные отчёты и сводки ## Расширяемость Добавьте готовые сценарии или создайте свои. Подключите собственные сервисы через API. # Безопасность Source: https://docs.ascn.ai/about-agent/security Как ASCN Agent работает с вашими данными, токенами и разрешениями. ## Принципы * **Каждый агент работает отдельно** — данные одного агента недоступны другому * **Пароли и ключи хранятся в зашифрованном виде** — никто, кроме вас, к ним не имеет доступа * **Вы сами решаете, что агент может делать** — отправлять письма, удалять файлы, создавать события — каждое действие требует вашего разрешения * **Доступ можно отозвать в любой момент** — отключите любой сервис или удалите агента полностью ## Что агент не делает без вашего разрешения * Не отправляет письма * Не делится вашими данными с другими пользователями * Не использует ваши данные для обучения моделей ИИ ## Где этим управлять Выберите, что агент может делать самостоятельно, а что — только с вашего подтверждения. Безопасное хранение токенов и ключей от сервисов. Сброс агента и полное удаление всех его данных. Что агент помнит о вас и как это удалить. # use-cases Source: https://docs.ascn.ai/about-agent/use-cases Реальные примеры, как люди и команды используют ASCN Agent. ## Для личной продуктивности Каждый вечер агент читает входящие и присылает только важное в Telegram. Сохраняет контакты и присылает брифинг перед каждой встречей. «Отправь письмо Ивану», «забронируй встречу» — без открытия браузера. Фиксирует договорённости и ставит задачи после звонков. ## Для бизнеса и команд Проверяет Gmail и Telegram, отвечает на типовые вопросы, эскалирует сложные. Собирает данные из CRM, рекламы и GitHub в утреннюю сводку. Ищет упоминания компании в сети и классифицирует по тональности. Следит за активностью конкурентов и присылает дайджест. ## Для маркетинга и контента Находит тренды, пишет тексты и генерирует изображения. Сканирует Reddit и X, выдаёт список проблем ЦА. Разбор реального кейса: агент по почте и календарю. # Как устроен агент Source: https://docs.ascn.ai/architecture/overview Три уровня архитектуры ASCN Agent: Мозг, Задачи, Каналы. Каждый ASCN Agent состоит из трёх уровней. Понять их — значит понять, как настроить агента под любую задачу. В боковом меню агента видны три ключевых раздела: **Мозг** (①), **Каналы** (②) и **Задачи** (③) — каждый отвечает за свой уровень. Структура агента в боковом меню *** ## Мозг — центр управления **Мозг** — это то, что определяет личность агента, его знания и возможности. Здесь вы настраиваете: * **Интеграции** — к каким сервисам агент имеет доступ: Gmail, Google Calendar, Google Drive, Slack, GitHub * **Скиллы** — повторяемые сценарии поведения для типовых задач * **База знаний** — кто этот агент, как он общается, какие файлы и документы он использует * **Память** — что агент помнит о вас между сессиями Мозг — это настройка один раз. После подключения интеграций и заполнения базы знаний агент готов работать без повторных инструкций. *** ## Задачи — автоматизации **Задачи** — это то, что агент делает сам, без вашего участия. Два вида задач: | Тип | Пример | | - | - | | **По расписанию** | Каждое утро в 8:00 — сводка непрочитанных писем | | **По событию (триггер)** | Пришло новое письмо → агент готовит черновик ответа | Задачи создаются через чат — просто опишите, что нужно делать и когда. *** ## Каналы — где общаться с агентом **Каналы** — это где вы общаетесь с агентом и где он вам отвечает. Доступные каналы: * **Чат ASCN** — веб-интерфейс платформы * **Telegram** — бот, которого вы создаёте через BotFather * **Slack** — рабочее пространство вашей команды Подключите Telegram, чтобы управлять агентом и получать уведомления прямо в мессенджере — без открытия браузера. *** ## Как уровни работают вместе **Пример: агент по утренней почте** 1. **Мозг** — подключён к Gmail и Google Calendar, знает ваш рабочий стиль 2. **Задачи** — каждый день в 8:00 агент читает входящие и формирует сводку 3. **Каналы** — сводка приходит вам в Telegram Вы просыпаетесь и уже знаете, что важного пришло за ночь. *** Начните с настройки Мозга — подключите первую интеграцию. # Подключения Source: https://docs.ascn.ai/brain/connectors Gmail, Slack, Google Диск — подключи раз, агент использует сам. **Подключение** — это провод между агентом и сервисом, которым ты уже пользуешься. Подключил Gmail — агент читает письма и отвечает. Подключил Slack — пишет в каналы. Без подключения агент работает вслепую. ## Что уже работает без настройки Две вещи доступны агенту сразу, из коробки: * **Поиск в интернете** — находит актуальную информацию по любому запросу * **Чтение страниц** — открывает любую публичную ссылку и читает содержимое ## Что можно подключить | Сервис | Что агент сделает за тебя | | - | - | | **Gmail** | Читает, пишет черновики, отправляет, сортирует | | **Google Календарь** | Видит встречи, создаёт и обновляет события | | **Google Диск** | Открывает файлы, создаёт новые, следит за изменениями | | **Google Docs / Sheets** | Читает и редактирует документы | | **Slack** | Читает каналы и пишет сообщения | | **GitHub / GitLab** | Смотрит задачи, ветки, запросы на слияние | | **Notion / Supabase** | Работает со страницами и базами данных | Нужного сервиса нет в списке? Его можно подключить вручную — об этом ниже. ## Самый быстрый способ — через чат Просто напиши агенту что хочешь сделать. Он сам поймёт что подключить и попросит войти в аккаунт. ```text theme={null} Подключи мой Gmail и каждый вечер присылай сводку важных писем ``` ```text theme={null} Следи за моим Календарём и напоминай о встречах за час ``` Авторизация происходит прямо в чате — одно нажатие, и готово. ## Подключить вручную Если хочешь настроить сам: 1. Открой **Мозг → Подключения** 2. Найди нужный сервис 3. Нажми **+ Добавить** 4. Разреши запрошенный доступ Раздел Мозг → Подключения с кнопками «+ Добавить» После подключения агент сам предложит что с этим можно сделать. ## Подключить нестандартный сервис Для разработчиков: если нужного сервиса нет в списке — его можно добавить через открытый стандарт подключения инструментов (MCP). 1. В разделе **Дополнительные подключения** нажми **+ Добавить** 2. Укажи адрес сервера 3. Агент получит доступ к его инструментам ## Управление подключёнными сервисами Каждое подключение можно в любой момент: * **Сменить аккаунт** — привязать другую учётную запись * **Отключить** — поставить на паузу * **Удалить** — убрать полностью > ⚠️ Если удалишь подключение, все задания которые его используют — перестанут работать. Лучше сначала отключи, убедись что ничего не сломалось — и только потом удаляй. # База знаний Source: https://docs.ascn.ai/brain/knowledge Всё что агент знает о себе и о тебе — ещё до первого сообщения. База знаний — это то, что агент читает перед тем как ответить. Кто он, как себя ведёт, что ты предпочитаешь, какие документы использовать. Без этого агент — умный, но незнакомец. Раздел Мозг → База знаний ## Что здесь есть **Ядро** — три системных файла: IDENTITY.md, SOUL.md и USER.md. Отвечают за характер, ценности и всё что агент знает о тебе. **Документы** — справочные файлы: списки клиентов, шаблоны, инструкции, регламенты. Загружаются через **+ Добавить** или перетаскиванием. *** ### IDENTITY.md — кто твой агент Должностная инструкция. Здесь задаёшь роль, стиль общения и что агент делает, а что — нет. Агент читает этот файл при каждом запуске. ```markdown theme={null} # Роль Ты — ассистент по почте и встречам. ## Стиль - Краткие ответы: максимум 3-4 предложения, если не попросят больше - При неопределённости — уточняй, не угадывай - Деловой тон, без лишних вступлений ## Фокус - Почта и встречи: приоритет — задачи с дедлайнами - Напоминания по срокам - Подготовка к встречам ``` *** ### USER.md — информация о тебе Всё что агент должен знать о тебе: имя, проекты, предпочтения, часовой пояс. Агент дополняет этот файл сам по ходу общения — но лучше заполнить сразу. ```markdown theme={null} # О пользователе Имя: [имя] Обращение: на «ты» ## Проекты - Основной: [название] - Дедлайн: [дата] ## Предпочтения - Краткие ответы, без воды - Часовой пояс: UTC+3 - Утром — только самое важное ``` Чтобы агент запомнил что-то прямо сейчас — скажи ему в чате: ```text theme={null} Запомни: я предпочитаю получать ответы списком, без вступлений ``` Он обновит USER.md сам. *** ### SOUL.md — характер и приоритеты Тонкая настройка. Как агент ведёт себя в неоднозначных ситуациях, что считает важным, где не соглашается автоматически. ```markdown theme={null} ## Ценности - Честность важнее комфорта: лучше сказать неприятную правду - Конкретика вместо общих слов: факты, числа, примеры - Предлагай следующий шаг — не просто отвечай, а двигай вперёд ## Ограничения - Не принимай решения за пользователя в важных вопросах — спрашивай - Не соглашайся автоматически: если видишь проблему — говори ``` *** ### Документы Справочники которые агент использует при ответах: список клиентов, шаблоны писем, описание продукта, инструкции. Загружаются через **Документы → + Добавить** или перетаскиванием. *** > Чем база знаний отличается от памяти — читай в разделе [Память](/brain/memory). # Память Source: https://docs.ascn.ai/brain/memory Как агент запоминает информацию между сессиями. **Память** — это то, что агент узнаёт о вас в процессе работы и сохраняет между сессиями. В отличие от базы знаний, которую вы заполняете вручную, память формируется автоматически. ## Как работает память В ходе разговоров агент запоминает: * Упомянутые вами предпочтения и детали * Контекст текущих задач и проектов * Ваш стиль общения и реакции на ответы Эта информация сохраняется и используется в следующих сессиях — вам не нужно повторять одно и то же каждый раз. ## Как управлять памятью **Чтобы агент запомнил что-то конкретное**, скажите ему прямо в чате: ``` Запомни: я предпочитаю краткие ответы без вступлений. ``` ``` Запомни: встречи в пятницу я не назначаю принципиально. ``` Агент обновит ваш профиль и будет учитывать это в дальнейшем. **Чтобы агент забыл информацию**, также скажите ему: ``` Забудь, что я говорил про проект X — он отменён. ``` ## Чем память отличается от базы знаний | Память | База знаний | | - | - | | Формируется автоматически | Вы заполняете вручную | | Личные детали из разговоров | Справочная информация, роли, правила | | Меняется со временем | Остаётся стабильной | ## Приоритет при конфликте Информация из базы знаний имеет приоритет над памятью. Если в разговоре вы сказали одно, а в файлах базы знаний написано другое — агент следует базе знаний. **Пример конфликта:** > В SOUL.md: «Никогда не создавай встречи без явного подтверждения»\ > В разговоре: «Запишись на встречу с Иваном на пятницу»\ > Результат: агент предложит детали встречи для подтверждения, но не создаст её автоматически Это позволяет зафиксировать важные ограничения раз и навсегда — они не «перезаписываются» случайной фразой в чате. # Мозг: обзор Source: https://docs.ascn.ai/brain/overview Центральный блок настройки агента — здесь вы объясняете ему кто он, что умеет и к чему подключён. **Мозг** — это центр управления вашим агентом. Здесь вы задаёте, к чему он подключён, как себя ведёт и что знает о вас и вашей работе. Раздел Мозг раскрыт в боковом меню: Интеграции, Навыки, Знания, Память ## Что входит в Мозг Внешние сервисы, к которым подключён агент. Например: Gmail, Google Календарь, Slack, GitHub. Агент читает данные из них и выполняет действия — отвечает на письма, создаёт события, постит в канал. Готовые шаблоны поведения для повторяющихся задач. Например: «составлять краткое саммари после каждой встречи» или «отвечать на входящие по шаблону поддержки». Можно добавить из библиотеки или создать свои через чат. Всё, что агент знает о вас и вашей работе. Например: как вас зовут, в какой компании работаете, какой тон общения предпочитаете, какие документы использует агент как справочник. То, что агент запомнил в ходе разговоров. Например: «Alex предпочитает короткие сводки» или «встречи по понедельникам не трогать». Сохраняется между сессиями автоматически. ## Как открыть Мозг 1. Войдите в ASCN и откройте нужного агента 2. Перейдите в раздел **Мозг** в боковом меню ## Рекомендованный порядок настройки 1. **Интеграции** — подключите сервисы, которые нужны для задачи. Например, Gmail и Google Календарь для агента по почте. 2. **Знания** — объясните агенту кто он и расскажите о себе. Например: «Ты помощник Alex, менеджера по продажам. Пиши коротко и по делу». 3. **Навыки** — добавьте, если нужна специфическая логика. Например, навык «еженедельный отчёт по сделкам». 4. **Память** — работает автоматически, вмешиваться не нужно. # Скиллы Source: https://docs.ascn.ai/brain/skills Научи агента один раз — он запомнит навсегда. Скилл — это память на поведение. Объяснил агенту как делать сводку почты, как оформлять отчёт, как реагировать на запросы клиентов — он запомнил и повторяет. Не нужно каждый раз объяснять заново. Раздел Мозг → Скиллы ## Готовые скиллы и свои В **Мозг → Скиллы** два раздела. **Open Source скиллы** — библиотека от ASCN и сообщества. Нашёл нужный, нажал **+ Установить**. Например, скилл `pdf` даёт агенту работать с PDF-файлами: читать, заполнять формы, шифровать. Скилл `creating-financial-models` — строить DCF и считать сценарии. Таких скиллов десятки. **Мои скиллы** — то, чему ты сам научил агента. Изначально пусто. ## Примеры скиллов | Скилл | Что делает | | - | - | | **email-digest** | Собирает сводку писем: группирует по отправителю, выделяет важные, пропускает рассылки | | **meeting-prep** | Перед встречей достаёт из календаря участников, ищет о них инфу, присылает краткую справку | | **crm-update** | После звонка или письма сам обновляет карточку клиента в CRM | | **daily-brief** | Каждое утро в заданное время присылает сводку: задачи, встречи, важные письма | | **invoice-tracker** | Следит за входящими счетами, напоминает об оплате, помечает просроченные | | **social-reply** | Отвечает на типовые комментарии и вопросы в соцсетях по заданному тону | | **lead-qualifier** | Оценивает входящие заявки по критериям и расставляет приоритеты | | **content-repurpose** | Из длинной статьи делает пост для Telegram, тред для X и письмо для рассылки | | **support-triage** | Сортирует входящие обращения по теме и срочности, отвечает на типовые сам | | **weekly-report** | В конце недели собирает данные из таблиц и присылает итоговый отчёт | ## Как создать свой Просто напиши в чате что агент должен делать. Он разберётся и создаст скилл сам. ```text theme={null} Создай скилл: когда прошу сводку почты — группируй по отправителю, выдели письма с дедлайнами или вопросами ко мне, рассылки пропусти ``` Готовый скилл появится в **Мои скиллы**. Можно открыть, посмотреть, подправить. Если хочешь создать вручную — кнопка **+ Добавить** там же. ## Где это хранится Все скиллы лежат в файлах агента по пути `.agents/skills/` — раздел **Файлы**. Текстовые файлы, можно редактировать напрямую. # Slack Source: https://docs.ascn.ai/channels/slack Подключите агента к Slack и работайте с ним прямо в рабочем пространстве команды. Slack позволяет общаться с агентом прямо в рабочем пространстве вашей команды — задавать вопросы, получать уведомления и давать команды, не выходя из привычной среды. ## Как подключить Slack 1. Откройте раздел **Каналы** в настройках агента 2. Выберите **Slack** 3. Нажмите **Подключить** 4. Авторизуйтесь в своём Slack-аккаунте и выберите рабочее пространство 5. Подтвердите запрошенные разрешения После подключения агент появится в вашем Slack как приложение. ## Что можно делать через Slack * Задавать вопросы и получать ответы в личном сообщении агента * Давать команды: «проверь почту», «что у меня в календаре?», «пришли сводку» * Получать уведомления от триггеров и задач по расписанию * Отправлять сообщения в каналы через агента (если интеграция Slack подключена в Мозге) **Пример команд:** ```text theme={null} Какие встречи у меня завтра? ``` ```text theme={null} Отправь в канал #general: "Ежедневный синк переносится на 15:00." ``` ```text theme={null} Проверь почту и пришли сводку важных писем за сегодня. ``` Для отправки сообщений в Slack-каналы через агента дополнительно подключите **интеграцию Slack** в разделе **Мозг → Интеграции**. # Telegram Source: https://docs.ascn.ai/channels/telegram Подключите агента к Telegram: личный чат, группа, канал или личный аккаунт. Telegram — самый удобный способ взаимодействовать с агентом вне браузера: получать уведомления, задавать вопросы и давать команды прямо из мессенджера. ## Личный чат с ботом ### Шаг 1. Создайте бота через BotFather Откройте [@BotFather](https://t.me/BotFather) в Telegram и создайте нового бота. ASCN покажет пошаговую инструкцию прямо в интерфейсе. Диалог с BotFather — /newbot, имя, username и получение токена ### Шаг 2. Следуйте инструкции в ASCN Откройте **Каналы → Telegram**. ASCN запустит мастер подключения: 1. Откройте BotFather в Telegram — кнопка **Открыть @BotFather** 2. Отправьте команду `/newbot` 3. Выберите отображаемое имя бота 4. Выберите username (должен заканчиваться на `_bot`) 5. Скопируйте токен — BotFather пришлёт его в чат Мастер подключения Telegram в ASCN — 5 шагов ### Шаг 3. Вставьте токен Нажмите **У меня есть токен →**, вставьте токен в поле. Можно вставить всё сообщение от BotFather целиком — ASCN извлечёт токен автоматически. Нажмите **Подключить бота**. Ввод токена и кнопка «Подключить бота» ### Шаг 4. Подтвердите владение После подключения ASCN попросит верифицировать бота: 1. Нажмите **Открыть бота в Telegram** 2. Нажмите **Старт** в открывшемся диалоге — это свяжет ваш аккаунт с агентом Подтверждение: открыть бота и нажать Старт ### Готово После нажатия Старт бот поприветствует вас и предложит быстро подключить интеграции прямо в Telegram. Бот в Telegram после /start — кнопки подключения сервисов *** ## Подключение к группе или каналу Агента можно добавить в Telegram-группу или канал — для командной работы или публикации уведомлений. ### Шаг 1. Добавьте бота в группу или канал 1. Откройте настройки группы/канала → **Администраторы** → **Добавить администратора** 2. Найдите вашего бота по username и добавьте 3. Выдайте права: **Отправка сообщений** (для группы) или **Публикация** (для канала) ### Шаг 2. Получите ID чата **Простой способ:** добавьте бота [@RawDataBot](https://t.me/RawDataBot) в группу или канал — он сразу пришлёт сообщение с `chat.id`, скопируйте его. После получения ID удалите @RawDataBot из группы. **Альтернатива:** напишите любое сообщение в группе/канале, затем откройте: ``` https://api.telegram.org/bot<ВАШ_ТОКЕН>/getUpdates ``` В ответе найдите поле `chat.id` (для каналов начинается с `-100`). ### Шаг 3. Укажите ID в ASCN В разделе **Каналы → Telegram** введите Chat ID и нажмите **Сохранить**. В группах агент отвечает на сообщения, адресованные боту через @username, или в ответ на его сообщения — чтобы не засорять общий чат. *** ## Подключение к личному аккаунту Telegram Возможность Telegram позволяет агенту работать от имени вашего личного аккаунта — не как бот, а как вы сами. **Что агент получает при подключении личного аккаунта:** * Доступ к вашим чатам и переписке * Возможность отправлять сообщения от вашего имени по команде или триггеру * Видит все входящие, включая личные переписки **Агент НЕ делает автоматически**: не отвечает в чатах без явной команды или настроенного триггера. Рекомендация: если хотите сохранить разделение — используйте отдельный Telegram-аккаунт специально для агента. ### Как подключить 1. Перейдите в **Каналы → Telegram** 2. Выберите вкладку **Личный аккаунт** 3. Нажмите **Подключить аккаунт** 4. Введите номер телефона и подтвердите код из Telegram После подключения агент сможет читать входящие, отправлять сообщения от вашего имени и реагировать на упоминания. *** ## Что можно делать через Telegram * Задавать вопросы и получать ответы * Давать команды: «отправь письмо», «забронируй встречу», «что у меня сегодня?» * Получать уведомления от триггеров и задач по расписанию * Загружать файлы и изображения прямо в чат **Примеры команд:** ``` Что у меня в почте за сегодня? ``` ``` Отправь письмо Ивану Петрову: подтверждаю встречу на пятницу в 15:00. ``` ``` Запишись на встречу с командой завтра в 11:00, название "Синк по продукту". ``` Удобный паттерн: триггер на важные письма — мгновенное уведомление в Telegram, утренняя сводка — задача по расписанию прямо в чат. # ASCN.AI API — Документация Source: https://docs.ascn.ai/crypto/overview Программный доступ к крипто-аналитике институционального уровня в реальном времени. ## ✨ Введение Добро пожаловать в ASCN.AI Assistant API! Наша цель — предоставить программный доступ к крипто-аналитике институционального уровня в реальном времени. API преобразует сложные on-chain данные с более чем 20 блокчейнов, а также данные социальных сетей и новостных источников, в готовые к применению инсайты — через простые запросы на естественном языке. Строите торговых ботов, трекеры портфеля или AI-инструменты для управления сообществом — наш API даёт скорость, точность и глубину, которые нужны, чтобы быть на шаг впереди. *** ## 🚀 Начало работы ### Шаг 1. Получите API-ключ **Быстрый вариант** — запросить напрямую в [поддержке в Telegram](https://t.me/ascnai). **Более полезный вариант** — зарегистрироваться на [B2B-платформе](https://b2b.ascn.ai), ознакомиться с планами и выбрать Free. Так вы получите доступ к подробным логам запросов, информации о расходе кредитов и возможности мгновенно перейти на платный план. ### Шаг 2. Выполните первый запрос Откройте терминал и выполните команду. Замените `YOUR_API_KEY` на ваш ключ. ```bash theme={null} curl --request POST \ --url 'https://b2b.api.ascn.ai/api/ai-assistant/v2/invoke_assistant' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'X-API-Key: YOUR_API_KEY' \ --data '{ "message": "Сделай краткий анализ PEPE: цена, объём, настроения", "model": "ascn_v1.2" }' ``` ### Шаг 3. Посмотрите ответ Вы получите JSON с анализом монеты PEPE в реальном времени: рыночные метрики, on-chain активность и оценку настроений. Полная структура ответа описана в разделе [Схема ответа](#схема-ответа). *** ## 🔓 Аутентификация Все запросы к API должны быть аутентифицированы. Передавайте ключ в заголовке `X-API-Key` каждого запроса. ```text theme={null} X-API-Key: YOUR_API_KEY ``` API-ключ — секрет. Не публикуйте его в клиентском коде (браузеры, мобильные приложения). Все запросы к API должны выполняться с защищённого сервера. ## 🟢 Коды ответов | Код | Значение | Описание | | - | - | - | | `200` | OK | Запрос успешен. | | `400` | Bad Request | Неверный формат запроса или отсутствуют обязательные параметры. | | `401` | Unauthorized | Неверный или отсутствующий API-ключ. | | `403` | Forbidden | У ключа нет прав на это действие. | | `429` | Too Many Requests | Превышен лимит запросов — см. [Лимиты запросов](#-лимиты-запросов). | | `500` | Internal Server Error | Ошибка на сервере. Попробуйте позже. | Пример ответа с ошибкой: ```json theme={null} { "detail": "Authentication credentials were not provided." } ``` *** ## 🧠 Возможности ### Рыночные данные в реальном времени Данные с более чем 20 блокчейнов: ценовые графики, объём, капитализация и технический анализ любого токена. ### Анализ токена Потоки токенов (CEX), балансы холдеров (топ-адреса, киты, фонды), крупнейшие переводы, активность покупателей и продавцов. ### On-chain анализ Мониторинг DeFi-позиций, трекинг DEX-сделок и выявление прибыльных кошельков на 20+ блокчейнах, включая EVM-сети и Solana. ### Бессрочные контракты (DEX) Инсайты по DEX-фьючерсному рынку в реальном времени. Отслеживайте топ-трейдеров на Hyperliquid, их стратегии, открытые позиции, плечо, P/L и историю сделок. ### Анализ настроений Анализ Telegram-сообществ и новостных медиа — чёткая картина позитивных и негативных настроений по любой монете. ### Веб-поиск AI-ассистент выполняет расширенные поиски для сбора публичной информации о проектах, командах и рыночных трендах. *** ## 📜 Шаблоны использования | Сценарий | Описание | Используемые функции | | - | - | - | | Торговый бот | Бот, торгующий на основе рыночных данных, on-chain событий и анализа настроений. | `Рыночные данные`, `On-chain анализ`, `Настроения` | | Трекер портфеля | Обзор криптоактивов, DeFi-позиций и исторической доходности с AI-инсайтами. | `On-chain анализ` | | Дашборд настроений | Визуализация настроений рынка по конкретным монетам. | `Анализ настроений` | | Управление сообществом | AI-ассистент для Telegram/Discord, отвечающий на вопросы о рынке. | `Веб-поиск`, `Рыночные данные` | | Инструмент due diligence | Глубокий анализ новых токенов: распределение холдеров, потоки умных денег. | `Анализ токена` | | Исследовательский ассистент | Объединяет on-chain данные, метрики, настроения и веб-информацию. | `Анализ токена`, `Веб-поиск` | *** ## 📚 API Reference **Base URL:** `https://b2b.api.ascn.ai` | Метод | Эндпоинт | Назначение | | - | - | - | | `POST` | `/api/ai-assistant/v2/invoke_assistant` | Полный ответ одним запросом. | | `POST` | `/api/ai-assistant/v2/invoke_assistant_stream` | Потоковый ответ через SSE. | ### POST /invoke\_assistant Отправляет сообщение AI-ассистенту и возвращает полный структурированный анализ за один запрос. **Тело запроса** | Параметр | Тип | Описание | | - | - | - | | `message` | string | Вопрос или сообщение для AI-ассистента на естественном языке. Обязателен во всех запросах, **кроме** ответа на HIL-запрос — там достаточно `chat_id` + `hil_response`. | | `chat_id` | uuid | Опционально. ID существующего чата для продолжения разговора. **Обязателен** при ответе на HIL-запрос. | | `model` | string | Опционально. Модель AI. По умолчанию: `ascn_v1.2`. | | `auto_hil` | bool | Опционально. По умолчанию `false`. При `true` сервис сам разрешает неоднозначность (берёт первый вариант) и возвращает готовый `content`. Только для sync-режима. | | `hil_response` | object | Опционально. Ответ пользователя на HIL-запрос — см. [Продолжение диалога после HIL](#продолжение-диалога-после-hil). | **Пример запроса** ```json theme={null} { "message": "Сделай глубокий on-chain и рыночный анализ DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 (BONK)", "model": "ascn_v1.2" } ``` #### Схема ответа | Поле | Тип | Когда приходит | | - | - | - | | `chat_id` | uuid | Всегда. | | `chat_title` | string | Всегда. | | `message_id` | string \| null | При финальном ответе. | | `content` | string \| null | Когда ответ готов. | | `hil` | object \| null | Когда ассистент ждёт выбор пользователя — см. [HIL](#hil-human-in-the-loop). | | `error` | string \| null | При ошибке. | В одном ответе приходит **либо** `content` (ответ готов), **либо** `hil` (нужен ввод пользователя) — но не оба одновременно. **Пример: ответ готов** ```json theme={null} { "chat_id": "6f1c2a9e-0b3d-4f27-9c51-8ad2e7b4c910", "chat_title": "Анализ BONK", "message_id": "msg_01H9Z7", "content": "BONK торгуется на уровне ...", "hil": null, "error": null } ``` **Пример: требуется выбор пользователя** ```json theme={null} { "chat_id": "6f1c2a9e-0b3d-4f27-9c51-8ad2e7b4c910", "chat_title": "Анализ PEPE", "message_id": null, "content": null, "hil": { "type": "token_select", "description": "Найдено несколько токенов с тикером PEPE. Выберите нужный.", "choices": [ { "name": "Pepe", "symbol": "PEPE", "main_chain": "ethereum", "price_usd": 0.0000112, "market_cap_usd": 4700000000 }, { "name": "Pepe on Solana", "symbol": "PEPE", "main_chain": "solana", "price_usd": 0.0000004, "market_cap_usd": 1200000 } ] }, "error": null } ``` ### HIL (Human-in-the-Loop) Ассистент может приостановить обработку и запросить у пользователя уточнение — например, выбрать конкретный токен, когда тикер неоднозначен. В этом случае финального `content` в ответе нет, вместо него приходит объект `hil`. **Объект `hil`** | Поле | Тип | Описание | | - | - | - | | `type` | string | Тип запроса. Например, `"token_select"`. | | `description` | string | Пояснение для пользователя: что именно нужно выбрать и почему. | | `choices` | array of object | Список вариантов на выбор. | Поля элемента `choices` совпадают с полями элемента `hil_response.chosen` (см. ниже). #### Продолжение диалога после HIL Чтобы продолжить, отправьте новый запрос на тот же эндпоинт, передав выбор пользователя: | Параметр | Тип | Описание | | - | - | - | | `chat_id` | uuid | **Обязателен.** ID чата, в котором пришёл HIL-запрос. | | `hil_response.chosen` | array | Выбранные пользователем варианты. | | `message` | — | Можно опустить: контекст берётся из чата. | Поля элемента `hil_response.chosen` (все опциональны — достаточно передать те, что однозначно идентифицируют вариант): | Поле | Тип | | - | - | | `name` | string | | `symbol` | string | | `logo_url` | string | | `main_chain` | string | | `contracts` | array | | `price_usd` | number | | `market_cap_usd` | number | | `description` | string | **Пример ответа на HIL-запрос** ```json theme={null} { "chat_id": "6f1c2a9e-0b3d-4f27-9c51-8ad2e7b4c910", "hil_response": { "chosen": [ { "name": "Pepe", "symbol": "PEPE", "main_chain": "ethereum" } ] } } ``` #### Автоматический выбор: auto\_hil Если интерактивный выбор в вашем сценарии не нужен, передайте `auto_hil: true` в исходном запросе. Сервис сам возьмёт первый вариант из `choices` и вернёт готовый `content` — без промежуточного HIL-ответа. `auto_hil` работает только в sync-режиме (`/invoke_assistant`). В стриминге параметр игнорируется — HIL-события нужно обрабатывать на стороне клиента. ### POST /invoke\_assistant\_stream Для приложений реального времени — SSE-поток, который отдаёт части ответа по мере генерации. Тело запроса такое же, как у `/invoke_assistant`, за исключением `auto_hil` (не применяется). **События потока** | Событие | Данные | Описание | | - | - | - | | `chat` | `{"chat_id": "...", "chat_title": "..."}` | Контекст чата в начале потока. | | `pending_tool_call` | `{"call_id": "...", "title": {...}}` | Внутренний инструмент вызван для сбора данных. | | `finished_tool_call` | `{"call_id": "..."}` | Инструмент завершил работу. | | `message_start` | `{"t": "..."}` | Контент сообщения в процессе генерации. | | `message_end` | `{"message_id": "..."}` | Текущее сообщение завершено. | | `hil` | `{"type": "...", "description": "...", "choices": [ ... ]}` | Ассистент ждёт выбор пользователя. | | `finish` | `null` | Завершение всего потока. | **Событие `hil`** ```text theme={null} event: hil data: {"type": "token_select", "description": "Найдено несколько токенов с тикером PEPE. Выберите нужный.", "choices": [ ... ]} ``` Клиент обязан обрабатывать событие `hil`. Структура `data` совпадает с полем `hil` в sync-ответе. После получения события продолжите диалог **новым** запросом с `chat_id` и `hil_response` — так же, как в sync-режиме. *** ## 📌 О сервисе ### 🔴 Лимиты запросов | Тариф | Запросов в минуту | | - | - | | Free | 60 | | Pro | 300 | | Enterprise | Индивидуально | При превышении лимита — HTTP `429 Too Many Requests`. Рекомендуем реализовать повторные попытки с экспоненциальной задержкой. Подробности о тарифах и кредитах — на [странице цен](https://arbitragescanner.io/crypto-api). ### ⛓️ Поддерживаемые блокчейны | Категория | Блокчейны | | - | - | | EVM-сети | Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Base и другие | | Solana | Полная поддержка: on-chain данные, DEX-сделки, DeFi-анализ | | Другие | Популярные блокчейны вне EVM | *** ## 🙋 FAQ **Какие языки программирования поддерживаются?** API не зависит от языка. Используйте любой, поддерживающий HTTP-запросы. **Можно ли использовать API в коммерческих целях?** Да. Подробности — в [Условиях использования](https://ascn.ai/terms). **Чем отличается `invoke_assistant` от `invoke_assistant_stream`?** `invoke_assistant` возвращает полный ответ за один запрос. `invoke_assistant_stream` стримит ответ через SSE — подходит для интерактивных приложений. **Почему в ответе нет `content`?** Скорее всего, ассистент запросил уточнение — проверьте поле `hil` и продолжите диалог с `chat_id` + `hil_response`. Если интерактивный выбор не нужен, передавайте `auto_hil: true` (только в sync-режиме). См. [HIL](#hil-human-in-the-loop). **Есть ли поддержка?** Да — [info@ascn.ai](mailto:info@ascn.ai), [Telegram](https://t.me/Ascn_support_bot). *** ## 🔗 Ссылки * **Сайт:** [https://ascn.ai](https://ascn.ai) * **B2B-платформа:** [https://b2b.ascn.ai](https://b2b.ascn.ai) # Быстрый старт Source: https://docs.ascn.ai/getting-started/quickstart Создайте своего первого агента за 5 минут. Image ## Шаг 1. Создайте аккаунт Перейдите на [ascn.ai](https://ascn.ai/ru/agent) и нажмите **Попробовать бесплатно**. Регистрация занимает меньше минуты. ## Шаг 2. Создайте первого агента На главной странице нажмите **+ Создать новый** в правом верхнем углу. Выбор агента в меню и кнопка «+ Создать новый» ## Шаг 3. Опишите задачу Напишите агенту в чате, чем он должен заниматься. Чем конкретнее — тем лучше. ```text theme={null} Следи за дедлайнами в моём Google Календаре. За день до дедлайна напоминай мне о задаче и спрашивай, нужна ли помощь с подготовкой. ``` ```text theme={null} Каждое утро в 9:00 присылай мне сводку непрочитанных писем в Gmail с кратким описанием каждого. ``` Начните с задачи, которую вы уже делаете вручную каждый день. Так быстрее всего почувствуете разницу. ## Шаг 4. Подключите нужные сервисы Агент сам предложит подключить нужные сервисы после первого сообщения — просто следуйте его подсказкам в чате. Если хотите подключить что-то самостоятельно — откройте раздел **Мозг**, выберите **Интеграции** и найдите нужный сервис. Раздел Мозг → Интеграции → Приложения ## Шаг 5. Готово Агент уже работает. Пишите ему в чате ASCN или подключите [Telegram](/channels/telegram) — и общайтесь откуда удобно. *** ## Что дальше Разберитесь в архитектуре: Мозг, Задания, Каналы. Подключите Gmail, Календарь, Диск, Slack, GitHub. Настройте автоматические утренние сводки и напоминания. Пошаговая сборка агента по почте и календарю. # Что такое ASCN Agent? Source: https://docs.ascn.ai/getting-started/what-is-ascn-agent Помощник на основе ИИ, который работает за вас — пока вы заняты другим. Создавайте **агентов** которые будут выполнять работу за вас. Расскажите своему суперагенту, что вам нужно, и он превратит вашу повседневную работу в задачи, обновления, отчеты и автоматические действия.

Ваш агент может выступать в роли личного помощника, специалиста службы поддержки, маркетолога или аналитика — в зависимости от того, какую задачу вы ему поручите. Он может отслеживать обновления, привлекать потенциальных клиентов, готовить отчеты, запускать повторяющиеся рабочие процессы, отправлять обновления и отвечать через чат или подключенные каналы ## **Работайте с помощью ASCN Agent** * Запускает процессы по расписанию: ежедневные сводки, недельные отчёты, регулярные напоминания * Срабатывает на триггеры — новые данные в приложении или активность в подключённом сервисе * Следит за системами и инструментами и сообщает о важных изменениях * Подключается к видеовстречам, ведёт заметки и фиксирует задачи * Ведёт общие заметки, которые вы и ASCN читаете и дополняете вместе * Собирает лиды, мониторит конкурентов, готовит отчёты и организует follow-up * Работает с веб-страницами: изучает темы, ищет информацию, выполняет действия * Использует ваши файлы, память и подключённые инструменты, чтобы отвечать с учётом контекста * Дорабатывает ваши приложения Base44 прямо в чате — от мелких правок до запуска серверных функций * Общается там, где вам удобно: WhatsApp, Telegram * Подключается к Google Workspace, Tiktok, GitHub, Notion, HubSpot и еще 3000+ интеграций * Генерирует видео и фото **Общение с вашим агентом** Опишите нужный результат дальше это диалог: агент задаёт уточняющие вопросы, вы правите ответы и добавляете контекст по ходу дела. Можно загружать файлы, вставлять изображения или надиктовывать голосом, чтобы быстрее объяснить задачу. Чем дольше вы работаете вместе, тем точнее ASCN подсказывает предлагает готовые промпты, нужные коннекторы и рабочие процессы, исходя из текущего разговора. Подсказки появляются прямо в поле ввода, подстраиваются под ваш язык и обновляются, когда нужна другая отправная точка. Начните с реальной задачи, с которой вы часто сталкиваетесь, например поиск новых потенциальных клиентов, отслеживание конкурентов, подготовка отчетов, мониторинг электронной почты или обобщение обновлений в различных инструментах. **Использование интеграций** Используйте плагины, чтобы подключить вашего суперагента к сервисам и добавить навыки, которые он может выполнять * **Коннекторы:** сервисы, к которым может подключаться ваш суперагент, например Slack, Notion, GitHub, HubSpot, Google Drive. Например, подключите Gmail, чтобы ваш суперагент мог составлять для вас краткие обзоры и черновики писем Image * **Навыки:** наборы инструкций, которые расширяют возможности вашего агента. Просматривайте тщательно отобранные навыки [ASCN.ai](http://ASCN.ai) , полный каталог по категориям или создавайте и загружайте свои собственные. Image ## **Запуск рабочих процессов** Запускайте действия по расписанию или при срабатывании триггера. Используйте рабочие процессы для повторяющихся задач, например для утреннего брифинга каждый день в 10 утра или для напоминания, если электронное письмо остается непрочитанным в течение дня. Вы можете настроить рабочие процессы, пообщавшись со своим агентомм * **Запланированными рабочими процессами:** запускаются в определенное время, например для составления ежедневных сводок, еженедельных отчетов или повторяющихся напоминаний. * **Рабочими процессами по триггеру:** запускаются при наступлении триггера, например при изменении ваших данных или активности в подключенном инструменте. * **Активностью:** просматривайте последние запуски рабочих процессов. ## **Хранение файлов** Храните документы, папки и другие ресурсы, на которые может ссылаться ваш суперагент, в том числе те, которые вы загружаете, и те, которые он создает в процессе работы. Вы можете загружать файлы, папки или создавать папки для организации рабочего пространства вашего агента Image # Агент по почте и календарю Source: https://docs.ascn.ai/guides/email-calendar-agent Пошаговая сборка агента, который читает почту, делает черновики, присылает утреннюю сводку и управляет встречами через Telegram. В этом руководстве мы соберём с нуля агента, который: * Читает Gmail и присылает утреннюю сводку * Готовит черновики ответов на важные письма * Видит встречи в Google Calendar и напоминает о них * Принимает команды через Telegram Время на настройку: **10–15 минут**. *** ## Шаг 1. Создайте агента и опишите задачу 1. Войдите в ASCN и перейдите к списку агентов 2. Нажмите **+ Создать новый** 3. В чате напишите задачу: ```text theme={null} Ты — мой персональный ассистент по почте и встречам. Твоя задача: следить за Gmail и Google Calendar, готовить черновики ответов, присылать утренние сводки и выполнять мои поручения через Telegram. ``` После первого сообщения агент сразу предложит подключить нужные интеграции прямо в чате. Чат с описанием задачи — агент предлагает подключить Gmail, Google Calendar и Telegram *** ## Шаг 2. Подключите интеграции Прямо в чате нажмите кнопки подключения (①): * **Gmail** → **Connect** — агент запросит доступ к почте * **Google Calendar** → **Connect** — доступ к календарю * **Telegram** → **Connect** — можно подключить сейчас или позже через раздел **Каналы** После подключения кнопки покажут статус **Connected** (② ③). *** ## Шаг 3. Настройте личность агента через чат Вставьте в чат правила поведения агента: ```text theme={null} # Роль Ты — персональный ассистент по почте и встречам. ## Стиль - Краткие ответы — только суть - Не пересказывай всё письмо, выдели главное и нужное действие - При неопределённости — спрашивай, не угадывай ## Приоритеты при работе с почтой 1. Письма с дедлайнами или явными вопросами ко мне 2. Письма от конкретных людей (уточняй у меня список VIP) 3. Остальное — в сводку, без уведомлений ## Запрещено - Отправлять письма без моего явного подтверждения - Удалять письма или события без подтверждения - Самостоятельно принимать решения о встречах ``` Агент сохранит эти правила и сразу начнёт работать по ним. Вставка правил поведения в чат — агент подтверждает и начинает работу *** ## Шаг 4. Расскажите агенту о себе Вставьте в чат информацию о ваших предпочтениях: ```text theme={null} # О пользователе Имя: [ваше имя] Обращение: на «ты» Часовой пояс: UTC+3 ## Предпочтения - Утренняя сводка в 8:30 - Важные письма — уведомление сразу, остальное — в сводку - Встречи подтверждать лично, не автоматически ``` Агент запомнит всё и подтвердит сохранение. Агент подтверждает сохранённые настройки пользователя *** ## Шаг 5. Подключите Telegram Если не подключили на шаге 2 — перейдите в **Каналы → Telegram** и следуйте инструкции. Подробно: [Как подключить Telegram](/channels/telegram). *** ## Шаг 6. Настройте утреннюю задачу Напишите агенту в чате: ```text theme={null} Каждый день в 8:30 делай следующее: 1. Проверь непрочитанные письма в Gmail за последние 12 часов 2. Составь краткую сводку: важные письма (с дедлайном или вопросом ко мне), письма требующие ответа, остальное кратко одной строкой 3. Проверь Google Calendar на сегодня — список встреч с временем 4. Отправь мне сводку в Telegram ``` Агент создаст задачу по расписанию и начнёт выполнять её каждое утро. *** ## Готово — что получилось | Функция | Как работает | | - | - | | Утренняя сводка | Каждый день в 8:30 в Telegram: почта + встречи на день | | Черновики ответов | По запросу в чате, с подтверждением перед отправкой | | Напоминания о встречах | В составе утренней сводки | | Создание встреч | По команде в Telegram или чате, с подтверждением | | Ответы на вопросы | В реальном времени через Telegram или чат ASCN | | Сортировка почты | По заданным приоритетам, без вашего участия | **Следующий шаг:** добавьте триггер на письма от важных людей — тогда агент будет уведомлять вас мгновенно, не дожидаясь утренней сводки. ```text theme={null} Когда приходит письмо от [имя клиента или коллеги], немедленно уведоми меня в Telegram с кратким содержанием. ``` # Инструкция для ИИ Source: https://docs.ascn.ai/router/ai-prompt Одна кнопка — и ваш ИИ-ассистент знает, как работать с ASCN Router. Интегрируете ASCN Router с помощью Cursor, Claude Code, ChatGPT или другого ИИ-ассистента? Скопируйте инструкцию ниже одной кнопкой (иконка копирования в правом верхнем углу блока) и вставьте в чат с ассистентом. Он получит всё нужное, чтобы написать рабочий код. ```text Инструкция для ИИ theme={null} You are integrating ASCN Router — an OpenAI-compatible API in front of models from OpenAI, Anthropic, Google, DeepSeek, xAI, Qwen, Mistral and others. CONNECTION - Base URL: https://b2b.api.ascn.ai/api/ai-gateway/v1 - Auth: send the API key in the header "X-API-KEY: ". Read the key from the env var ASCN_API_KEY. Never hard-code it or ship it to the client. - With the official OpenAI SDK, set base_url to the URL above, pass the key as api_key AND add it to default headers as X-API-KEY. Python: OpenAI(base_url=URL, api_key=key, default_headers={"X-API-KEY": key}) Node: new OpenAI({ baseURL: URL, apiKey: key, defaultHeaders: { "X-API-KEY": key } }) MODELS - Model names look like "vendor/model", e.g. "openai/gpt-4o-mini", "anthropic/claude-haiku-4.5", "deepseek/deepseek-v4-flash". - Get the live list from GET /v1/models. Each entry has id, kind (text | image | video | music | audio), context_length, input_modalities and pricing. Do not hard-code a model list. TEXT - POST /v1/chat/completions — standard OpenAI Chat Completions; tools, tool_choice, response_format, seed, stop etc. are forwarded to the model. - POST /v1/responses — OpenAI Responses API, but responses are NOT stored: previous_response_id is not supported, send the full history in input. - Use "stream": true for long answers; non-streamed long answers may fail with code streaming_required. - Reasoning models spend max_tokens on hidden reasoning: set max_tokens >= 2000 for them. MEDIA (images, video, music, speech) — asynchronous jobs 1. POST /v1/{images|videos|music|audio}/jobs with a model of that kind -> returns { id, status: "pending", estimated_cost }. 2. Poll GET /v1/{kind}/jobs/{id} every 3-5 s until status is "completed" or "failed". 3. Download each output[i].url (/v1/{kind}/jobs/{id}/content?index=N) with the same X-API-KEY header. Images/video are kept 7 days; download music/speech right away. - Images: model, prompt, size ("16:9", "1k", "WIDTHxHEIGHT"), input_images (for editing), output_format. - Video: model, prompt, duration, aspect_ratio, resolution, image_url (image-to-video), audio. - Music: model, prompt, lyrics, style, title, instrumental. - Audio: model, text + voice (speech), dialogue, audio_url (voice isolation). ERRORS - OpenAI error envelope plus status_code and request_id: {"error": {"message", "type", "code"}, "status_code", "request_id"}. - Retry 429 rate_limited (after Retry-After), 502 backend_error, 503. Do not retry 400/404 without changing the request. - 402 insufficient_balance: the max possible cost (prompt + max_tokens, 4096 if unset) is held before the request runs; set max_tokens when the balance is low. BILLING - Charged in USD, counted in micro-dollars (1 µ$ = $0.000001): input_tokens x input price + output_tokens x output price, prices per million tokens from GET /v1/models. Failed media jobs cost nothing. Full docs: https://docs.ascn.ai/llms-full.txt ``` ## Открыть страницу в ИИ На каждой странице документации справа от заголовка есть меню: можно скопировать страницу в Markdown или сразу открыть её в ChatGPT, Claude, Perplexity или Cursor. ## Вся документация одним файлом * [`/llms.txt`](/llms.txt) — краткий список страниц для ИИ. * [`/llms-full.txt`](/llms-full.txt) — вся документация в одном файле. Передайте ссылку ассистенту, если нужен полный контекст. # Ошибки Source: https://docs.ascn.ai/router/errors Формат ошибок и список кодов. Ошибки возвращаются в формате OpenAI с дополнительными полями `status_code` и `request_id`. Указывайте `request_id` при обращении в поддержку. ```json theme={null} { "error": { "message": "model \"x\" is not available", "type": "invalid_request_error", "code": "model_not_found" }, "status_code": 404, "request_id": "req_…" } ``` | HTTP | `code` | Значение | | - | - | - | | 400 | `model_required` | Тело не JSON или нет `model`. | | 400 | `invalid_request_error` | Модель отклонила запрос; причина в `message`. | | 400 | `context_length_exceeded` | Промпт с `max_tokens` превышает контекстное окно. | | 400 | `streaming_required` | Ответ слишком длинный — повторите с `"stream": true`. | | 400 | `unsupported_parameter`, `unsupported_value` | Модель не принимает параметр или значение. | | 400 | `content_policy_violation` | Модель отказалась обрабатывать контент. | | 400 | `wrong_endpoint` | Модель обслуживает другой эндпоинт; он указан в `message`. | | 402 | `insufficient_balance` | Недостаточно свободного баланса. В `meta` — `required_micro_usd`, `balance_micro_usd`, `held_micro_usd`. | | 404 | `model_not_found` | Модели нет в каталоге. | | 404 | `not_found` | Неизвестный эндпоинт. | | 404 | `job_not_found` | Нет такой задачи у этого аккаунта. | | 409 | `job_not_completed` | У задачи пока нет результата. | | 410 | `content_expired` | Срок хранения файла истёк. | | 413 | `request_too_large` | Слишком большое тело запроса. | | 429 | `rate_limited` | Слишком много запросов — повторите после `Retry-After`. | | 429 | `too_many_jobs` | Достигнут лимит одновременных медиа-задач. | | 502 | `backend_error` | Сбой бэкенда модели. Можно безопасно повторить. | | 503 | `no_provider_active` | Сервис временно недоступен. | | 503 | `model_unavailable` | Модель сейчас не может обслужить эту конфигурацию. | **Когда повторять:** `429` — после `Retry-After`; `502` — сразу или с небольшой задержкой; `503` — позже или с другой моделью. Ошибки `400` и `404` не повторяйте без изменения запроса. # FAQ Source: https://docs.ascn.ai/router/faq Ответы на частые вопросы об ASCN Router. Если `finish_reason` равен `length`, модели не хватило `max_tokens`. У рассуждающих моделей часть лимита уходит на скрытые рассуждения — задайте `max_tokens` от 2000. Перед запуском резервируется максимальная возможная стоимость: для текста — промпт плюс `max_tokens` (4096, если не задан). Суммы, зарезервированные другими запросами и задачами, тоже вычитаются. Задайте меньший `max_tokens` или посмотрите `meta` в ошибке. Ответ слишком длинный для обычного режима. Повторите запрос с `"stream": true`. Вы отправили модель не на тот эндпоинт — например, модель для картинок в `/v1/chat/completions`. Поле `kind` в каталоге показывает, куда отправлять модель, а `message` ошибки называет нужный эндпоинт. Возьмите цены модели из `GET /v1/models` и умножьте на количество токенов. Для медиа-задач прогноз приходит в `estimated_cost` сразу после запуска, а фактическая сумма — в `cost` после завершения. Медиа-задача, завершившаяся ошибкой, ничего не стоит. Недопустимые параметры отклоняются до списания. Текстовый запрос оплачивается по фактически потраченным токенам. Нет. Ответы не сохраняются, каждый запрос независим. Передавайте всю историю в `messages` или `input`. Актуальный список — всегда в `GET /v1/models`. Каталог меняется, поэтому не храните список в коде. `409 job_not_completed` — задача ещё не завершена. `410 content_expired` — истёк срок хранения (картинки и видео — 7 дней, музыку и речь скачивайте сразу). Также проверьте, что передаёте заголовок `X-API-KEY`. # Возможности моделей Source: https://docs.ascn.ai/router/features Картинки на входе, JSON-ответы, вызов инструментов, кэширование. Все поля протокола Chat Completions передаются модели как есть, а учитывает ли их модель, решает она сама. Перед использованием возможности проверьте модель в `GET /v1/models`. ## Изображения на входе Модели с `image` в `input_modalities` читают картинки, переданные в `messages`. Передайте `content` массивом частей: ```python theme={null} response = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{ "role": "user", "content": [ {"type": "text", "text": "Что на этой картинке?"}, {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}, ], }], ) ``` ## Структурированный ответ (JSON) Поле `response_format` передаётся модели без изменений. Модели, которые его поддерживают, вернут JSON по схеме: ```python theme={null} response = client.chat.completions.create( model="openai/gpt-4o-mini", messages=[{"role": "user", "content": "Назови столицу Франции и её население."}], response_format={ "type": "json_schema", "json_schema": { "name": "city", "schema": { "type": "object", "properties": { "city": {"type": "string"}, "population": {"type": "integer"}, }, "required": ["city", "population"], }, }, }, ) ``` Если модель не поддерживает `response_format`, API может вернуть `400 unsupported_parameter`, а модель — проигнорировать поле. В таком случае опишите нужный формат в промпте. ## Вызов инструментов: полный цикл Передайте их в `tools`. Если модель решит вызвать функцию, в ответе будет `finish_reason: "tool_calls"`. Возьмите имя и аргументы из `message.tool_calls`. Добавьте в историю ответ модели и сообщение с `role: "tool"` и тем же `tool_call_id`, затем отправьте запрос снова. ```python theme={null} import json tools = [{ "type": "function", "function": { "name": "get_weather", "description": "Current weather for a city.", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, }, }] messages = [{"role": "user", "content": "Какая погода в Берлине?"}] first = client.chat.completions.create(model="openai/gpt-4o-mini", messages=messages, tools=tools) call = first.choices[0].message.tool_calls[0] args = json.loads(call.function.arguments) result = {"city": args["city"], "temp_c": 18} # ваша функция messages.append(first.choices[0].message) messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)}) final = client.chat.completions.create(model="openai/gpt-4o-mini", messages=messages, tools=tools) print(final.choices[0].message.content) ``` ## Кэширование промпта Некоторые модели кэшируют повторяющийся промпт. Сколько токенов взято из кэша, видно в `usage.prompt_tokens_details.cached_tokens`. Если в каталоге для модели указан `cached_input_per_mtok`, такие токены оплачиваются по этой цене; если не указан — по обычной цене входа. Чтобы кэш срабатывал чаще, держите неизменную часть (системный промпт, инструкции, документы) в начале сообщений, а изменяющуюся — в конце. # Интеграции Source: https://docs.ascn.ai/router/integrations LangChain, Vercel AI SDK, LlamaIndex и HTTP-запросы. ASCN Router работает с любой библиотекой, где можно задать свой базовый URL для OpenAI и дополнительный заголовок `X-API-KEY`. Инструменты, в которых можно указать только URL и ключ, без своих заголовков, отправляют ключ в `Authorization`. Перед подключением такого инструмента проверьте, что запрос проходит. ## LangChain ```python Python theme={null} import os from langchain_openai import ChatOpenAI key = os.environ["ASCN_API_KEY"] llm = ChatOpenAI( model="anthropic/claude-haiku-4.5", base_url="https://b2b.api.ascn.ai/api/ai-gateway/v1", api_key=key, default_headers={"X-API-KEY": key}, ) print(llm.invoke("Hello!").content) ``` ```javascript Node.js theme={null} import { ChatOpenAI } from "@langchain/openai"; const key = process.env.ASCN_API_KEY; const llm = new ChatOpenAI({ model: "anthropic/claude-haiku-4.5", apiKey: key, configuration: { baseURL: "https://b2b.api.ascn.ai/api/ai-gateway/v1", defaultHeaders: { "X-API-KEY": key }, }, }); console.log((await llm.invoke("Hello!")).content); ``` ## Vercel AI SDK ```javascript theme={null} import { createOpenAICompatible } from "@ai-sdk/openai-compatible"; import { generateText } from "ai"; const ascn = createOpenAICompatible({ name: "ascn", baseURL: "https://b2b.api.ascn.ai/api/ai-gateway/v1", headers: { "X-API-KEY": process.env.ASCN_API_KEY }, }); const { text } = await generateText({ model: ascn("openai/gpt-4o-mini"), prompt: "Hello!", }); ``` ## LlamaIndex ```python theme={null} import os from llama_index.llms.openai_like import OpenAILike key = os.environ["ASCN_API_KEY"] llm = OpenAILike( model="deepseek/deepseek-v4-flash", api_base="https://b2b.api.ascn.ai/api/ai-gateway/v1", api_key=key, default_headers={"X-API-KEY": key}, is_chat_model=True, ) print(llm.complete("Hello!")) ``` ## HTTP-запрос без SDK В no-code инструментах (n8n, Make, Zapier) используйте обычный HTTP-узел: * **Метод:** `POST` * **URL:** `https://b2b.api.ascn.ai/api/ai-gateway/v1/chat/completions` * **Заголовки:** `X-API-KEY: <ключ>`, `Content-Type: application/json` * **Тело:** `{"model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}` Ответ модели лежит в `choices[0].message.content`. # Медиа-задачи Source: https://docs.ascn.ai/router/media Изображения, видео, музыка и речь через асинхронные задачи. Изображения, видео, музыка и речь генерируются через **задачи**, потому что рендер занимает от секунд до нескольких минут. `POST /v1/{images|videos|music|audio}/jobs` с моделью нужного типа. В ответе сразу приходят `id`, `status: "pending"` и `estimated_cost`. `GET /v1/{kind}/jobs/{id}` каждые 3–5 секунд, пока `status` не станет `completed` или `failed`. Задача выполняется, даже если вы перестали опрашивать. У каждого элемента `output` есть `url` (`…/v1/{kind}/jobs/{id}/content?index=N`). Файл отдаётся с тем же `X-API-KEY`, поддерживаются `Range`-запросы. | Тип | Время | Хранение | | - | - | - | | Изображения | Секунды — пара минут (4K до 5) | 7 дней | | Видео | 30 секунд — несколько минут | 7 дней | | Музыка | Несколько минут | Скачайте сразу | | Речь и звук | Зависит от модели | Скачайте сразу | Точный срок — в `expires_at`; после него вернётся `410 content_expired`. Одновременно можно запускать ограниченное число задач (`429 too_many_jobs`). ## Изображения `POST /v1/images/jobs` — генерация по тексту или редактирование, если переданы `input_images`. Одно изображение на задачу. | Поле | Описание | | - | - | | `model`, `prompt` | Обязательны. Промпт обычно до 5000 символов | | `size` | `1:1`, `16:9`, `1k`/`2k`/`4k`, `WIDTHxHEIGHT` или `auto` | | `input_images` | Референсы (https или `data:` URI), обычно до 10 | | `output_format` | `png` (по умолчанию), `jpeg`, `webp` | | `quality` | `standard`, `hd` | | `mj_task_id`, `mj_index` | Действия Midjourney | ## Видео `POST /v1/videos/jobs`. Режим определяется по входным данным: текст; `image_url` (+ `last_frame_url`) — изображение в видео; `reference_image_urls` / `video_urls` — по референсам; `video_url` + `image_url` — контроль движения. | Поле | Описание | | - | - | | `model`, `prompt` | Обязательны. Промпт до 10 000 символов | | `duration` | Секунды; у каждой модели свой набор (Veo 4/6/8, Kling 5/10, Seedance 4–15) | | `aspect_ratio` | `16:9` (по умолчанию), `9:16`, `1:1` и др. | | `resolution` | `480p`, `720p`, `1080p`, `4k` | | `audio` | Звуковая дорожка, где поддерживается (может повысить цену) | | `mode` | `standard`, `pro`, `master` | | `output_format` | `mp4` (по умолчанию), `mov`, `webm` | ## Музыка `POST /v1/music/jobs`. Только `prompt` — модель сама напишет текст и выберет стиль. Поля: `lyrics` (до 5000), `style` (до 1000), `title` (до 200), `instrumental`. Некоторые модели возвращают два трека по цене одного. ## Речь и звук `POST /v1/audio/jobs`. Синтез речи — `text` + `voice`; диалог — `dialogue` (реплики с `text` и `voice`); звуковые эффекты — `text` + `duration_seconds` (до 30); выделение голоса — `audio_url`. Дополнительно: `language_code`, `speed` (0.7–1.2), `stability`, `similarity_boost`. ## Пример ```python theme={null} import os, time, requests BASE = "https://b2b.api.ascn.ai/api/ai-gateway" HEADERS = {"X-API-KEY": os.environ["ASCN_API_KEY"]} job = requests.post(f"{BASE}/v1/images/jobs", headers=HEADERS, json={ "model": "google/nano-banana-2", "prompt": "A cozy cabin at sunrise, cinematic light", "size": "16:9", }).json() while job["status"] not in ("completed", "failed"): time.sleep(4) job = requests.get(f"{BASE}/v1/images/jobs/{job['id']}", headers=HEADERS).json() print(job["output"][0]["url"] if job["status"] == "completed" else job["error"]) ``` ## Ошибки задачи | `error.code` | Что делать | | - | - | | `content_moderation` | Переформулируйте промпт | | `input_rejected` | Поменяйте входной файл, см. `message` | | `invalid_request` | Исправьте поля по подсказке в `message` | | `generation_failed`, `job_expired` | Запустите новую задачу | Неудачная задача не оплачивается. Референсные файлы должны быть доступны по https без авторизации. # Переход с OpenAI Source: https://docs.ascn.ai/router/migration Перенос существующего кода на ASCN Router. ASCN Router говорит на протоколе OpenAI, поэтому существующий код обычно переносится заменой трёх вещей: базового URL, заголовка с ключом и имени модели. ## С OpenAI ```python Python theme={null} import os from openai import OpenAI # Было: # client = OpenAI(api_key=os.environ["OPENAI_API_KEY"]) # Стало: key = os.environ["ASCN_API_KEY"] client = OpenAI( base_url="https://b2b.api.ascn.ai/api/ai-gateway/v1", api_key=key, default_headers={"X-API-KEY": key}, ) response = client.chat.completions.create( model="openai/gpt-4o-mini", # было: "gpt-4o-mini" messages=[{"role": "user", "content": "Hello!"}], ) ``` ```javascript Node.js theme={null} import OpenAI from "openai"; // Было: // const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY }); // Стало: const key = process.env.ASCN_API_KEY; const client = new OpenAI({ baseURL: "https://b2b.api.ascn.ai/api/ai-gateway/v1", apiKey: key, defaultHeaders: { "X-API-KEY": key }, }); const response = await client.chat.completions.create({ model: "openai/gpt-4o-mini", // было: "gpt-4o-mini" messages: [{ role: "user", content: "Hello!" }], }); ``` ## С других OpenAI-совместимых шлюзов Если вы уже работаете через другой шлюз с именами моделей вида `vendor/model`, замените `base_url` и ключ как показано выше. Имена моделей сверьте с каталогом `GET /v1/models` — они могут отличаться. ## Чек-лист * **Базовый URL:** `https://b2b.api.ascn.ai/api/ai-gateway/v1`. * **Ключ:** в заголовке `X-API-KEY`. * **Модели:** с префиксом производителя, например `anthropic/claude-haiku-4.5`. Регистр и разделители не важны. * **Responses API:** ответы не хранятся, поэтому `previous_response_id` не работает — передавайте историю в `input`. * **Картинки, видео, речь:** вместо синхронных эндпоинтов OpenAI используются [медиа-задачи](/router/media). * **Рассуждающие модели:** задавайте `max_tokens` от 2000. # Модели и оплата Source: https://docs.ascn.ai/router/models Каталог моделей, цены и правила списаний. ## Каталог моделей `GET /v1/models` — живой каталог. Каждая запись содержит имя модели, контекстное окно, принимаемые входные данные и **вашу** цену. `GET /v1/models/{model}` возвращает одну запись. Каталог меняется: модели добавляются и выводятся из эксплуатации. Читайте его из API, а не храните список в коде. Имя модели имеет вид `vendor/model`, например `openai/gpt-4o-mini`. Регистр и разделители не важны: `anthropic/claude-haiku-4.5` и `anthropic/claude-haiku-4-5` — одна и та же модель. Значение для поля `model`. Отображаемое имя. Производитель модели. `text` — обслуживается `/v1/chat/completions` и `/v1/responses`; `image`, `video`, `music`, `audio` — соответствующим `/v1/{kind}/jobs`. Контекстное окно в токенах (промпт плюс ответ). Максимальная длина ответа, если известна. `text`, `image`, `audio`, `video`, `file`. Ваша цена в USD. Для текста — `input_per_mtok`, `output_per_mtok` и `cached_input_per_mtok` (за миллион токенов). Для медиа — `unit` (`image`, `video`, `second`, `request`, `1k_characters`) и `per_unit` для самой дешёвой конфигурации. Поля без данных не передаются, а не заполняются нулями. ```bash theme={null} curl https://b2b.api.ascn.ai/api/ai-gateway/v1/models \ -H "X-API-KEY: $ASCN_API_KEY" ``` ## Стоимость Запросы оплачиваются в долларах США и учитываются в микродолларах: 1 µ$=$0,000001. **Текст:** ```text theme={null} input_tokens × цена входа + output_tokens × цена выхода ``` * Цена за миллион токенов численно равна цене одного токена в µ\$. * Токены берутся из отчёта `usage` модели и возвращаются вам без изменений. * Минимум 1 µ\$ за запрос с токенами; итог округляется вверх. * Скрытые токены рассуждений оплачиваются как выходные. **Медиа:** задача оплачивается один раз при завершении — сумма в поле `cost`. `estimated_cost` — прогноз на момент запуска. Длительность, разрешение, звук и уровень качества повышают цену. Неудачная задача ничего не стоит. ## Резервирование средств Перед запуском максимальная возможная стоимость резервируется на балансе, чтобы параллельные запросы не потратили больше, чем есть на счёте. * **Текст** — промпт плюс `max_tokens` ответа (4096, если не задан). После завершения резерв заменяется фактической стоимостью. * **Медиа** — стоимость задачи. При первом использовании конфигурации (новая модель, первый 4K-клип) резерв берётся с запасом. Резерв неудачной задачи освобождается сразу. Если резерв не помещается в свободный баланс, запрос отклоняется с `402 insufficient_balance` до начала работы. В `meta` — `required_micro_usd`, `balance_micro_usd`, `held_micro_usd`. При небольшом балансе всегда задавайте `max_tokens`. ## Модели с рассуждениями o-серия, DeepSeek R1 и thinking-варианты, Gemini Pro и Claude в режиме thinking тратят часть `max_tokens` на скрытые рассуждения. Задавайте им `max_tokens` от 2000, иначе ответ может оборваться с `finish_reason: "length"`. # ASCN Router Source: https://docs.ascn.ai/router/overview Единый OpenAI-совместимый API для сотен языковых и медиа-моделей. ASCN Router — это один OpenAI-совместимый API, за которым стоят модели OpenAI, Anthropic, Google, DeepSeek, xAI, Qwen, Mistral и многих других. Подключите любой OpenAI SDK, выберите модель из `GET /v1/models` и отправляйте запросы по уже знакомому протоколу. Пишете код с ИИ-ассистентом? Скопируйте [инструкцию для ИИ](/router/ai-prompt) одной кнопкой и вставьте в чат. Chat Completions и Responses API, потоковый вывод, вызов инструментов. Изображения, видео, музыка и речь через асинхронные задачи. Живой каталог моделей с вашими ценами и правила списаний. Формат ошибок и что делать с каждой. ## Базовый URL ```text theme={null} https://b2b.api.ascn.ai/api/ai-gateway ``` Все эндпоинты начинаются с `/v1`. Для OpenAI SDK укажите `base_url` вместе с `/v1`. ## Аутентификация Каждый запрос должен содержать ключ API вашего аккаунта в заголовке `X-API-KEY`. Тот же заголовок нужен для скачивания файлов медиа-задач. ```http theme={null} X-API-KEY: <ваш_ключ> ``` OpenAI SDK по умолчанию отправляет ключ в заголовке `Authorization`, поэтому добавьте `X-API-KEY` через дополнительные заголовки клиента (см. примеры ниже). Храните ключ на сервере. Не вставляйте его в клиентский код и не коммитьте в репозиторий. ## Быстрый старт ```bash cURL theme={null} curl https://b2b.api.ascn.ai/api/ai-gateway/v1/chat/completions \ -H "X-API-KEY: $ASCN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek/deepseek-v4-flash", "messages": [{"role": "user", "content": "What is 1+1? Answer with a single number."}] }' ``` ```python Python theme={null} import os from openai import OpenAI key = os.environ["ASCN_API_KEY"] client = OpenAI( base_url="https://b2b.api.ascn.ai/api/ai-gateway/v1", api_key=key, default_headers={"X-API-KEY": key}, ) response = client.chat.completions.create( model="deepseek/deepseek-v4-flash", messages=[{"role": "user", "content": "What is 1+1? Answer with a single number."}], ) print(response.choices[0].message.content) ``` ```javascript Node.js theme={null} import OpenAI from "openai"; const key = process.env.ASCN_API_KEY; const client = new OpenAI({ baseURL: "https://b2b.api.ascn.ai/api/ai-gateway/v1", apiKey: key, defaultHeaders: { "X-API-KEY": key }, }); const response = await client.chat.completions.create({ model: "deepseek/deepseek-v4-flash", messages: [{ role: "user", content: "What is 1+1? Answer with a single number." }], }); console.log(response.choices[0].message.content); ``` ## Эндпоинты | Метод | Путь | Назначение | | - | - | - | | `POST` | `/v1/chat/completions` | Текст, протокол Chat Completions | | `POST` | `/v1/responses` | Текст, протокол Responses | | `GET` | `/v1/models`, `/v1/models/{model}` | Каталог моделей с вашими ценами | | `POST` | `/v1/{images\|videos\|music\|audio}/jobs` | Запуск медиа-задачи | | `GET` | `/v1/{kind}/jobs/{id}` | Статус задачи | | `GET` | `/v1/{kind}/jobs/{id}/content` | Скачивание результата | Каждый ответ содержит заголовок `X-Request-ID` — указывайте его при обращении в поддержку. # Генерация текста Source: https://docs.ascn.ai/router/text Chat Completions, Responses и потоковый вывод. Для текста доступны два протокола OpenAI. Используйте модели с `kind: text` из `GET /v1/models`. ## Chat Completions ```http theme={null} POST /v1/chat/completions ``` Каждое поле протокола передаётся модели как есть — `tools`, `tool_choice`, `response_format`, `logprobs`, `seed`, `stop` и остальные. Учитывает ли модель поле, решает сама модель. `id` модели, например `deepseek/deepseek-v4-flash`. История диалога. `role`: `system`, `developer`, `user`, `assistant` или `tool`. `content`: текст или массив частей (`text`, `image_url`, …). Лимит выходных токенов, включая рассуждения. От 0 до 2. `minimal`, `low`, `medium` или `high`. `none`, `auto`, `required` или выбор конкретного инструмента. Ответ — стандартный объект `chat.completion` с `choices` (`message`, `finish_reason`: `stop`, `length`, `tool_calls`, `content_filter`) и `usage`. `completion_tokens` включает скрытые токены рассуждений. ```bash Вызов инструментов theme={null} curl https://b2b.api.ascn.ai/api/ai-gateway/v1/chat/completions \ -H "X-API-KEY: $ASCN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "openai/gpt-4o-mini", "messages": [{"role": "user", "content": "What is the weather in Berlin?"}], "tools": [{ "type": "function", "function": { "name": "get_weather", "description": "Current weather for a city.", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]} } }] }' ``` ## Responses ```http theme={null} POST /v1/responses ``` Для кода, написанного под `client.responses.create`. Обязательные поля — `model` и `input` (строка или массив сообщений); также `instructions`, `max_output_tokens`, `temperature`, `tools`, `stream`. Ответы не сохраняются. `previous_response_id` и получение ответа позже не поддерживаются — передавайте всю историю в `input`. ```python theme={null} response = client.responses.create( model="openai/gpt-4o-mini", input="Summarise the CAP theorem in three bullets.", max_output_tokens=400, ) print(response.output_text) ``` ## Потоковый вывод Передайте `"stream": true`, чтобы получать ответ через Server-Sent Events. Поток заканчивается `data: [DONE]`. * **Chat Completions** — `stream_options.include_usage` включён всегда, последний чанк содержит `usage`. * **Responses** — события `response.output_text.delta`, …, `response.completed`; `usage` — в `response.completed`. Используйте поток для длинных ответов. Длинный ответ без потока может быть отклонён с `streaming_required`. ```python theme={null} stream = client.chat.completions.create( model="anthropic/claude-haiku-4.5", max_tokens=1024, messages=[{"role": "user", "content": "Explain mixture-of-experts in one paragraph."}], stream=True, ) for chunk in stream: if chunk.choices and chunk.choices[0].delta.content: print(chunk.choices[0].delta.content, end="") ``` Уже начавшийся поток не переключается на другой бэкенд. При сбое посреди ответа поток завершится чанком `data: {"error": {…}}` и затем `data: [DONE]` — считайте полученное неполным ответом. # API Source: https://docs.ascn.ai/settings/api Подключите внешние системы к агенту через API. ASCN Agent предоставляет API для интеграции с внешними системами: запускайте беседы, отправляйте сообщения и получайте ответы программно. Раздел Настройки → API — Base URL, ключ авторизации и пример запроса ## Как получить доступ к API 1. Откройте **Настройки → API** 2. Скопируйте **Base URL** — он уникален для каждого воркспейса 3. Скопируйте **Ключ авторизации** 4. Используйте ключ в заголовке `Authorization: Bearer ...` с каждым запросом ## Базовый пример ```bash theme={null} curl -X POST "https://api.clawman.ascn.ai/api/v1/workspaces/{workspace_id}/session/{session_id}/messages" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {API_KEY}" \ -d '{"content": "Проверь почту и пришли сводку"}' ``` ## Методы API | Метод | Эндпоинт | Описание | | - | - | - | | `POST` | `/session/{session_id}/messages` | Отправить сообщение и получить стриминг ответа | **Что такое session\_id:** каждый разговор с агентом — это сессия. `session_id` — уникальный идентификатор конкретного диалога. Вы можете создать новую сессию (новый диалог) или продолжить существующую, передав её ID. Если хотите каждый раз начинать новый разговор — генерируйте новый UUID для `session_id`. ## Сценарии использования **Интеграция с вашим приложением.** Отправляйте задачи агенту из своего продукта и получайте результаты через API. **Связь нескольких агентов.** Прямой связи между агентами нет, но вы можете использовать API как мост — один агент отправляет данные другому через API-запрос. **Вебхуки и автоматизации.** Подключите ASCN Agent к Zapier, Make или собственным скриптам через API. Base URL и ключ авторизации привязаны к конкретному воркспейсу. Для каждого агента они свои. # Опасная зона Source: https://docs.ascn.ai/settings/delete-agent Перезапуск агента и удаление воркспейса. В разделе **Настройки → Опасная зона** два действия: перезапуск агента и удаление воркспейса. Настройки → Опасная зона *** ## Перезапустить Перезапускает процесс агента. Все активные сессии будут прерваны, но данные, настройки и задачи сохраняются. Используйте если агент завис, ведёт себя неожиданно или не отвечает. **Как перезапустить:** 1. Откройте **Настройки → Опасная зона** 2. Нажмите **Перезапустить** *** ## Удалить воркспейс Полное и необратимое удаление агента. Восстановить данные после невозможно. ### Что будет удалено * Все беседы и история чатов * Настройки Мозга: интеграции, скиллы, база знаний, память * Задачи и триггеры * Подключённые каналы (Telegram-бот, Slack) * Файлы, созданные агентом * Секреты и ключи агента Перед удалением сохраните всё, что хотите сохранить: скопируйте содержимое IDENTITY.md, SOUL.md и других файлов базы знаний. ### Как удалить воркспейс 1. Откройте **Настройки → Опасная зона** 2. Нажмите **Удалить воркспейс** 3. Подтвердите действие *** ## Альтернативы удалению Если хотите начать заново, но сохранить часть настроек: * **Отредактируйте IDENTITY.md / SOUL.md** — обновите роль и характер без пересоздания * **Отключите ненужные интеграции** — уберите доступ к сервисам, которые больше не нужны * **Удалите конкретные задачи** — через раздел **Задачи** Полное удаление имеет смысл только если хотите стереть всю историю и начать с чистого листа. # Разрешения инструментов Source: https://docs.ascn.ai/settings/permissions Управляйте тем, что агент может делать с файлами в воркспейсе. **Разрешения инструментов** — это переключатели, которые определяют, может ли агент изменять или удалять файлы в **воркспейсе** (изолированная файловая среда вашего агента, где хранятся его данные и файлы). Раздел Настройки → Разрешения инструментов ## Доступные разрешения | Разрешение | Описание | | - | - | | **Разрешить изменение файлов** | Агент может создавать и изменять файлы в воркспейсе | | **Разрешить удаление файлов** | Агент может безвозвратно удалять файлы из воркспейса | ## Рекомендации Если агент не должен самостоятельно менять файлы — отключите «Разрешить изменение файлов». Агент будет предлагать изменения, но применять их только вы. * Разрешение удаления файлов стоит включать только если агент явно должен этим заниматься (например, очищать временные файлы по расписанию) * Для агентов, которые только читают и отвечают на вопросы, оба разрешения можно оставить выключенными # Секреты и ключи Source: https://docs.ascn.ai/settings/secrets Безопасное хранение токенов и API-ключей для внешних сервисов. **Секреты** — это переменные окружения для безопасного хранения токенов, API-ключей и других учётных данных. Агент использует их при обращении к внешним сервисам, и они никогда не отображаются в открытом виде. Раздел Настройки → Секреты и ключи ## Когда нужны секреты Секреты нужны, если вы подключаете собственные API или сервисы, которые требуют ключей авторизации. Например: * API-ключ стороннего сервиса * Токен корпоративного Slack или другого инструмента * Ключи для вебхуков и интеграций Стандартные коннекторы (Gmail, Google Calendar, Slack и др.) авторизуются через OAuth — секреты для них добавлять не нужно. ## Как добавить секрет 1. Откройте **Настройки → Секреты и ключи** 2. Нажмите **+ Добавить секрет** 3. Введите **название** (например, `API_KEY`) и **значение** — токен или ключ 4. Сохраните ## Как использовать секрет После добавления секрет доступен агенту как переменная окружения по его названию. Укажите название в описании задачи или скилла: ``` При обращении к API используй ключ из переменной MY_API_KEY. ``` ## Безопасность * Значения секретов зашифрованы и не отображаются в интерфейсе после сохранения * Секреты не попадают в историю чатов и логи * Удалить секрет можно в любой момент через **Настройки → Секреты и ключи** # Задачи по расписанию Source: https://docs.ascn.ai/tasks/scheduled Настройте агента на автоматическое выполнение задач в заданное время. **Задача по расписанию** — это сценарий, который агент выполняет сам в нужное время, без вашего участия. Создаются через чат: просто опишите, что и когда нужно делать. ## Как создать задачу Напишите агенту в чате: ``` Каждое утро в 8:00 делай сводку непрочитанных писем в Gmail и отправляй мне в Telegram. ``` ``` Каждый понедельник в 9:00 проверяй мой Google Calendar и присылай план встреч на неделю. ``` ``` Каждую пятницу в 17:00 спрашивай, что я успел сделать за неделю, и фиксируй ответ в файл weekly_log.md. ``` Агент создаст задачу, подтвердит расписание и начнёт выполнять её автоматически. ## Поддерживаемые форматы расписания | Формат | Пример | | - | - | | Каждые N минут / часов | Каждые 30 минут | | Ежедневно в определённое время | Каждый день в 09:00 | | По дням недели | Каждый понедельник и пятницу | | В конкретное время | В 18:00 по московскому времени | ## Управление задачами Просмотреть все задачи можно в разделе **Задачи**. Каждая задача показывает расписание, статус (**Активна** / **Пауза**) и кнопки управления: **Редактировать**, **Детали** и удалить. Раздел «Задачи» — список с расписанием и статусами Чтобы изменить или остановить задачу, скажите агенту: ``` Отмени задачу утренней сводки. ``` ``` Измени время утренней сводки на 9:30. ``` ## Расход кредитов Каждое выполнение задачи по расписанию расходует кредиты сообщений. Если задача обращается к внешним сервисам (Gmail, Google Calendar и др.) — также тратятся интеграционные кредиты. Задачи по расписанию расходуют кредиты предсказуемо — вы точно знаете, сколько раз в день агент будет запускаться. Для частых проверок рассмотрите оптимальный интервал: раз в час вместо каждые 15 минут. ## Примеры полезных задач **Утренняя почтовая сводка:** ``` Каждый день в 8:00 читай непрочитанные письма в Gmail, выдели важные (с вопросами ко мне или дедлайнами) и пришли краткое резюме в Telegram. ``` **Напоминание о встречах:** ``` Каждый день в 8:30 смотри мой Google Calendar на сегодня и отправляй список встреч с временем и названиями. ``` **Еженедельный отчёт:** ``` Каждую пятницу в 17:00 спроси меня, что было сделано за неделю, запиши ответ в файл weekly_report_[дата].md. ``` # Триггеры по событиям Source: https://docs.ascn.ai/tasks/triggers Агент реагирует на события в ваших сервисах — новые письма, встречи, файлы. **Триггер** — это условие, при наступлении которого агент автоматически выполняет заданное действие. В отличие от расписания, триггер не привязан ко времени — он срабатывает в момент события. ## Доступные триггеры | Сервис | Событие | | - | - | | **Gmail** | Новое входящее письмо | | **Google Calendar** | Создание события | | **Google Calendar** | Изменение события | | **Google Calendar** | Удаление события | | **Google Drive** | Добавление нового файла | | **Google Drive** | Изменение существующего файла | ## Как создать триггер Опишите условие и реакцию в чате: ```text theme={null} Когда приходит новое письмо в Gmail, проверь, нужен ли ответ, и если да — подготовь черновик и пришли мне на утверждение в Telegram. ``` ```text theme={null} Когда в Google Calendar создаётся новая встреча, пришли мне в Telegram краткое резюме: кто, когда, зачем. ``` ```text theme={null} Когда в Google Drive появляется новый файл в папке «Входящие от клиентов», проверь формат и уведоми меня. ``` ## Управление триггерами Просмотреть и отключить активные триггеры можно в разделе **Задачи**. Чтобы остановить триггер, скажите агенту: ```text theme={null} Отключи триггер на новые письма в Gmail. ``` ## Расход кредитов Триггеры расходуют интеграционные кредиты при каждом срабатывании. Если в вашей почте много входящих, триггер на каждое новое письмо может расходовать кредиты значительно быстрее, чем задача по расписанию. **Совет:** если важна не мгновенная реакция, а регулярная проверка, используйте [задачу по расписанию](/tasks/scheduled) — это предсказуемее по расходу кредитов. ## Пример: триггер + расписание Комбинация работает эффективнее, чем каждый инструмент по отдельности: * **Триггер** на новые письма от VIP-клиентов → мгновенное уведомление в Telegram * **Расписание** в 8:00 → сводка всей остальной почты за ночь Так вы получаете срочное сразу, а остальное — в удобное время.