Вызов по ключу
Ключ агента вызывает подключённые сервисы организации без агента: по REST на https://api.samreshuuu.ru/v1 или через MCP-сервер. Двери различаются транспортом, а не смыслом: каталог, паспорт и вызов принимают одни аргументы и отказывают одними кодами с одними details, у REST к ним добавляется HTTP-статус. Агент в приложении зовёт те же операции своими инструментами по другим правилам, они собраны в разделе Агент в приложении.
| Шаг | REST | MCP | Право ключа |
|---|---|---|---|
| Каталог | GET /v1/connectors | list_services | tools:read |
| Паспорт сервиса | GET /v1/connectors/{service}, модуль в ?module= | describe_service | tools:read |
| Подключённые кабинеты | GET /v1/connections | нет | tools:read |
| Вызов | POST /v1/connectors/{service}/execute | connector_execute | tools:read, запись tools:write |
| Статус согласия | GET /v1/connectors/approvals/{approval_id} | нет | tools:read |
Первый вызов
Сначала узнайте, какие кабинеты видит ключ. Ответ data перечисляет {service, connection, label} по кабинетам, открытым всей организации; connection это готовый адрес для service:
Затем вызовите сервис. Тело вызова это аргументы connector_execute без service: method, path, module, body, query. Ответ и отказы те же, что у MCP:
Каталог и паспорт
Каталог отдаёт services: [{name, summary, transport}] без признака подключённости: имя в каталоге значит «сервис существует», а не «подключён». Подключённые кабинеты называет GET /v1/connections.
Паспорт одного сервиса без module это индекс: модули, call_template, critical_hints и заголовки рецептов. С module паспорт отдаёт методы модуля, шаблоны запросов, лимиты, пагинацию и примеры ответов. Неизвестный модуль возвращает индекс и _module_filter_warning со списком допустимых. Переиспользуйте полный паспорт при совпадении сервиса, модуля, версии содержимого и области доступа; version обозначает версию схемы ответа. Аргументы вызова проверяются по схеме сервиса до любого исходящего запроса.
Параметры вызова
| Field | Type | Description |
|---|---|---|
| servicerequired | string | Ключ коннектора из каталога (например moysklad). Кабинет называется суффиксом в этой же строке (`ozon:2`), отдельного поля для него нет; см. «Кабинеты» ниже. В REST это часть пути, а не поле тела. |
| module | string | REST: обычно не нужен, модуль выводится из path; укажите, только если пути нет среди рецептов. RPC: обязателен (пространство методов, например crm). |
| methodrequired | string | REST: HTTP-глагол (GET/POST/…). RPC: имя метода (crm.deal.list). Глагол и путь всегда в разных полях. |
| path | string | REST: путь с подставленными значениями (/api/v3/stocks/12); адрес объекта из ответа (meta.href) принимается как есть. RPC: пустая строка. |
| body | object | array | Тело POST/PUT/PATCH или именованные аргументы RPC-метода. |
| query | object | Параметры строки запроса; массивы сериализуются автоматически. |
REST и RPC
Коннекторы бывают двух форм, и вызов обрабатывает обе:
- REST (большинство коннекторов): HTTP-
method,pathиbody/query;moduleвыводится из пути. - RPC (например
bitrix24):module(пространство методов, напримерcrm), имя метода вmethod(crm.deal.list), аргументы вbody,pathпустой.
Точную форму показывают call_template и рецепты паспорта. HTTP-глагол с путём у RPC-сервиса отклоняется с TOOL_VALIDATION_FAILED и меню available_recipes.
Кабинеты
Ключ видит только кабинеты, открытые всей организации; личные кабинеты того, кто выпустил ключ, ему недоступны. Когда у сервиса один такой кабинет, голое имя сервиса адресует его. Когда подключено несколько, голое имя по ключу не читает их все: вызов отказывает с UNKNOWN_INSTANCE и списком details.candidates (connection, label). Тот же код со списком приходит, если названного кабинета нет или его метка стоит у нескольких. Возьмите connection из candidates или из GET /v1/connections и передайте в service целиком: в REST это путь /v1/connectors/ozon:2/execute, в MCP аргумент service:
Какой из случаев произошёл, называет details.connector_code (INSTANCE_AMBIGUOUS или INSTANCE_NOT_FOUND); ветвитесь по code.
Сервис не подключён
Ключ не подключает сервисы: пароли и токены кабинетов через API не передаются. Если нужного кабинета нет или его вход истёк, вызов отказывает, а details несут ссылку для человека connect_url и причину auth_reason:
auth_reason | Код | Что случилось | Что делает человек |
|---|---|---|---|
missing_link | INTEGRATION_REQUIRED | Кабинета, открытого организации, нет | Подключает кабинет и открывает его организации |
not_shared | INTEGRATION_REQUIRED | Кабинет есть у того, кто выпустил ключ, но он личный | Открывает этот кабинет организации |
reauthentication_required | AUTH_RECONNECT_REQUIRED | Вход в кабинет истёк | Подключает кабинет заново |
Отдайте connect_url человеку из организации. Ссылка ведёт в приложение и токена не несёт: страница сама попросит войти. Параметр org называет организацию ключа, поэтому человек из нескольких организаций подключит кабинет туда, где работает ключ. После его действия повторите тот же вызов; повтор до этого получит тот же отказ.
Согласие на запись
Запись, которую режим доверия организации без человека не пропускает, по ключу не выполняется сразу. Вызов отказывает 409 с кодом APPROVAL_PENDING, а карточка согласия с этим вызовом встаёт в основном чате того, кто выпустил ключ, в приложении Сам Решу. Одобряет человек в приложении, а не ваш клиент, поэтому у заявки есть ручка статуса. Чтение согласия не спрашивает.
details отказа:
| Поле | Что значит |
|---|---|
approval_id | id заявки |
approval_status | pending, пока человек не ответил |
approval_status_path | путь ручки статуса, /v1/connectors/approvals/{approval_id} |
approval_expires_at | до какого момента заявка ждёт ответа и повтора |
GET /v1/connectors/approvals/{approval_id} отвечает объектом заявки: id, status, created_at, expires_at (у ждущей и одобренной заявки) и decided_at (после ответа человека). status принимает значения pending, approved, rejected, expired, executed. Ручка видит только заявки своего ключа: чужой и неизвестный id отвечают 404 с кодом DATA_NOT_FOUND.
- Получив
APPROVAL_PENDING, опрашивайте ручку статуса с паузой. Повтор того же вызова, пока заявка ждёт, отвечает той же заявкой без второй карточки. - Когда
statusсталapproved, повторите тот же вызов с теми же аргументами: одобрение исполнит его один раз, иstatusстанетexecuted. Вызов с другими аргументами поднимет новую карточку. Одобряется этот вызов, а не правило для ключа. - Заявка ждёт ответа и повтора сутки, срок называет
approval_expires_at. Потом она снимается (expired), и повтор спросит заново.
Отказы, после которых повторять вслепую нельзя:
TOOL_USER_DECLINED(403): человек отклонил вызов. До конца срока заявки тот же вызов отказывает так же. Не повторяйте его и не обходите другим вызовом.APPROVAL_RETIRED(409): одобрение уже использовано или снято,details.reasonназывает причину. Приclaim_lostодобренный вызов мог уже выполниться: проверьте состояние в сервисе, прежде чем решать, повторять ли.APPROVAL_QUEUE_PENDING(409): у человека уже ждут ответа другие одобрения; повторите после них.APPROVAL_NO_APPROVER(409): карточку показать не удалось, вызов не выполнен.
Тариф, лимит и журнал
Вызовы по ключу работают, пока у организации действует тариф, и отдельно не оплачиваются; без тарифа запрос получает 402 с кодом SUBSCRIPTION_REQUIRED. Каждый REST-запрос и каждый connector_execute через MCP тратят минутный лимит ключа, превышение отвечает 429 с кодом RATE_LIMIT_EXCEEDED и паузой в Retry-After и в details.retry_after_s. Таблица лимитов описана в разделе Ошибки и лимиты API агентов.
Журнал вызовов коннекторов по ключу (ключ, сервис, действие, кабинет, исход, длительность) показывает консоль разработчика.
Подсказки did-you-mean
Вызовы не падают молча при почти-попадании. Рецепты служат примерами, а не белым списком, поэтому:
- Неизвестный service возвращает отказ с похожими ключами в
details.suggestions. - Неизвестный module возвращает
TOOL_VALIDATION_FAILEDсо спискамиknown_modulesиsuggestions, и то же даёт пропущенный там, где он нужен (RPC), с тем же списком. У REST-вызова модуль выводится из пути, и неверная метка вызов не ломает. - Path, которого нет среди рецептов, всё равно выполняется, а в метаданные ответа (и в ошибку, например 404) ложится меню
available_paths. Глагол, которого нет у рецептов этого пути, не отказывает и подсказки не добавляет: какие глаголы принимает путь, решает таблица глаголов коннектора, а где она не закрыта, отвечает сам сервис. - Неизвестный или неназванный кабинет возвращает
UNKNOWN_INSTANCEсо спискомcandidates, см. Кабинеты.
Ошибки
Через MCP отказ приходит результатом с isError: true и объектом {code, message, retryable, hint?, details?}, по REST тем же кодом в объекте ошибки с HTTP-статусом. Ветвитесь по code; details несут данные отказа (кандидаты, подсказки, ссылку), а не инструкции. Кроме случаев выше, стоит различать:
- Нет прав у кабинета на путь (403).
AUTH_SCOPE_MISSING: ключу или токену кабинета не хватает прав, их можно выдать новым подключением.AUTH_SCOPE_NOT_GRANTABLE: права приложения фиксированы, повтор не поможет.details.required_scopesназывают права, которых не хватило. - Автопроверка запретила запись.
TOOL_AUTO_REVIEW_BLOCKED: секрет уходит не тому сервису, который его выдал; согласие этот запрет не снимает. - Метод снят вендором. Если Wildberries или Ozon сами объявили метод выключенным (заголовок
Sunsetс прошедшей датой или «this method is deprecated» в теле), подсказка велит больше не звать этот путь и искать преемника вdescribe_service.
Агент в приложении
Агент в чате и задаче зовёт те же три шага своими инструментами list_services, describe_service и connector_execute, но правила у него свои:
list_servicesагента отдаётitems(подключённые сервисы с кабинетами и статусом на моментas_of) иavailable(имена всего каталога).- Голое имя сервиса у агента распределяет чтения по всем подключённым кабинетам, кроме сервисов, где свод по кабинетам не складывается (например
onecиmoysklad); запись называет один кабинет. Вызов по ключу так не делает и отказывает со спискомcandidates. - У
connector_executeагента есть параметрfiles: файлы для загрузки по имени поля вендора (id вложения или артефакта, путь в песочнице), кодирует их платформа. - В песочнице агента
cw.connect()читает страницы, фильтрует их и считает итог в одной ячейке Python; в повторяющемся сценарии агент зовёт готовую функцию навыка. - Нет кабинета или его вход истёк: ход встаёт на паузу с карточкой подключения и продолжается, когда кабинет подключат.
Какие коннекторы и кабинеты выданы агенту, описано в разделе Агенты.