Console API リファレンス

AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/console-api/index.md にあります。ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。

このページは Console API の REST リファレンスです。認証 gate、/api/v1 配下の route、各 route が実行する permission action を解説します。

最も重要な性質を先に述べます。Console API は stateless で bearer 認証を用い、すべての request で呼び出し元が依然として active な管理者であることを再確認します。この仕事を引き受ける session cookie はなく、無効化された管理者は次回のログイン時ではなく即座に機能しなくなります。

/api/v1 配下のすべての route は :console_api pipeline と RequireConsoleAccessToken plug を通ります。plug は次に挙げる 3 つの検査を、すべて必須として独立に実行します。

1. 形式が正しい Authorization: Bearer ヘッダ。
2. 検証に通る console JWT。
3. JWT が指す Principal が依然として active な管理者であること。

成功時は Principal と claims を conn assigns に保存して、後続の policy 検査に渡します。いずれかの検査が失敗すると 401 で停止します。これは、session と CSRF がブラウザ向け surface に対して行うことを、request 単位・cookie なしで実現したものです。これらの route へのより弱い第二の経路は存在しません。

configuration の surface

configuration は controller 単位ではなく、「何を構成するか」で整理されています。運用者が実際に操作する surface は次のとおりです。

Provider と model アクセス

稼働中の agent には背後に model が必要です。運用者は AIGateway の provider surface と agent の model profile を通じてそれを接続します。

Provider の credential は暗号化された pool メンバーとして control plane に置かれ、agent の環境には決して置かれません。model profile は agent を provider と model に bind します。AIGateway はその provider 内で健全なメンバーを選択し、projection は安全な account 情報、健康状態、rate limit データ、使用量だけを返します。

Agent とその能力

agent は、運用者が他のすべてを構成する際の単位です。

signal routing rule

signal routing rule（API schema では Signal Binding）は provider adapter を Agent に接続し、共有された仕事が Agent に届くようにします。

binding を無効にすると、binding を削除せずに、新しい signal が agent を wake しなくなります。

Agent Library の能力

Agent Library は agent ができること、つまり plugin と skill です。Console は 2 つの scope を公開します。1 つはグローバルな既定値、もう 1 つは agent 単位の override です。

能力はまずグローバルに有効化され、その後 Agent ごとに狭めたり広げたりできます。Skill 教訓は Skill source を変更せずに、1 つの Agent へ追加の作業指針を渡します。一覧には証拠と廃止履歴も含まれます。廃止された教訓は配信されず、人が取り消した内容は Dreaming の再学習禁止 list に残ります。lifecycle と制限については Skill 教訓 を参照してください。

環境変数（WorkerEnv）

Agent Computer Worker は、API key や token などの環境変数を必要とすることがあります。Console はこの機能を 環境変数 と呼びます。API はリソース名として WorkerEnv を保持します。

復号は独立した audit 対象の操作です。一覧表示と読み取りは metadata を返し、secret の値は返しません。worker が環境を受け取るのは turn の開始時だけです。変更は次の turn で反映され、実行中の turn には反映されません。

Control Plane Plugin

Control Plane Plugin は、signals adapter のように、control plane 自身の動作を変えるファーストパーティ拡張です。

Identity provider と AppConfiguration

AppConfiguration は運用者が管理する設定、つまり宣言済みの Ankole.AppConfigure key のためのものです。bootstrap configuration（process 起動時の事実と credential）は、プロジェクトの境界の要求どおり、環境変数または secret mount に置かれ、ここからは除外されます。

読み取り用の surface

configuration に加えて、Console はシステムの残りの部分に対する observability の経路でもあります。既に解説した各 subsystem は、ここに読み取り用の surface を持ちます。

• 処理中の Agent: /agents/:agent_uid/sessions。Agent ごとの cron schedule と checkback の管理。一覧エンドポイントはインストール全体で、agent フィルターを取ります。
• Worker: /agent-computer-workers。worker ごとの file のアップロード、移動、一覧表示。
• Job: /background-agent-jobs（一覧表示、読み取り、cancel）。
• AI の活動: /ai-gateway/conversations。conversation ごとの message。
• Principal と AuthZ: /principals、/principal-groups、/permission-grants。Principal と AuthZ ページの permission model に対応します。

ここに含まれないものについて

/webhooks/* と /api/v1/ai-gateway/* の route は、意図的に console_api の下にありません。webhook の入口は管理者ではなく provider を認証します。AIGateway の runtime API は、ライブな AI 呼び出しのために agent または admin token を検証します。Console は運用者の configuration surface であり、deployment instance の動作を変更するために admin の bearer token を信頼する唯一の surface です。

次のステップ

• Console が構成する runtime surface については、AIGateway API、SignalsGateway、Actor Runtime をお読みください。
• Console 自身が従う permission model については、Principal と AuthZ をお読みください。
• 新しい deployment instance を構成するには、クイックスタートの deployment セクション をお読みください。