Агентский доступ

Агентский доступ позволяет ИИ-агенту работать с Gigma через обычный API управления: читать разрешённые данные, готовить сводки и выполнять подтверждённые операции.

Для агента создаётся отдельная техническая учётная запись и Agent Token. Доступ ограничивается проектом, ролью, правами учётной записи и списком методов, разрешённых на вашем агентском сервере.

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

Что вы настроите

После подключения агент сможет:

• отправить запрос владельцу проекта;
• получить первый Agent Token без ручной передачи через чат или письмо;
• проверить фактически выданные права;
• вызывать только заранее разрешённые методы Gigma;
• безопасно остановиться, если токен отозван или действие запрещено.

Кто что делает

Быстрый старт

Шаг 1. Определите минимальные права

Для первого подключения используйте профиль только для чтения:

[
	"view-orders",
	"view-counterparties"
]

Не запрашивайте права «на будущее». Владелец может одобрить только подмножество запрошенных permissions, но не может расширить запрос.

Шаг 2. Агент создаёт запрос

POST /api/agent-access-requests HTTP/1.1
Host: api.gigma.ru
Content-Type: application/json
Accept: application/json

{
	"owner_email": "owner@example.com",
	"agent_name": "Order Assistant",
	"agent_login": "agent-order-assistant",
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"purpose": "Читать заказы и готовить сводки"
}

Сразу сохраните request.public_id и request.request_token. Они нужны для проверки статуса и получения первого токена.

Полный сценарий, ответы и обработка ошибок описаны на странице Подключение агента.

Шаг 3. Владелец подтверждает доступ

Gigma отправляет письмо человеку, чей login совпадает с owner_email и который имеет право одобрить запрос. Владелец проверяет имя, назначение и permissions, затем одобряет или отклоняет запрос.

Пока решение не принято, агентский клиент опрашивает POST /api/agent-access-requests/{publicId}/status.

Шаг 4. Агент один раз получает токен

После статуса approved агентский клиент вызывает POST /api/agent-access-requests/{publicId}/consume.

agent_token.value возвращается только один раз. Сохраните его в хранилище секретов до завершения операции. Повторный consume подтвердит состояние consumed, но не вернёт секрет снова.

Шаг 5. Проверьте подключение

GET /api/user HTTP/1.1
Host: api.gigma.ru
Authorization: Bearer <agent_token>
Accept: application/json

{
	"user": {
		"id": 214,
		"login": "agent-order-assistant",
		"first_name": "Order Assistant",
		"branch": null,
		"department": null,
		"is_banned": false,
		"permissions": [
			{
				"name": "view-orders"
			},
			{
				"name": "view-counterparties"
			}
		],
		"last_activity_at": null
	}
}

Настройте рабочие методы

Agent Token используется не в отдельном «агентском API», а в обычных методах Gigma. Агентский сервер должен разрешать конкретные пары HTTP method + path.

Рекомендуемый профиль только для чтения

Полные параметры и ответы находятся в разделах Заказы и исполнение и Клиенты и контрагенты.

Перед запросом карточки сначала получите ID из списка текущего проекта. Не позволяйте модели передавать произвольный ID без такой проверки.

Операции записи

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

1. нужное право существует и назначено учётной записи агента;
2. метод проверен на данных текущего и чужого проекта;
3. инструмент использует фиксированную схему запроса;
4. человек видит итоговые method, path и JSON;
5. выполнение требует явного подтверждения;
6. после записи сервер повторно читает объект и сверяет результат.

POST /api/orders/calculator выполняет расчёт и не создаёт бизнес-сущность. Его можно подключить раньше остальных записывающих инструментов, но payload всё равно должен проходить строгую схему.

Не повторяйте автоматически POST, PATCH или DELETE после timeout, 401, 403, 404, 409 или 422.

Что не включать в обычный профиль

Для отдельного специализированного агента сначала проверьте соответствующий controller, policy, response и отрицательный сценарий на объект другого проекта.

Обязательные правила агентского сервера

Точный список разрешённых методов

Храните фиксированные пары:

GET /api/orders
GET /api/orders/{order}

Не принимайте от модели готовый URL или HTTP-метод.

Строгая схема

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

Секреты

Не передавайте в логи, аналитику и контекст модели:

• Agent Token;
• request_token;
• approval_token;
• ответ первого consume;
• App Token приложения.

Один профиль — одна учётная запись

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

Выберите задачу

Если токен потерян или истёк

Значение Agent Token нельзя прочитать повторно. Человек с permission manage-agent-tokens выпускает новый токен, проверяет его через GET /api/user, переводит агентский сервер на новый секрет и отзывает старый.