Действия OpenAPI

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

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

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

• Формат OpenAPI 3.0+ (JSON или YAML).
• В схеме указан servers с абсолютным URL — по нему Charo будет вызывать API.
• У каждой операции есть operationId и осмысленное description: именно по описаниям языковая модель решает, какое действие вызвать и с какими параметрами. Пишите описания как инструкцию для человека: что делает операция, когда её использовать, что означают параметры.
• Параметры и тела запросов типизированы схемами; обязательные поля отмечены required.

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

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

Поддерживаются стандартные способы:

• Без аутентификации — для внутренних API в закрытом контуре.
• Заголовки авторизации — собственные заголовки (например, Authorization: Bearer … или API-ключ); значения хранятся в зашифрованном виде и подставляются в каждый запрос.
• OAuth — подключение через настроенную OAuth-конфигурацию; токен запрашивается и обновляется автоматически.
• Передача аутентификации пользователя — запрос выполняется с токеном пользователя, задавшего вопрос (passthrough), если ваш API понимает эти токены.

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

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

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

Пример

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

openapi: 3.0.0
info:
  title: Справочник сотрудников
  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 попадает в контекст модели: не отдавайте в действии больше данных, чем допустимо показать пользователю.
• Разграничивайте доступ через видимость агента: действие доступно всем, кому доступен агент с этим действием.

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

«Не удалось разобрать схему»

Проверьте схему валидатором (например, editor.swagger.io) — чаще всего не хватает operationId или блока servers.

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

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

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

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