Hane Platform

外部連携

Connection と秘密値、取り込みと出力、顧客の API と API Gateway、ポータルの手順、webhook、MCP の扱いを説明します。

このページでは、Hane が外部のシステムとどうつながるかを説明します。外へ出る口と、外から入ってくる口を分けて、提供状況とあわせて整理します。

全体像

方向	仕組み	使う定義・API
Hane → 外部	接続先から読む・書く	`integrations/v1alpha1` の `Connection`
Hane → 外部	イベントを顧客のシステムへ届ける	購読（webhook）
外部 → Hane	顧客の API を Hane の入口から公開する	`gateway/v1alpha1` の `Route`・`PublishedApi`・`Consumer`
外部 → Hane	顧客のアプリや CI が公開 API を呼ぶ	サービスアカウントと API キー

Connection

外部との接続は Connection に書き、ReleaseBundle にまとめて有効化します。provider で種類を決めます。

`provider`	できること	提供状況
`api`	登録した HTTP の操作を Agent から使うか、Route の転送先にします	提供しています
`hr`	人事の台帳から社員と部門を取り込みます（`POST /v1/integrations/sync-jobs`）	提供しています
`accounting-csv`	会計へ渡す CSV を出力します（`POST /v1/integrations/exports`）	提供しています
`portal`	ログインが要る Web のポータルの一覧を読んで取り込みます	プレビュー
`storage`	外部の保管場所を読み、文書として同期します（読むだけ）	プレビュー

api の Connection には、操作ごとに HTTP メソッド・パス・影響区分・入力と出力の JSON Schema を登録します。呼出し元が URL を自由に指定することはできません。

apiVersion: integrations/v1alpha1
kind: Connection
metadata:
  name: calendar
spec:
  provider: api
  endpoint: https://calendar.example.com
  secret: calendar-api-token
  operations:
    get-busy:
      method: GET
      path: /calendar/freebusy
      impact: read
      input:
        type: object
        additionalProperties: false
        required: [calendar, from, to]
        properties:
          calendar: { type: string }
          from: { type: string, format: date }
          to: { type: string, format: date }
      output:
        type: object

影響区分は、GET だけが read で、ほかのメソッドは write です。Agent が write の操作を呼ぶと（integration.execute）、ActionRequest にして承認を通してから一度だけ実行します。

秘密値

接続に使う API のトークンなどは、秘密値として登録します（PUT /v1/integrations/secrets/{name}。secrets:write が必要）。

値は暗号化して持ち、登録した後は API でもコンソールでも見られません。
値を使うのは、取り込みの処理と、認可した顧客の API の呼出しだけです。Agent やモデルには渡しません。
OAuth 2.0 の認可コード（PKCE つき）で接続する Connection は、管理者がコンソールで同意すると、Hane がトークンを秘密値として持ち、期限が近ければ更新します。
rotation を書くと、決めた日数ごとに秘密値を回します。接続先に古い値が残った回は、人が片付けた記録を残すまで対応待ちとして一覧に出ます。

API Gateway

顧客の API を、Hane の入口を通して呼べるようにする仕組みです。

定義	役割
`Route`	入口から、`api` の Connection へ要求を渡す経路。パス・メソッド・timeout を決めます
`PublishedApi`	Route の上で公開する顧客の API。OpenAPI で操作を書きます
`Consumer`	PublishedApi を呼ぶ側。Consumer ごとに API キーと上限を持ちます
`ToolExposure`	PublishedApi の操作を 1 つ、Agent のツールにする宣言

社内の呼出しは /v1/gateway/invoke/{route}/…（gateway:routes.call が必要）、Consumer からの呼出しは /v1/gateway/published/{api}/… を使います。
転送先には、呼出し元の資格情報や Cookie を渡しません。既定では、Connection の秘密値で署名した 60 秒の短命のトークンを、1 回の呼出しごとに渡します。Route と PublishedApi では、秘密値そのものを渡す設定（backendAuth: connection_secret）も選べます。Agent の ToolExposure の呼出しには、いつも短命のトークンを渡します。
Consumer の API キーは発行したときに一度だけ返し、失効すると次の要求から拒否します。
呼出しの記録（本文は含まない）は GET /v1/gateway/calls で読めます。

ポータルの手順プレビュー

API のない Web のポータルには、BrowserFlow で手順を定義し、Agent が browser.run_flow で動かします。外への操作なので、承認が要ります。社内のネットワークにあるポータルには、顧客のネットワークの中や社員の端末で動くランナーを置き、ランナーから外向きに接続して仕事を取りに来させます。ポータルのパスワードはランナーの手元に置き、Hane には送りません。

CAPTCHA や多要素認証で止まったときの人への引き継ぎ、ランナーの配布物の署名などは、まだ整っていません。

webhook

案件の完了などのイベントを、顧客のシステムへ HTTP で届けられます。プロジェクトと環境ごとに購読を登録し（/v1/workflows/event-subscriptions）、受け手は署名の秘密値で署名を確かめます。同じイベントの再送は同じ配信として扱います。登録と受け手の作り方は webhook を受けるを見てください。