運用のヒント
AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/tips/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。
このページでは、個別の機能ガイドには収まりきらないものの、日々の運用で頻繁に役立つ実践的なテクニックをまとめています。いずれも Ankole の実際の動作仕様にもとづいており、トラブル時に手探りで原因を追う手間を大きく減らせます。
ローカルで pretty モードのログを読む
コントロールプレーンは既定で構造化 JSON ログを出力します。ログ基盤への取り込みには最適ですが、そのまま目視で読むには向きません。ローカル開発時は、devkit の pretty printer にパイプして整形表示できます。
bun run dev # 1 つのターミナルで
bun run kit logs pretty < /path/to/log-stream # またはログファイルをパイプする
本番環境では構造化 JSON のままログ収集基盤へ送り、ローカル環境での確認にだけ pretty printer を使ってください。
バグ調査の前にログレベルを絞る
ANKOLE_LOG_LEVEL の既定値は info です。特定の事象を再現させて詳しく調べたいときだけ debug に変更し、調査が終わったら必ず元の値へ戻してください。debug のまま運用を続けるとログ出力が膨大になり、パフォーマンス低下につながります。指定可能な値は debug | info | warning | error の 4 つのみで、それ以外の不正な値は黙って無視されることなく起動時にエラーとして拒否されます。
ターミナルなしでアクティベーションコードを取得する
初回セットアップ画面でアクティベーションコードの入力を求められたものの、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
データベースの中身を直接覗いて推測しようとせず、セットアップフロー自身が参照している正規の出力経路から確認してください。
model profile スロットをダイヤルとして扱う
Agent に用意されている 7 つの組み込みモデルプロファイル枠(primary、light、heavy、vision_fallback、web_search、web_fetch、image_generate)は、用途とコストを調整するためのダイヤルとして使い分けます。
primary: 短い質疑応答が中心の Agent なら軽量で安価なモデルに抑え、コストよりも推論品質が重視される役割なら上位モデルを割り当てます。light: 高頻度・低リスクの内部処理で使われるため、本当に高速で安価なモデルをバインドしてください。vision_fallback: Agent に画像を読み取らせる場合にのみ設定し、不要であれば未バインドのままにして枠を空けておきます。web_searchとweb_fetch: それぞれ独立しているため、外部 Web へのアクセスが必要な Agent にだけバインドします。- Brain の検索モデル: サイト単位の
brain.embedding_modelは AppConfigure で設定して全 Pod 共通のベクトル検索に使い、再ランキング用のrerankスロットは Console → Model Profiles(Site -> Pod -> ankole_brain)で設定します。Embedding モデルが未設定の場合はベクトル検索が無効になり、rerankが未設定の場合は RRF 融合後の順位がそのまま使われます。詳しくは Brain を参照してください。
「応答が遅い」と感じる Agent は、実際の業務内容に対してオーバースペックな重量級モデルが primary に割り当てられているケースが少なくありません。
環境変数で credential をローテーションする
Worker 環境変数の変更が反映されるのは、現在進行中の Turn ではなく次の Turn からです。ローテーションは次の手順で行います。
- Console の 環境変数 画面で新しい値を入力して保存します。
- その時点で実行中だった Turn があれば、そのまま最後まで完了させます(すでに起動時の古い環境変数を保持しているためです)。
- 新しくメッセージを送り、更新後の値が使われていることを確認します。
保存ボタンを押した瞬間に走っていた Turn の挙動を見て「シークレットが切り替わっていない」と判断しないでください。その Turn からはまだ新しい値は見えません。
暗号化された値は必要なときだけ表示する
認証情報をローテーションする際は、古い値をわざわざ画面に表示して確認するのではなく、新しい値をそのまま上書き入力してください。表示 機能を使うのは、トラブルシューティングのために現在登録されている値をどうしても確認しなければならない場面だけに留めましょう。
詰まった Turn から回復する
一見フリーズしているように見える Turn も、実際には Ankole 内部の停止ではなく、上流モデルや Provider の応答待ち、あるいは時間のかかるツール実行中であることが大半です。強制キャンセルする前に、まず次の順で原因を切り分けてください。
/api/v2/ai-gateway/conversationsで直近のモデル呼び出し履歴を確認します。応答間隔が大きく空いていれば、ボトルネックは Provider 側にあります。- Worker のログで実行中のツール呼び出しを確認します。重いコマンドや外部通信を待つツールは、外からは Turn が詰まっているように見えます。
- 本当に処理がスタックしていると確認できた場合にのみ、対象 Session に steer 指示を送るかタイムアウトを待ちます。なお、Background Job を止める
POST /api/v2/background-agent-jobs/:id/cancelは、停止状態を記録した後に実行中の Turn へ中断を要求します。
原因を確認せずにすぐ強制キャンセルすると、外部サービスへの書き込みなどの副作用が中途半端な状態で残る原因になります。
binding を静かに無効化する
DELETE /api/v2/signal-bindings/:id はデータの完全削除ではなく**無効化(ソフト無効化)**として動作し、設定自体はいつでも復元可能な状態で残ります。認証情報の期限切れ対応、担当者の休暇中、インシデント発生時など、「設定を消さずにチャネル内での反応だけを一時的に止めたい」場面で活用してください。再開するときは PATCH で有効状態に戻せます。
アップグレード前には毎回バックアップする
Helm のロールバックを実行しても、すでに適用されたデータベースマイグレーションまでは自動で巻き戻りません。アップグレード作業の前には毎回、コントロールプレーンの PostgreSQL データベースおよび設定済みの専用 BASE_DB_URLS シャードデータベースに対して pg_dump を取得し、あわせてブートストラップシークレット(ANKOLE_SECRET_BASE、RELEASE_COOKIE、ANKOLE_FUNCTION_RUNTIME_TOKEN)も控えを保全してください。このわずか数分のひと手間が、「数分で切り戻せた」か「リストア復旧に丸一日費やした」かの分かれ目になります。具体的なコマンドは バックアップとリストア を参照してください。
正しい durable ドキュメントを調整する
Meta Ankole → Agents で目的に合ったドキュメントを編集します。Agent の担当範囲や成果物の基準、受け答えのトーン、判断姿勢を調整したいときは AGENTS.md を編集し、生成される Web ページ、スライド、ドキュメント、チャートのデザインに統一感を持たせたいときは DESIGN.md を編集します。2 つの契約ファイルはそれぞれ明確な責務を担っているため、DESIGN.md に行動ルールを混ぜたり、AGENTS.md に視覚トークンを書いたりしないでください。
DingTalk では agent ごとに 1 つの bot
DingTalk アダプターには、「1 Agent につき有効なバインディングは 1 つまで」「1 つの clientId に紐付けられる Agent は 1 体まで」という厳格な制約があります。複数の Agent を展開する場合は、Agent と同じ数の DingTalk ボットアプリを用意してください。同一 Agent に 2 つ目のバインディングを追加しようとすると dingtalk_binding_already_exists エラーになり、別の Agent で同じ clientId を使い回そうとすると dingtalk_app_already_bound エラーで拒否されます。セットアップ手順は Quickstart を参照してください。
Teams は常にパブリックエンドポイントを必要とする
Microsoft Teams は常時接続ストリームではなく、Bot Framework からの受信 Webhook 呼び出しでメッセージを届けます。そのため、Teams ボットが急に応答しなくなったときに真っ先に点検すべき箇所はパブリック HTTPS エンドポイントです。TLS 証明書の期限切れ、DNS レコードの変更、Ingress の瞬断はいずれも「ボットが急に黙り込んだ」という同じ症状として現れます。常時接続を使う Lark、Slack、DingTalk なら公開エンドポイントの短い瞬断をやり過ごせますが、Teams ではそのまま配信失敗に直結します。
次のステップ
- Console API の一覧と仕様については、Console API リファレンス を参照してください。
- 環境変数による設定項目については、環境変数 を参照してください。
kitCLI の各コマンドについては、kit CLI リファレンス を参照してください。