В данном разделе описываются доступные методы для работы с агентами Аммы.

Через методы API агентов интеграция может создавать своих агентов в аккаунте, получать список агентов, изменять их параметры, а также удалять их из аккаунта. О том, что такое агенты Аммы и как с ними работать в аккаунте, читайте в статье Возможности агентов Аммы.

Интеграция идентифицируется посредством проверки переданного Access Token в заголовке Authorization: Bearer ACCESS_TOKEN.

Оглавление

• Требования к работе с API агентов
• Добавление агентов
• Список агентов
• Получение агента по ID
• Редактирование агента
• Удаление агента
• Формат ошибок

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

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

Работа с агентами доступна в аккаунтах, где доступна Амма. Если на аккаунте Амма недоступна, любой метод API агентов вернёт ошибку 402.

Лимиты:

• не более 2 агентов от одной интеграции в аккаунте;
• не более 10 агентов в аккаунте суммарно по всем интеграциям;
• выключенные агенты учитываются в лимитах наравне с активными.

Добавление агентов

Метод

POST /api/v4/amma/agents

Описание

Метод позволяет добавлять агентов в аккаунт пакетно.

При создании агента проверяется корректность адреса MCP-сервера. Требования к адресу описаны в статье Возможности агентов Аммы.

Ограничения

Метод доступен только интеграциям.
Метод доступен интеграциям, у которых установлен scope – Амма.
Одна интеграция может создать не более 2 агентов в аккаунте.
В аккаунте может быть не более 10 агентов суммарно по всем интеграциям.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Метод принимает массив агентов. Обязательные поля – name, description, system_prompt и mcp[url].

