--- title: クイックスタート description: Organization を作り、agent version を公開し、最初の session を動かすまで — ターミナルと 1 回の HTTP 呼び出しで、最初から最後まで。 sidebar: order: 2 --- ここでの作業はすべてターミナルで行います。読み終えるころには、organization、workspace、公開済みの agent version、API key、そしてメッセージに応答する session が手元にあるはずです。 ## CLI をインストールする **macOS / Linux** ```bash curl --proto '=https' --tlsv1.2 -LsSf https://github.com/subako-ai/subako-cli/releases/latest/download/subako-cli-installer.sh | sh ``` インストーラは、`$XDG_BIN_HOME` が設定されていればそこに、なければ `~/.local/bin` に `subako` を配置します。確認してみましょう。 ```bash subako --version ``` ## Organization を用意する 1. **サインアップする** Organization は請求とアイデンティティの境界です。作成時は Free plan から始まり、試用のための 500 SC が付与されます — 有料 plan で何が増えるか、どう申し込むかは [Plan と請求](/ja/concepts/plans-and-billing) を参照してください。 ```bash subako cloud signup --org acme --name "Acme, Inc." ``` `--org` は organization の **handle** です。これが organization を識別するものであり、重複は許されず、URL にも現れ、organization が存在する限り変更できません。サインインの際に指定する名前でもあり — 次のステップの `subako login --org acme` も、それ以降のログインもすべて そうです — ずっと使い続けられるものを選んでください。`--name` は表示名にすぎず、こちらはいつでも変更できます。 このコマンドはローカルには何も保存しません。Organization が置かれる Core サーバー — 別のものを指定していなければ `https://api.us.cloud.subako.ai` — が表示され、次のステップではそこに サインインします。 2. **サインインする** サインインは OAuth のデバイス認可フローで行われます。CLI がコードを表示してブラウザを開き、承認すると credential が `~/.config/subako/credentials.json` に保存されます。 ```bash subako login --org acme ``` `--profile` を使うと、organization の handle とは別の名前でログインを保存できます — 複数の organization や、ステージングと本番のログインを並べて持つ方法です。`--server` は、既定の `https://api.us.cloud.subako.ai` 以外の Core サーバーにログインを向けます。保存された各 profile がどのサーバーに紐づいているかは `subako profile list` が表示します。 ```bash subako whoami ``` 3. **workspace を作る** あらゆる作業単位は workspace に属します — agent、skill、vault、API key、そしてそれらが動かす session です。`use` は選択内容を profile に記録するので、以降のコマンドに `--workspace` フラグは要りません。 ```bash subako workspace create --name production subako workspace use production subako workspace list ``` ## Agent を公開する 1. **model provider を選ぶ** Subako はあなたに代わってモデルを呼び出すため、version は provider を指定して公開します。どの workspace も最初から **platform provider** が見えています — こちらで設定済みで、あなた自身のキーは不要なので、まず はここから始めてください。 ```bash subako model-provider list ``` ```txt workspace: production (01a0877c-03d9-7823-b997-f42147b8b607) 01a07f90-238c-7de3-b55e-6fe53de063cf type=platform format=openai_responses label=Subako description=(none) model=crow label=Crow model=hawk label=Hawk model=sparrow label=Sparrow ``` 自前のものを何も作っていない workspace には、ちょうどこれだけが見えます — Subako の platform provider と、それが提供する 3 つのモデルです。クイックスタートを終えるにはこれで十分で、自分で作った provider はこの横に並びます。 この一覧から 2 つを控えておいてください。公開先となる **provider の id** と、その下にインデントされている **モデル id** のいずれかです。provider がどのモデル id を受け付けるかは、この一覧が正解です。 自分のアカウントで動かしたい場合は、自前の provider を作成します。キーはフラグではなく必ず標準入力から読まれるので、シェルの 履歴にもプロセス一覧にも残りません。 ```bash subako model-provider create \ --format anthropic \ --display-name "Anthropic production" \ --base-url https://api.anthropic.com < key.txt ``` `subako model-provider formats` は、このサーバーが受け付ける format を一覧します。Agent version は、その model が話す format と一致する format の provider に対してのみ公開できます。 2. **agent を作る** Agent は名前とアイデンティティにすぎません。設定そのものは持たず — それを持つのは version です。 ```bash subako agent create --name support-triage ``` Agent id が表示されます。これが `agent publish` に渡す引数です。あとから見直すには `subako agent list` を使います。 3. **version の設定ファイルを書く** `agent config-example` は、そのままで公開できる最小の設定を表示します。 サーバーを必要としないので、ほかに何も存在しないうちから編集を始められます。 例は format ごとに異なるので、選んだ provider の format を渡してください。 ```bash subako agent config-example --format openai_responses > agent.json ``` ```json agent.json { "system_prompt": "You are a helpful assistant.", "model": { "format": "openai_responses", "model": "your-model-id", "max_tokens": 8192, "context_window": 128000 } } ``` `your-model-id` を、provider の一覧にあるモデル id — たとえば `hawk` — に置き換えます。id は公開時ではなく session の実行時に検証されるので、本物をここに書いてください。 Grant — MCP サーバーと skill — は任意で、同じドキュメントに書きます。 provider はファイルではなく、公開時の `--model-provider` で指定します。 4. **公開する** ```bash subako agent publish \ --config agent.json \ --model-provider ``` Version はイミュータブルです。もう一度公開すると新しい version が作られ、新しい session は最新の live version に束縛されます。すでに動いている session は、束縛済みの version のままです。 :::warning モデル id は公開時には検証されません。誤った id は、version を公開したときではなく session が動いたときに判明します。 ::: ## Session を動かす ここから先は HTTP で、サインインしたのと同じ Core サーバーに対して行います — 以下の呼び出しでは既定の `https://api.us.cloud.subako.ai` です。別のサーバーに サインインした場合は、各 profile がどのサーバーに紐づいているかを `subako profile list` が表示します。 1. **API key を発行する** API key は、あなたのプロダクトが名乗るマシン用の credential です。そのシークレットは一度だけ表示され、二度と取得できません。 ```bash subako api-key mint \ --label "support-triage backend" \ --permission session.create \ --permission session.read \ --permission session.manage ``` ```txt minted api key support-triage backend (01a0877e-…) in workspace production (01a0877c-…) permissions: session.create, session.read, session.manage expires: (never) prefix: sbk_ak_4f50c2aa the secret below is shown once and cannot be retrieved again: sbk_ak_4f50c2aa8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` 最後の行 — `sbk_ak_…` のシークレット全体 — をコピーしてください。`prefix` ではありません。あれは `api-key list` でキーを見分けるためのラベルです。 以降の呼び出しは `SUBAKO_API_KEY` から読むので、いま入れておきます。 ```bash export SUBAKO_API_KEY=sbk_ak_4f50c2aa8XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX ``` これは `curl` の例のために、あなた自身が用意するシェル変数です。CLI がこれを読むことはありません — `subako` は API key ではなく、`subako login` で保存されたログインで認証します。 このサーバーがキーに与えられる権限は `subako api-key permissions` が一覧します。動作する範囲でもっとも狭い組み合わせを与えてください — [Permission](/ja/reference/permissions) を参照。 2. **session を作成する** ```bash curl -X POST https://api.us.cloud.subako.ai/v1/sessions \ -H "Authorization: Bearer $SUBAKO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id": "", "display_name": "ticket-4192"}' ``` ```json { "id": "01a0877f-d3b3-7e73-9eed-a16caee8cff7", "status": "idle", "session_token": "sbk_st_...", "session_token_expires_at": "2026-09-09T19:48:16Z" } ``` `session_token` はこの session ひとつに限定された credential で、permission は何も持たず、一度だけ表示されます。ブラウザのタブに渡すの はこれで、API key はサーバー側に置いたままにします。`session_token_expires_at` で失効するので、追加分は API key を使って `POST /v1/sessions/{session_id}/tokens` から発行します。 残り 2 つのステップでは session の `id` とこのトークンが必要になるので、どちらも控えておいてください — これもあなた自身のシェル変数です。 ```bash export SESSION_ID= export SUBAKO_SESSION_TOKEN= ``` どの呼び出しがどちらの credential を取るかに注意してください。session の作成は API key の仕事で、session の中で起きることはすべて session token の仕事です。 3. **メッセージを送る** ユーザーのターンを追記すると run が始まります。 ```bash curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \ -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \ -H "Content-Type: application/json" \ -d '{"type": "input", "text": "Summarize ticket 4192."}' ``` 応答には、これによって始まった run が示されます。 ```json { "run_id": "01a08780-611d-7290-a9a0-e8a27b64ad9c", "outcome": "new_run" } ``` 4. **動きを見る** ストリームはログの先頭から追尾するので、すでに終わった run には送るものが残っていません。`after_seq=0` を渡すと、session を最初の event から再生したうえで、そのままライブに続きます。 ```bash curl -N "https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events/stream?after_seq=0" \ -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" ``` Event は SSE として届き、それぞれに再接続の再開点となるシーケンス番号が 付いています。Run は `run_completed`、`run_failed`、`run_cancelled` のいずれかで終わりです。 ```txt id: 2 event: message_user data: {"seq":2,"type":"message_user",...} id: 5 event: message_assistant data: {"seq":5,"type":"message_assistant",...} id: 6 event: run_completed data: {"seq":6,"type":"run_completed","run_id":"01a08780-..."} ``` そのあともストリームは次の run を待って開いたままになります — `curl` は自分では終了しないので、`run_completed` を見たら中断してください。 ## 次のステップ **[Session](/ja/concepts/sessions)** Run、event ログ、そして何が何に束縛されるか。 **[Client tool](/ja/guides/client-tools)** あなたのアプリだけが実行できる関数を agent に与える。 **[Vault](/ja/concepts/vaults)** Credential を見せずに、agent を本物のシステムへ到達させる。 **[Skill](/ja/concepts/skills)** 手順を一度まとめて、agent version に grant する。