Возможности

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

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

Инструменты агента интеграция реализует на своей стороне — в виде 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.
  • Выключенные агенты учитываются в лимитах наравне с активными. Чтобы освободить место, агента нужно удалить.
  • Агенты работают только в аккаунтах, где доступна Амма.
  • Массовое удаление агентов не поддерживается – агенты удаляются по одному.

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

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

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

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

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

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

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