運用のヒント

ここには、単独のガイドにきれいに収まらないけれど頻繁に出てくる運用テクニックを集めました。各ヒントは短く、Ankole の実際の動作に根ざしており、初めて苦労して発見するよりもコストがかかりません。

ローカルで pretty モードのログを読む

control plane は既定で構造化 JSON ログを出力します — 取り込みには向きますが読みにくい。ローカル開発では、devkit の pretty printer にパイプします：

bun run dev   # 1 つのターミナルで
bun run kit logs pretty < /path/to/log-stream   # またはログファイルをパイプする

本番では ANKOLE_LOG_FORMAT=json のままにし、書式設定はログインジェスターに任せます。pretty printer はローカル用の便利機能であり、本番設定ではありません。

バグ調査の前にログレベルを絞る

ANKOLE_LOG_LEVEL の既定値は info です。特定の再現のために debug に下げ、終わったら戻します — debug のままのデプロイはうるさく、遅くなります。有効な値は debug | info | warning | error で、無効な値はブート時に拒否され、黙って無視されることはありません。

ターミナルなしでアクティベーションコードを取得する

bun dev（または control-plane コンテナ）のターミナルが見えず、セットアップページがコードを要求する場合：

bun run kit show bootstrap-activation-code          # ローカル
docker compose logs control-plane | grep "SETUP ACTIVATION CODE"   # Compose
kubectl -n ankole logs deployment/ankole-control-plane -c control-plane | grep "SETUP ACTIVATION CODE"   # Helm

データベースからコードを推測しないでください — セットアップフローが実際に使う source から読み取ります。

model profile スロットをダイヤルとして扱う

8 つの組み込み Agent profile スロット、primary、light、heavy、coding、vision_fallback、web_search、web_fetch、image_generate は、それぞれがダイヤルです：

agent が主に短い質問に答えるときは primary を安い model に下げ、品質が cost より重要なら上げます。
light には本当に安くて速いものをバインドします — これは高頻度・低リスクの経路のために存在します。
agent が画像を見る場合にだけ vision_fallback を設定します。それ以外は未バインドのままにしてスロットを節約します。
web_search と web_fetch は独立しています — agent が web に触れる必要があるときだけバインドします。
Brain の検索モデルは Agent profile ではなく、AppConfigure で一度設定します。brain.embedding_model はすべての Agent のベクトル検索に適用され、brain.rerank_model は rerank に適用されます。embedding モデルが空の場合はベクトル検索が無効になり、rerank モデルが空の場合は融合後の順序を保ちます。詳しくは Brain を参照してください。

「遅い」と感じる agent は、実際に行っている仕事に対して重すぎる primary がバインドされていることがよくあります。

環境変数で credential をローテーションする

worker 環境の変更は、実行中の現在の Turn ではなく次の Turn で反映されます。つまり：

Console の 環境変数 に新しい値を入力して保存します。
進行中の Turn を完了させます — その Turn はすでに自分の環境を持っています。
新しいメッセージを送って、新しい値が反映されていることを確認します。

保存したときに実行中だった Turn から secret の変更を判断しないでください。その Turn は新しい値を見ません。

暗号化された値は必要なときだけ表示する

credential をローテーションするには置き換え値を入力します。古い値を確認するためだけに表示しないでください。問題を診断するために現在値を調べる必要があるときだけ表示を選択します。

詰まった Turn から回復する

詰まっているように見える Turn は、たいてい Ankole ではなく model か provider を待っています。何かをキャンセルする前に：

/ai-gateway/conversations で Turn の最近の model call を確認します — 長い間隔があれば provider がボトルネックです。
worker ログで実行中の tool call を確認します — 遅い tool は詰まった Turn のように見えます。
Turn が本当に固まっている場合だけ、agent の session を導くか、Turn をタイムアウトさせます。background job のキャンセルは POST /background-agent-jobs/:id/cancel で、実行中の Turn は完了まで走らせます。

積極的にキャンセルすることが、operator が半分だけ完了した副作用を作る方法です。

binding を静かに無効化する

DELETE /agents/:agent_uid/signal-bindings/:binding_name は無効化であり、ハード削除ではありません — 設定は回復可能なままです。agent を channel 内で沈黙させたいが設定は失いたくない場合（失効した credential、休暇、インシデント）に使います。再び有効にするには PATCH を使います。

アップグレード前には毎回バックアップする

Helm のロールバックはデータベース migration を逆転しません。アップグレード前の 2 分間の pg_dump が、「ロールバックした」と「バックアップからリストアして 1 日失った」の違いです。コマンドはバックアップとリストアを参照してください。

正しい durable ドキュメントを調整する

Agent の責任が不明確なときは MISSION.md を編集します。コミュニケーションや判断が間違っているときは SOUL.md を編集します。web ページ、スライド、ドキュメント、チャートに一貫したビジュアルスタイルがないときは DESIGN.md を編集します。各ファイルは 1 つの関心事を所有するので、ビジュアルデザインシステムに振る舞いのルールを入れないでください。

DingTalk では agent ごとに 1 つの bot

DingTalk は厳しい制約を強制します。agent ごとに有効な binding は 1 つ、clientId ごとに agent は 1 つです。スケールアウトするなら、agent ごとに 1 つの bot を計画してください。同じ agent への 2 つ目の binding は dingtalk_binding_already_exists で失敗し、別の agent での clientId 再利用は dingtalk_app_already_bound で失敗します。セットアップは Quickstart を参照してください。

Teams は常にパブリックエンドポイントを必要とする

Teams は長い接続ではなく、Bot Framework の webhook 呼び出しとして配信します。Teams の bot が動かなくなったら、最初に確認するのはパブリック HTTPS エンドポイントです。証明書の期限切れ、DNS の変更、ingress のダウンタイムはすべて「bot が返答しなくなった」ように見えます。Lark、Slack、DingTalk は長い接続を使うため、短時間のエンドポイントの瞬断を乗り切れますが、Teams は乗り切れません。

次のステップ

Console のインターフェースリファレンスについては、Console API リファレンスを読んでください。
環境のつまみについては、環境変数を読んでください。
kit のコマンドについては、kit CLI リファレンスを読んでください。