API を呼び出す

キーを Vault に置いたまま、認証付きの API を呼び出します。

API クライアントは Function として書くのに向いています。チームが GitHub や請求システム、自社のバックエンドに対して行う呼び出しを、一度コードに書いておけばそのまま使えます。ただし API クライアントにはキーが必要です。そしてキーは、コードにも、Agent のコンテキストにも、モデルが口にしうるどこにも置いてはいけません。

Subako では、Function はキーをいっさい持ちません。キーは、API の Origin 用の HTTP header として Vault に保管します。Function がその Origin にリクエストを送ると、Subako が外に出ていくリクエストに Header を付けます。Function のコードも、モデルも、Session のファイルも、Header を目にすることはありません。

このページでは、サンプルの Package github を使って、GitHub 向けにこの設定を行います。リポジトリについての質問に読み取り専用で答える Package で、プライベートリポジトリにはトークンを使います。

1. トークンを Vault に保管する

まず GitHub の personal access token を作成します。コードについての質問に答えるだけなら、Contents の読み取り権限だけを持つ fine-grained token で十分です。次に、コンソールで Vault を開いて Credential を追加 を選び、HTTP header を選んで次のように入力します。

Origin: https://api.github.com。Scheme、Host、Port だけを指定し、それ以外は含めません。
Header authorization に、値 Bearer <your token> を設定します。

Credential を追加: Origin https://api.github.com の HTTP header と authorization Header

追加した値は、コンソールでもほかのどこでも、二度と表示されません。

2. Origin を指定して Package を付与する

Package をアップロードし (手順はクイックスタートを参照)、Agent のバージョンの編集画面で付与します。トークンを使って GitHub に接続するには、次の 2 つを設定します。

ネットワーク: 許可した Host のみ を選び、api.github.com と codeload.github.com を指定します。codeload.github.com は、GitHub がダウンロードをリダイレクトする先です。
Credential: Origin https://api.github.com を指定します。

Function package の Grant: api.github.com と codeload.github.com に接続でき、https://api.github.com の Credential を使う github

Agent config では、同じ Grant を次のように書きます。

{
  "name": "github",
  "source": { "type": "workspace", "function_id": "<function-id>", "version": { "type": "latest" } },
  "default_policy": "allow",
  "network": { "type": "allowlist", "hosts": ["api.github.com", "codeload.github.com"] },
  "http_credentials": ["https://api.github.com"]
}

3. Vault を指定して Session を開始する

Credential は、Session の開始時に指定した Vault から取り出されます。Vault は、コンソールでは 新しい Session の Vault で、API では vault_ids で指定します。そのため、同じ Agent のバージョンを、ある Session ではある顧客のトークンで、次の Session では別の顧客のトークンで実行できます。

コードはキーを送らない

Function の中では、authorization Header のない普通のリクエストを送るだけです。

use subako_function_sdk::http::{self, Request};

let response = http::request(&Request::get("https://api.github.com/repos/subako-ai/subako-function-examples"))?;

const response = await fetch("https://api.github.com/repos/subako-ai/subako-function-examples");

resp, err := http.Get("https://api.github.com/repos/subako-ai/subako-function-examples")

Subako はリクエストを Grant のネットワーク設定と照合し、Session にある https://api.github.com 用の Credential を見つけて、その Header を付けて送ります。その Origin の Credential がなければ、リクエストはそのまま送られます。そのため Package「github」は、トークンがなくても公開リポジトリについての質問には答えられます。ただし、匿名のリクエストに適用される GitHub の低いレート制限の範囲内です。

知っておきたいルール

1 つの Credential が適用されるのは 1 つの Origin だけで、さらに Grant がその Origin を指定しているリクエストに限られます。ほかの Host へのリクエストには何も付きません。
別の Origin にリダイレクトされると、authorization Header と Cookie の Header は外されます。トークンがリダイレクトをたどって API の外に漏れることはありません。
Function が Credential の Header のどれかを自分で設定すると、リクエストは拒否されます。どちらかの値が黙って優先されることはありません。
1 つの Vault に保管できる Credential は、Origin ごとに 1 つです。Session の複数の Vault に同じ Origin の Credential がある場合、Subako はどれを使うかを推測せず、その Origin へのリクエストは失敗します。
リクエストは https でのみ、公開アドレスにのみ送られます。

Function を書かずに API を呼び出す

Platform package の http も同じルールに従います。ネットワークと Credential を設定して付与すれば、Agent が自分で API へのリクエストを組み立てられます。その場合もキーはモデルには見えず、Subako が付けます。ただ、呼び出す内容が決まっているなら、自分の Package を書くほうが適しています。入力を検証し、回答を整え、大きなレスポンスを Session Volume に置いておけるからです。