Function の付与

Agent への Package の付与: バージョン、タイムアウト、ネットワーク、承認。

Package は、Agent のバージョンに 付与 されるまで何もしません。呼び出しに関することは、すべて Grant で決めます。Package 側ではネットワーク、Credential、制限を宣言しないので、同じ Package を、ある Agent には狭い範囲で、別の Agent には広い範囲で付与できます。

コンソールでは、Grant は バージョンの編集画面 の Tool › Function package で設定します。Agent config では functions 配列にあたります。

フィールド

{
  "functions": [
    {
      "name": "files",
      "source": { "type": "platform", "package": "files" },
      "default_policy": "allow"
    },
    {
      "name": "billing",
      "source": {
        "type": "workspace",
        "function_id": "0192f5c4-7a1e-7d3c-9b8f-2c6d1e4a5b70",
        "version": { "type": "pinned", "number": 3 }
      },
      "default_policy": "allow",
      "tools": [{ "name": "issue_refund", "policy": "require_approval" }],
      "timeout_secs": 120,
      "network": { "type": "allowlist", "hosts": ["billing.acme.example"] },
      "http_credentials": ["https://billing.acme.example"]
    }
  ],
  "volume": { "data": { "type": "enabled" } }
}

モデルに見えるもの

各 Tool は fn__<grant>__<tool> (上の例では fn__billing__issue_refund) という名前で、Tool の説明と入力 Schema とともにモデルに渡されます。Package 自体の説明と Tool の出力 Schema は人が読むためのもので、モデルには渡されません。

さらに Subako は Grant ごとに一度、Session Volume の構成、1 回の呼び出しの実行時間の上限、接続できる Host をモデルに伝えます。つまり、Grant の設定そのものが Agent による Tool の使い方を方向づけます。

バージョン

Session は開始時に各 Grant のバージョンを 1 つに確定し、終了までそのバージョンを使います。

• 最新 は Package の更新に追従します。今日アップロードしたバージョンが、これから開始する Session で使われます。Agent の新しいバージョンを作る必要はありません。
• 固定 は、Agent の新しいバージョンで別のバージョンを指定するまで、同じバージョンを使い続けます。

変更内容を Agent のバージョンを通してレビューしたい Package は固定し、自動で更新されても信頼できる Package は最新に追従させます。

ネットワーク

Grant でネットワークを与えない限り、呼び出しはネットワークを使えません。

Host は api.example.com のような名前で指定し、その Host だけを許可します。*.example.com と書くとサブドメインを許可しますが、example.com 自体は含みません。Grant の設定にかかわらず、リクエストは https でしか送られず、Private address、Reserved address、Metadata address への接続は常に拒否されます。リダイレクトも 1 ホップごとに検査されるので、リダイレクト先でも同じです。

Credential

認証が必要な API を呼び出す Function であっても、Function 自身にキーを持たせてはいけません。代わりに次のようにします。

1. API の Origin 用の HTTP header Credential として、キーを Vault に追加します。たとえば https://billing.acme.example に authorization Header を設定します。
2. その Origin を Grant の Credential (http_credentials、最大 16 個) に指定します。その Origin には、Grant のネットワーク設定でも接続できる必要があります。
3. その Vault を指定して Session を開始します。

これで、Function がその Origin に送るリクエストすべてに Header が付きます。Header はリクエストが Module を出た後で追加されるので、Module が Header を目にすることはありません。Module がそれらの Header を自分で設定しようとすると、リクエストは拒否されます。Session のどの Vault にもその Origin の Credential がなければ、リクエストは Credential なしで送られます。GitHub を例にした手順は API を呼び出す で説明しています。

承認

各 Grant には、Tool 全体に適用する 既定の Policy と、Tool 名の完全一致で既定値を上書きする Tool rule があります。

• 許可 (allow): 呼び出しはそのまま実行されます。
• 承認を求める (require_approval): 呼び出しは、人がコンソールまたは アプリ から許可または拒否するまで待機します。
• 拒否 (deny): Tool はモデルに提供されません。

たとえば、読み取りだけを行う Package は 許可 で実行し、何かを変更する 1 つの Tool だけを 承認を求める にできます。タイムアウトの後でモデルが再試行するかもしれない Tool は、二度実行しても問題ないように作ってください。

Session Volume

Agent config の volume (編集画面では Session Volume) で、Function が Temporary に加えて Data 領域も使えるかどうかを決めます。詳しくは ランタイム を参照してください。

課金

Function の呼び出しは、実行時間 (HTTP の待ち時間を含み、Subako Cloud では 1 秒あたり 0.01 SC) と、Volume に書き込んだバイト数に応じて課金されます。詳しくは Plan と使用量 を参照してください。