Действия OpenAPI

Что такое действия

Действие — внешний API, который агент может вызвать во время ответа: создать заявку, проверить статус заказа, получить данные из внутренней системы. Действия по OpenAPI-схеме подключаются на странице Админка → Действия OpenAPI и назначаются конкретным агентам.

Рядом в меню есть страница «Действия MCP» — там подключаются внешние MCP-серверы, которые отдают агенту свои инструменты.

Требования к схеме

Схема вставляется в поле «Определение схемы OpenAPI» (JSON или YAML) и проверяется при сохранении:

• версия openapi начинается с 3.;
• есть раздел info, а в нём title и description;
• есть раздел paths;
• ровно один непустой servers[].url — по нему Charo будет вызывать API.

У каждой операции нужны operationId и осмысленное description: именно по описаниям языковая модель решает, какое действие вызвать и с какими параметрами. Пишите описания как инструкцию для человека: что делает операция, когда её использовать, что означают параметры. Параметры и тела запросов типизируйте схемами, обязательные поля отмечайте required.

Одна схема может содержать несколько операций — каждая станет отдельным доступным действием.

Аутентификация

Способ авторизации настраивается отдельно от схемы, в карточке действия:

Способ	Когда подходит
Не настраивать	внутренний API в закрытом контуре, которому авторизация не нужна
Свой заголовок авторизации	API-ключ или свой заголовок; отправляется с каждым запросом
OAuth	указываются URL авторизации, URL токена, Client ID, Client Secret и скоупы; каждый пользователь авторизуется своими учётными данными
OAuth-транзит	серверу передаётся тот же OAuth-токен, которым пользователь вошёл в Charo; вариант доступен, только если в инсталляции включена авторизация OIDC или OAuth

Пока авторизация не настроена, действие помечается в списке как «(Не авторизовано)».

Как агент вызывает действие

1. Пользователь задаёт вопрос; модель видит список доступных агенту действий с их описаниями.
2. Если действие уместно, модель формирует параметры по схеме и Charo выполняет HTTP-запрос к вашему API.
3. Ответ API возвращается модели, и она использует его в ответе пользователю.

Действие подключается к конкретному агенту в его настройках — глобально действия не включаются.

Пример

Минимальная схема действия «поиск сотрудника в справочнике»:

openapi: 3.0.0
info:
  title: Справочник сотрудников
  description: Поиск сотрудников по внутреннему справочнику компании.
  version: "1.0"
servers:
  - url: https://directory.internal.example.ru
paths:
  /api/employees:
    get:
      operationId: findEmployee
      description: >
        Ищет сотрудника по фамилии или должности.
        Используй, когда спрашивают контакты или роль сотрудника.
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
          description: Фамилия или должность
      responses:
        "200":
          description: Список найденных сотрудников

Ограничения и безопасность

• Запросы выполняются с сервера Charo: API должен быть доступен из его сети, а межсетевой экран — разрешать этот трафик.
• Модель сама выбирает параметры вызова. Не подключайте операции с необратимыми последствиями (удаление, платежи) без подтверждающего шага на стороне вашего API.
• Ответ API попадает в контекст модели: не отдавайте в действии больше данных, чем допустимо показать пользователю.
• Разграничивайте доступ через видимость агента: действие доступно всем, кому доступен агент с этим действием.

Устранение неполадок

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

Сообщение об ошибке называет недостающий раздел. Чаще всего не хватает info.description, operationId у операции или единственного servers[].url. Проверить схему целиком можно валидатором — например, editor.swagger.io.

Агент не вызывает действие

Улучшите description операции: модель должна понять из него, когда действие уместно. Проверьте, что действие включено у нужного агента.

Вызов завершается ошибкой сети

API недоступен с сервера Charo — проверьте адрес в servers, DNS и правила межсетевого экрана.