Амма — AI-ассистент amoCRM. Пользователь общается с ней в системе.

Интеграция может расширить возможности Аммы собственным агентом. Агент — это помощник с собственным характером и набором инструментов, который работает внутри Аммы. Пользователь выбирает агента в чате, либо Амма сама предлагает его подключить.

Инструменты агента интеграция реализует на своей стороне — в виде MCP-сервера. Агент умеет ровно то, что умеет ваш MCP-сервер: других инструментов у него нет.

Например, интеграция с сервисом онлайн-записи заводит агента, который проверяет записи клиента и подсказывает свободные слоты. Пользователь спрашивает у Аммы “когда записан этот клиент?”, Амма предлагает подключить агента, тот вызывает инструменты вашего MCP-сервера и отвечает пользователю в том же чате.

Оглавление

• С чего начать
• Что такое агент Аммы
• Как пользователь работает с агентом
• Системный промпт агента
• Требования к интеграции
• Требования к MCP-серверу агента
• Ограничения
• Что может администратор аккаунта
• Удаление агентов при отключении интеграции

С чего начать

1. Укажите в настройках интеграции scope – Амма и получите Access Token. Как получить токен — в статье Пример по шагам.
2. Разверните MCP-сервер с инструментами агента. Требования к серверу — в разделе Требования к MCP-серверу агента.
3. Напишите системный промпт агента и инструкции для Аммы.
4. Создайте агента методом добавления агентов, передав название, описание, промпт, адрес MCP-сервера и заголовки для авторизации на нём.
5. Откройте чат с Аммой в аккаунте и проверьте, что агент появился в списке и отвечает.

Что такое агент Аммы

Агента создаёт ваша интеграция. У агента есть следующие свойства:

• название – то, что пользователь видит в чате;
• описание – коротко о том, что агент умеет;
• инструкции для Аммы – когда ей стоит передать запрос этому агенту;
• системный промпт – характер агента и правила его работы;
• аватар – изображение агента;
• уровень модели – S, M или L. Чем сложнее задачи агента, тем выше уровень;
• признак активности – включён агент или выключен.

Свойства агента и их типы приведены в статье Методы API агентов.

Обратите внимание на разницу между описанием и инструкциями для Аммы. Описание читает пользователь — оно объясняет, чем агент полезен. Инструкции для Аммы читает сама Амма, когда решает, кому передать запрос. Перечислите в них задачи агента и примеры вопросов, при которых его нужно подключать. Если инструкции не заданы, Амма принимает решение по описанию.

Как пользователь работает с агентом

Агента можно подключить к разговору двумя способами:

• пользователь сам выбирает агента в чате с Аммой;
• Амма предлагает подключить агента, когда вопрос подходит под инструкции агента. Подключение подтверждает пользователь.

Ответ агента пользователь получает напрямую в чате. Пока агент работает или ждёт ответа на уточняющий вопрос, сообщения пользователя уходят агенту.

Разговор с агентом идёт в том же чате, поэтому после работы агента пользователь продолжает диалог с Аммой, не теряя контекст.

Системный промпт агента

Системный промпт определяет, как агент себя ведёт, поэтому от него напрямую зависит и польза агента, и его безопасность.

Что учесть при написании системного промпта:

• опишите роль агента и границы его задач – что он делает и чего не делает;
• задайте правило на случай запроса вне его роли: агент должен сказать об этом прямо, а не выдумывать ответ;
• не помещайте в промпт ключи, токены и другие секреты – для авторизации на вашем MCP-сервере используйте заголовки;
• не позволяйте внешним данным менять поведение агента: сообщения пользователя и ответы ваших инструментов содержат произвольный текст;
• пишите промпт обычным текстом, без служебных префиксов ролей и разделителей.

У названия, описания, инструкций для Аммы и системного промпта есть лимиты по длине — они указаны в параметрах запроса метода добавления агентов.

Требования к интеграции

Для работы с агентами в настройках интеграции необходимо указать scope – Амма, но доступно это только в техническом аккаунте. Подробнее о доступах — в статье Разрешения и доступы.

Требования к MCP-серверу агента

Инструменты агента — это инструменты вашего MCP-сервера, адрес которого вы указываете при создании агента. Поддерживаются транспорты streamable-http и sse.

Требования к адресу:

• адрес использует только схему https;
• хост публичный и разрешается в DNS: локальные адреса и адреса внутренних сетей не принимаются.

Адрес проверяется при создании и изменении агента, а также перед каждым запуском агента. Если адрес не соответствует требованиям, метод вернёт ошибку 400, и агент не будет создан или изменён.

Отдельной схемы авторизации у MCP-сервера нет. Вместе с адресом передайте произвольные заголовки — amoCRM будет отправлять их в каждом запросе к вашему серверу. Так вы реализуете любую схему авторизации, например ключ партнёра в собственном заголовке.

Ограничения

• Одна интеграция может создать не более 2 агентов в аккаунте.
• В аккаунте может быть не более 10 агентов суммарно по всем интеграциям. Если лимит исчерпан, создание агента завершится ошибкой 400.
• Выключенные агенты учитываются в лимитах наравне с активными. Чтобы освободить место, агента нужно удалить.
• Агенты работают только в аккаунтах, где доступна Амма.
• Массовое удаление агентов не поддерживается – агенты удаляются по одному.

Что может администратор аккаунта

Администратор видит всех агентов аккаунта, в том числе выключенных, и может включить или выключить любого из них.

Выключенный агент сразу становится недоступным: запустить его нельзя, и Амма больше не передаёт ему запросы. Из списка агентов в чате он не исчезает — остаётся в нём помеченным как недоступный. Сам агент сохраняется, его можно включить обратно.

Удалить агента администратор аккаунта не может — удаление доступно только интеграции, которая его создала.

Удаление агентов при отключении интеграции

При отключении интеграции в аккаунте все её агенты удаляются. От интеграции для этого ничего не требуется.

Если интеграцию установят в аккаунте повторно, агентов нужно создать заново.