Вэб-хукі, SCIM і спалучэнне

curl https://your-aihummer.example/v1/pairing/redeem \
  -H "Content-Type: application/json" \
  -d '{ "code": "ABCD-EFGH" }'

Гэта старонка ахоплівае астатнія пратакольныя паверхні: **спалучэнне прылад**, прадпрыемства **федэрацыя аўтэнтыфікацыі** (SAML / SCIM / OAuth), падключэнне па жаданні **Сервер MCP** і **A2A** канечныя пункты **СМІ** перадача, і **Злучыць-RPC** паспяхова. Некаторыя з іх па змаўчанні адключаны і павінны быць уключаны явна. ## Спалучэнне прылады Мабільныя і настольныя кліенты далучаюцца да інстанцыі праз кароткі абмен парамі (прыкладанне iOS/macOS выкарыстоўвае толькі QR-пары). | Метад і шлях | Мэта | |---|---| | `POST /v1/pairing/redeem` | Выкупіць код спалучэння і наладзіць прыладу | | `POST /v1/pairing/device/validate` | Праверыць ужо спалучаную прыладу | ```bash curl https://your-aihummer.example/v1/pairing/redeem \ -H "Content-Type: application/json" \ -d '{ "code": "ABCD-EFGH" }' ``` ## Федэрацыя аўтэнтыфікацыі AiHummer інтэгруецца з правайдэрамі ідэнтычнасці прадпрыемства як для ўваходу, так і для прадастаўлення карыстальнікаў. ### SAML | Метад і шлях | Мэта | |---|---| | `GET /saml/metadata` | Метаданыя пастаўшчыка паслуг для вашага IdP | | `POST /saml/acs` | Служба кліентаў сцвярджэнняў (SAML-адказ) | | `GET /saml/login` | Пачаць уваход праз SAML | ### Правайджынг SCIM Сістэма кіравання ідэнтычнасцю паміж даменамі (SCIM 2.0) дазваляе вашаму IdP аўтаматычна ствараць і кіраваць карыстальнікамі. | Метад і шлях | Мэта | |---|---| | `.../scim/v2/Users` | Спіс / стварэнне карыстальнікаў | | `.../scim/v2/Users/{id}` | Чытаць / абнаўляць / выдаляць карыстальніка | Канчатковыя пункты SCIM аўтэнтыфікуюцца з дапамогай **прымач SCIM-токена на арандатара**, выдадзена (і заменена/адклікана) у `POST /v1/admin/scim/token`; IdP адпраўляе яго ў `Authorization: Bearer` загаловак. Токен паказваецца адзін раз у час выдачы. ### Токен OAuth | Метад і шлях | Мэта | |---|---| | `POST /v1/oauth/token` | Канчатковая кропка токена OAuth | ## Сервер MCP (публікацыя знешняя) AiHummer можа публікаваць свае ўласныя інструменты для кліентаў MCP, дзейнічаючы як **Сервер MCP**Гэта **падаць згоду** і адключана, калі вы не ўсталюеце `AIHUMMER_MCP_PUBLISH=1`. | Метад і шлях | Мэта | |---|---| | `POST /v1/mcp` | Канчатковы пункт сервера MCP (патрэбна `AIHUMMER_MCP_PUBLISH=1`) | > [!WARNING] > **Аднаго `AIHUMMER_MCP_PUBLISH=1` недастаткова.** Ён адкрывае адрас, але спіс > экспарту пусты: `tools/list` вяртае пусты масіў, а любы выклік адхіляецца. > Пералічыце патрэбныя інструменты **дакладнымі імёнамі праз коску** ў > `AIHUMMER_MCP_EXPORT_TOOLS` — шаблоны і `*` не падтрымліваюцца. Вонкі можна > аддаваць толькі інструменты **чытання**: `http_request`, `web_fetch`, > `browser`, `code_exec` і `filesystem_read` не экспартуюцца ніколі, нават калі > іх пералічыць. > > Абедзве настройкі задаюцца ў **Кіраванне → Настройкі** або камандай > `aihummer settings set`, а не ў `gateway.env` — для гэтых ключоў асяроддзе > ігнаруецца. `AIHUMMER_MCP_PUBLISH` прымае роўна `1`: `true` ці `on` > пакінуць адрас закрытым. Змены дзейнічаюць пасля перазапуску шлюза. > > Кліент абавязаны даслаць ключ API з вобласцю `mcp` у загалоўку > `Authorization: Bearer …`; без яго адказ — 401. > [!NOTE] > Публікацыя інструментаў звонку адрозніваецца ад *выкарыстання* сервера MCP як > інтэграцыя без кода. Гэты канец кропкі прызначаны для таго, каб іншыя кліенты MCP маглі выклікаць яго > АйХамер ## A2A (Агент-да-Агента) AiHummer можа адкрыць паверхню A2A, каб іншыя агенты маглі яе знайсці і адпраўляць паведамленні. Гэта таксама **падаць згоду** праз `AIHUMMER_A2A_PUBLISH=1`. | Метад і шлях | Мэта | |---|---| | `GET /.well-known/agent.json` | Карта агента A2A / дакумент адкрыцця | | `POST /a2a/message` | Атрымаць паведамленне A2A (патрабуецца `AIHUMMER_A2A_PUBLISH=1`) | ## СМІ Вялікія медыяфайлы (аўдыё, выявы, дакументы) загружаюцца і атрымліваюцца праз асобныя канцыпункты замест таго, каб уключацца ў JSON. | Метад і шлях | Мэта | |---|---| | `PUT /v1/media/{id}/content` | Загрузіце байты для медыяаб'екта | | `GET /v1/files/{id}` | Спампаваць захаваны файл | > [!TIP] > Набор `AIHUMMER_BLOB_DIR` каб актываваць службу медыя/файлаў, і > `AIHUMMER_MEDIA_TOKEN_SECRET` такім чынам падпісаныя URL для загрузкі застаюцца сапраўднымі на працягу > перазапускі. ## Службы Connect-RPC Для кліентаў з тыпізацыяй і струменевай перадачай AiHummer таксама прадастаўляе доступ **Злучыць-RPC** паслугі праз HTTP (падтрымліваецца серверны паток): | Сэрвіс | Плошча | |---|---| | `aihummer.health.v1` | Медыцынскія агляды | | `aihummer.event.v1` | Паток падзей | | `aihummer.conversation.v1` | Размовы | | `aihummer.push.v1` | Дастаўка push | | `aihummer.media.v1` | Перамяшчэнне медыя | | `aihummer.turn.v1` | Turn execution | ## Куды далей - Адпраўляць паведамленні ў AiHummer: [Інбоўнд і трыгеры інтэграцыі](/be/v1.0/api/inbound-triggers). - Пераключыце гэтыя паверхні і іншае: [Зменныя асяроддзя](/be/v1.0/reference/env-vars). - Кіруйце асобнікам: [Даведнік CLI](/be/v1.0/reference/cli).