Требования к изображению в avatar: размер до 2 МБ, MIME-тип image/*. Ссылка должна использовать схему https, а её хост – быть публичным, как и адрес MCP-сервера. Изображение загружается в amoCRM, поэтому в ответе возвращается ссылка на файл в amoCRM, а не исходная ссылка.

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

Агенты создаются целиком: если хотя бы один агент из массива не прошёл проверку, ни один агент не будет создан.

Если тело запроса не прошло валидацию, метод вернёт ошибку 400.

Пример запроса

[
  {
    "name": "Помощник по записям",
    "description": "Проверяет записи клиентов и подсказывает свободные слоты",
    "ai_instructions": "Передавай этому агенту вопросы о записи клиента, расписании и свободных слотах",
    "system_prompt": "Ты — ассистент по онлайн-записи. Помогаешь проверить запись клиента и найти свободное время.",
    "avatar": "https://cdn.partner.com/agents/booking.png",
    "model_size": "M",
    "mcp": {
      "url": "https://mcp.partner.com/booking",
      "transport": "streamable-http",
      "headers": {
        "X-Partner-Key": "ваш ключ"
      }
    },
    "is_active": true
  }
]

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Параметры ответа

Метод возвращает коллекцию созданных агентов.

Пример ответа

{
  "_total_items": 1,
  "_embedded": {
    "agents": [
      {
        "id": "b1f2c3d4-0000-4a5b-8c9d-000000000001",
        "name": "Помощник по записям",
        "description": "Проверяет записи клиентов и подсказывает свободные слоты",
        "system_prompt": "Ты — ассистент по онлайн-записи. Помогаешь проверить запись клиента и найти свободное время.",
        "ai_instructions": "Передавай этому агенту вопросы о записи клиента, расписании и свободных слотах",
        "avatar": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/avatar.png",
        "model_size": "M",
        "mcp": {
          "url": "https://mcp.partner.com/booking",
          "transport": "streamable-http",
          "has_headers": true
        },
        "is_active": true,
        "client_uuid": "a0c11111-2222-4333-8444-555566667777",
        "created_by": 123456,
        "created_at": 1753305600,
        "updated_at": 1753305600,
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/amma/agents/b1f2c3d4-0000-4a5b-8c9d-000000000001"
          }
        }
      }
    ]
  }
}

Список агентов

Метод

GET /api/v4/amma/agents

Описание

Метод позволяет получить список агентов, созданных вашей интеграцией.

Ограничения

Метод доступен только интеграциям.
Метод доступен интеграциям, у которых установлен scope – Амма.

GET параметры

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Параметры ответа

Метод возвращает коллекцию агентов, рассмотрим ниже свойства агента.

Свойства system_prompt, ai_instructions и created_by в списке не возвращаются – получить их можно методом получения агента по ID.

Пример ответа

{
  "_total_items": 1,
  "_page": 1,
  "_page_count": 1,
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/amma/agents?page=1&limit=50"
    }
  },
  "_embedded": {
    "agents": [
      {
        "id": "b1f2c3d4-0000-4a5b-8c9d-000000000001",
        "name": "Помощник по записям",
        "description": "Проверяет записи клиентов и подсказывает свободные слоты",
        "avatar": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/avatar.png",
        "model_size": "M",
        "mcp": {
          "url": "https://mcp.partner.com/booking",
          "transport": "streamable-http",
          "has_headers": true
        },
        "is_active": true,
        "client_uuid": "a0c11111-2222-4333-8444-555566667777",
        "created_at": 1753305600,
        "updated_at": 1753305600,
        "_links": {
          "self": {
            "href": "https://example.amocrm.ru/api/v4/amma/agents/b1f2c3d4-0000-4a5b-8c9d-000000000001"
          }
        }
      }
    ]
  }
}

Получение агента по ID

Метод

GET /api/v4/amma/agents/{id}

Описание

Метод позволяет получить агента по его UUID. В отличие от списка агентов, этот метод дополнительно возвращает системный промпт агента, инструкции для Аммы и ID пользователя, от имени которого агент создан.

Ограничения

Метод доступен только интеграциям.
Метод доступен интеграциям, у которых установлен scope – Амма.

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Параметры ответа

Метод возвращает модель агента, рассмотрим ниже её свойства.

Пример ответа

{
  "id": "b1f2c3d4-0000-4a5b-8c9d-000000000001",
  "name": "Помощник по записям",
  "description": "Проверяет записи клиентов и подсказывает свободные слоты",
  "system_prompt": "Ты — ассистент по онлайн-записи. Помогаешь проверить запись клиента и найти свободное время.",
  "ai_instructions": "Передавай этому агенту вопросы о записи клиента, расписании и свободных слотах",
  "avatar": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/avatar.png",
  "model_size": "M",
  "mcp": {
    "url": "https://mcp.partner.com/booking",
    "transport": "streamable-http",
    "has_headers": true
  },
  "is_active": true,
  "client_uuid": "a0c11111-2222-4333-8444-555566667777",
  "created_by": 123456,
  "created_at": 1753305600,
  "updated_at": 1753305600,
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/amma/agents/b1f2c3d4-0000-4a5b-8c9d-000000000001"
    }
  }
}

Редактирование агента

Метод

PATCH /api/v4/amma/agents/{id}

Описание

Метод позволяет изменить параметры агента. Передавайте только те свойства, которые нужно изменить.

Изменить можно свойства name, description, ai_instructions, system_prompt, avatar, model_size, mcp и is_active.

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

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

Ограничения

Метод доступен только интеграциям.
Метод доступен интеграциям, у которых установлен scope – Амма.

Заголовок запроса

Content-Type: application/json

Параметры запроса

Обязательные поля отсутствуют, тело запроса должно содержать хотя бы одно изменяемое свойство.

Требования к изображению в avatar: размер до 2 МБ, MIME-тип image/*. Ссылка должна использовать схему https, а её хост – быть публичным, как и адрес MCP-сервера. Изображение загружается в amoCRM, поэтому в ответе возвращается ссылка на файл в amoCRM, а не исходная ссылка.

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

Пример запроса

{
  "model_size": "L",
  "system_prompt": "Обновлённый системный промпт агента.",
  "is_active": false
}

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Параметры ответа

Метод возвращает модель изменённого агента, рассмотрим ниже её свойства.

Пример ответа

{
  "id": "b1f2c3d4-0000-4a5b-8c9d-000000000001",
  "name": "Помощник по записям",
  "description": "Проверяет записи клиентов и подсказывает свободные слоты",
  "system_prompt": "Обновлённый системный промпт агента.",
  "ai_instructions": "Передавай этому агенту вопросы о записи клиента, расписании и свободных слотах",
  "avatar": "https://drive-b.amocrm.ru/download/aff5603a-28b1-4c17-8e98-16e473b323b3/367b9f38-5f01-4cea-947e-dfab47aea522/avatar.png",
  "model_size": "L",
  "mcp": {
    "url": "https://mcp.partner.com/booking",
    "transport": "streamable-http",
    "has_headers": true
  },
  "is_active": false,
  "client_uuid": "a0c11111-2222-4333-8444-555566667777",
  "created_by": 123456,
  "created_at": 1753305600,
  "updated_at": 1753309200,
  "_links": {
    "self": {
      "href": "https://example.amocrm.ru/api/v4/amma/agents/b1f2c3d4-0000-4a5b-8c9d-000000000001"
    }
  }
}

Удаление агента

Метод

DELETE /api/v4/amma/agents/{id}

Описание

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

Массовое удаление агентов не поддерживается – агенты удаляются по одному.

Ограничения

Метод доступен только интеграциям.
Метод доступен интеграциям, у которых установлен scope – Амма.

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Параметры ответа

Метод не возвращает тело

Формат ошибок

Пример ошибки

{
  "title": "Forbidden",
  "type": "https://httpstatus.es/403",
  "status": 403,
  "detail": "Integration is missing the 'amma' scope"
}

Ошибки валидации

Если ошибка относится к конкретным свойствам агента, в ответе дополнительно возвращается массив validation-errors.

Коды ошибок:

Часть ошибок возвращается без массива validation-errors — с описанием в свойстве detail. Так возвращаются ошибки формы запроса (тело не является массивом, некорректный JSON, некорректные page и limit) и превышение отдельных лимитов.

Пример ошибки валидации

{
  "validation-errors": [
    {
      "request_id": 0,
      "errors": [
        {
          "code": "NotBlank",
          "path": "name",
          "detail": "This value should not be blank."
        },
        {
          "code": "Url",
          "path": "mcp.url",
          "detail": "This value is not a valid URL."
        }
      ]
    }
  ],
  "title": "Bad Request",
  "type": "https://httpstatus.es/400",
  "status": 400,
  "detail": "Request validation failed"
}