Амма — AI-ассистент amoCRM. Пользователь общается с ней в системе.
Интеграция может расширить возможности Аммы собственным агентом. Агент — это помощник с собственным характером и набором инструментов, который работает внутри Аммы. Пользователь выбирает агента в чате, либо Амма сама предлагает его подключить.
Инструменты агента интеграция реализует на своей стороне — в виде MCP-сервера. Агент умеет ровно то, что умеет ваш MCP-сервер: других инструментов у него нет.
Например, интеграция с сервисом онлайн-записи заводит агента, который проверяет записи клиента и подсказывает свободные слоты. Пользователь спрашивает у Аммы "когда записан этот клиент?", Амма предлагает подключить агента, тот вызывает инструменты вашего MCP-сервера и отвечает пользователю в том же чате.
Агента создаёт ваша интеграция. У агента есть следующие свойства:
Свойства агента и их типы приведены в статье Методы API агентов.
Обратите внимание на разницу между описанием и инструкциями для Аммы. Описание читает пользователь — оно объясняет, чем агент полезен. Инструкции для Аммы читает сама Амма, когда решает, кому передать запрос. Перечислите в них задачи агента и примеры вопросов, при которых его нужно подключать. Если инструкции не заданы, Амма принимает решение по описанию.
Агента можно подключить к разговору двумя способами:
Ответ агента пользователь получает напрямую в чате. Пока агент работает или ждёт ответа на уточняющий вопрос, сообщения пользователя уходят агенту.
Разговор с агентом идёт в том же чате, поэтому после работы агента пользователь продолжает диалог с Аммой, не теряя контекст.
Системный промпт определяет, как агент себя ведёт, поэтому от него напрямую зависит и польза агента, и его безопасность.
Что учесть при написании системного промпта:
У названия, описания, инструкций для Аммы и системного промпта есть лимиты по длине — они указаны в параметрах запроса метода добавления агентов.
Для работы с агентами в настройках интеграции необходимо указать scope – Амма, но доступно это только в техническом аккаунте. Подробнее о доступах — в статье Разрешения и доступы.
Инструменты агента — это инструменты вашего MCP-сервера, адрес которого вы указываете при создании агента. Поддерживаются транспорты streamable-http и sse.
Требования к адресу:
https;Адрес проверяется при создании и изменении агента, а также перед каждым запуском агента. Если адрес не соответствует требованиям, метод вернёт ошибку 400, и агент не будет создан или изменён.
Отдельной схемы авторизации у MCP-сервера нет. Вместе с адресом передайте произвольные заголовки — amoCRM будет отправлять их в каждом запросе к вашему серверу. Так вы реализуете любую схему авторизации, например ключ партнёра в собственном заголовке.
Поверх заголовков, которые задаются при создании агента, amoCRM добавляет в каждый запрос к MCP-серверу служебные заголовки.
| Заголовок | Описание |
|---|---|
| X-Account-Id | ID аккаунта amoCRM, в котором запущен агент |
| X-User-Id | ID пользователя amoCRM, который ведёт диалог с агентом |
| X-Context | Экран amoCRM, из которого пользователь обратился к агенту. Формат описан ниже |
Пример заголовков запроса к MCP-серверу, если при создании агента был передан заголовок X-Partner-Key:
X-Partner-Key: ваш ключ
X-Account-Id: 29857837
X-User-Id: 9876543
X-Context: {"entity_type":"leads","entity_id":789}Заголовки X-Account-Id, X-User-Id и X-Context зарезервированы: amoCRM подставляет их сама, одноимённые значения из mcp[headers] игнорируются. Те же данные агент получает в системном промпте и может подставлять их в параметры инструментов.
Значение заголовка — JSON-объект. Если раздел определить не удалось, заголовок не передаётся.
| Поле | Тип | Наличие | Описание |
|---|---|---|---|
| entity_type | string | Всегда | Раздел amoCRM, в котором находится пользователь. Значения — ниже |
| entity_id | integer | Только в карточке сделки и в конструкторе Salesbot | ID сделки или ID Salesbot |
Возможные значения entity_type:
| Значение | Раздел | entity_id | Пример значения заголовка |
|---|---|---|---|
dashboard |
Рабочий стол | Отсутствует | {"entity_type":"dashboard"} |
leads |
Карточка сделки | ID сделки | {"entity_type":"leads","entity_id":789} |
salesbot |
Конструктор Salesbot | ID Salesbot | {"entity_type":"salesbot","entity_id":42} |
400.Администратор видит всех агентов аккаунта, в том числе выключенных, и может включить или выключить любого из них.
Выключенный агент сразу становится недоступным: запустить его нельзя, и Амма больше не передаёт ему запросы. Из списка агентов в чате он не исчезает — остаётся в нём помеченным как недоступный. Сам агент сохраняется, его можно включить обратно.
Удалить агента администратор аккаунта не может — удаление доступно только интеграции, которая его создала.
При отключении интеграции в аккаунте все её агенты удаляются. От интеграции для этого ничего не требуется.
Если интеграцию установят в аккаунте повторно, агентов нужно создать заново.