agent-tools

エージェントツール

AI コーディングエージェント向けの安全な CLI ラッパー — GitHub、オブザーバビリティ、データベース、Kubernetes、Azure プラットフォーム、Azure DevOps、ログ、OpenCode セッションに対応します。

完全なドキュメント：API リファレンス、設定、認証情報のセットアップについては、README をお読みください。

実行方法（重要）

bun <tool-name> を使ってツールを実行します（開発依存関係として @blogic-cz/agent-tools が必要です）。

bun gh-tool pr status
bun observability-tool trace get <trace-id> --env local
bun k8s-tool pods --env test
bun db-tool sql --env local --sql "SELECT 1"

生の kubectl、gh、psql、az は絶対に実行しないでください — 認証情報ガードによってブロックされます。

従来の agent-tools-* 形式のバイナリ名（例：bun gh-tool）も引き続き動作しますが、短い形式を推奨します。

ツールの概要

ツール	説明	ヘルプ
gh-tool	GitHub CLI ラッパー — PR、イシュー、ワークフロー、チェック、レビュー、マージ	bun gh-tool --help
observability-tool	LGTM ラッパー — Tempo トレース、Loki ログ、Prometheus メトリクス	bun observability-tool --help
db-tool	データベースクエリツール — SQL の実行、スキーマの調査	bun db-tool --help
k8s-tool	Kubernetes ツール — 設定に基づくコンテキスト解決機能付き kubectl	bun k8s-tool --help
az-tool	Azure プラットフォームツール — vm、webapp、storage、aks、acr（読み取り専用）	bun az-tool --help
azdo-tool	Azure DevOps ツール — パイプライン、ビルド、リポジトリ（読み取り専用）	bun azdo-tool --help
logs-tool	アプリケーションログ — ローカルおよびリモート（k8s ポッド）のログを読み取り	bun logs-tool --help
session-tool	OpenCode セッションブラウザー — セッション履歴の一覧表示、読み取り、検索	bun session-tool --help
api-tool	オペレーターが発行したケイパビリティを使用する JSON REST クライアント	api-tool request --help
api-proxy	上流 REST の認証情報を保持する独立したオペレーターサービス	api-proxy --help

ツールの優先順位

1. CLI ツール（推奨） — より効率的で、コンテキストを読み込まず、すべての機能を提供します
2. MCP ツール（フォールバック） — CLI の代替手段がない場合に使用します

生の gh より bun gh-tool、生の psql より bun db-tool、生の kubectl より bun k8s-tool を常に優先してください。ラッパーはセキュリティガードレール、監査証跡、プロジェクト固有の設定を提供します。

一貫性：ツールはエラーレスポンスに hint、nextCommand、retryable フィールドを含め、失敗からの復旧を支援します。コマンドが失敗した場合は、必ずこれらのフィールドを確認してください。

クイックリファレンス

api-tool（REST サービス）

オペレーターが承認した REST プロファイルには、api-tool request --config ./api-client.json --profile sample --path /v1/items を使用します。このソースチェックアウトでは、同じフラグを指定して bun run api-tool request を使用してください。クライアント設定に含まれるのは、プロキシのオリジンと呼び出し元のケイパビリティのみです。api-proxy を設定または運用する前に、REST プロキシのセットアップをお読みください。プライベートストアとポリシーには、要求元エージェントの権限範囲外にある別個のサービス ID が必要です。

gh-tool（GitHub）

bun gh-tool pr status                  # View PR status for current branch
bun gh-tool pr view --pr 123           # View PR details
bun gh-tool pr checks --pr 123         # Check CI status
bun gh-tool pr checks --pr 123 --watch # Watch CI until complete
bun gh-tool pr checks-failed --pr 123  # Get failed check details
bun gh-tool pr merge --pr 123 --strategy squash --delete-branch --confirm
bun gh-tool pr threads --pr 123 --unresolved-only  # Review comments
bun gh-tool pr reply --pr 123 --comment-id 456 --body "Fixed"
bun gh-tool pr resolve --thread-id 789
bun gh-tool pr create --base test --title "feat: X" --body "Description"
bun gh-tool pr review-triage --pr 123  # Combined info, threads, checks
bun gh-tool pr reply-and-resolve --pr 123 --comment-id 456 --thread-id 789 --body "Done"

bun gh-tool workflow list                              # List recent workflow runs
bun gh-tool workflow view --run 123                    # View run details with jobs/steps
bun gh-tool workflow watch --run 123                   # Block until run completes (NO sleep-polling!)
bun gh-tool workflow logs --run 123                    # Fetch logs (failed jobs by default)
bun gh-tool workflow job-logs --run 123 --job "build"  # Clean parsed logs for specific job
bun gh-tool workflow rerun --run 123                   # Rerun failed jobs
bun gh-tool workflow cancel --run 123                  # Cancel in-progress run

sleep N && workflow list/jobs/view は絶対に使用しないでください — 代わりに workflow watch --run N を使用してください。認証情報ガードは、agent-tools コマンドによる sleep を使ったポーリングをブロックします。

bun gh-tool issue list --state open --limit 30
bun gh-tool issue view --issue 123
bun gh-tool issue close --issue 123 --reason completed --comment "Done"
bun gh-tool issue reopen --issue 123
bun gh-tool issue comment --issue 123 --body "text"
bun gh-tool issue edit --issue 123 --title "New title" --add-labels bug
bun gh-tool issue triage --issue 123 --verbosity full --format json

observability-tool（LGTM）

bun observability-tool trace get 0b7bdf0dde1c55458364ba5588a8075e --env local
bun observability-tool trace logs 0b7bdf0dde1c55458364ba5588a8075e --env local --limit 100
bun observability-tool metrics query 'up' --env local --start now-1h --end now --step 60

db-tool（データベース）

bun db-tool sql --env local --sql "SELECT * FROM users LIMIT 5"
bun db-tool sql --env test --sql "SELECT count(*) FROM organizations"
bun db-tool schema --env local --mode tables          # List tables
bun db-tool schema --env local --mode columns --table users # Show table schema

環境には任意の文字列（例：local、test、prod）を指定できます。設定の defaultEnvironment を設定すると、毎回 --env を指定する必要がなくなります。

データベースの前提条件は、プロファイルレベル（database.default.vpn）または環境レベル（database.default.environments.prod.vpn）で設定できます。環境の vpn／prerequisites はプロファイルの前提条件を置き換えます。prerequisites: [] を指定すると、継承が無効になります。DB コマンドは、VPN の前提条件に接続する前に、直接アクセスを試みます。

k8s-tool（Kubernetes）

bun k8s-tool kubectl --env test --cmd "get pods -n test-ns"
bun k8s-tool kubectl --env prod --cmd "logs <pod> --tail=100"
bun k8s-tool kubectl --env test --cmd "describe pod <pod>"
bun k8s-tool pods --env test                     # List pods
bun k8s-tool logs --pod <pod> --env test --tail 50 # Fetch logs
bun k8s-tool describe --resource pod --name <pod> --env test
bun k8s-tool exec --pod <pod> --exec-cmd "ls -la" --env test
bun k8s-tool top --env test                      # Show resource usage

az-tool（Azure Platform）

bun az-tool subscription                       # Which subscription am I pinned to?
bun az-tool groups                             # List resource groups
bun az-tool resources --group my-rg            # List resources in a group
bun az-tool cmd --cmd "vm list"
bun az-tool cmd --cmd "webapp show --name my-app --resource-group my-rg"
bun az-tool cmd --cmd "acr repository list --name my-registry"

読み取り専用です。サブスクリプションは azurePlatform 設定プロファイルで固定されており、--subscription は拒否されます。変更を伴う動詞、不明な動詞、認証情報の読み取り（keyvault secret show、storage account keys list、get-access-token）、シェル構文はすべてブロックされます。一方、keyvault secret list などのメタデータ読み取りは許可されます。prod／production をキーとするプロファイルでは、--profile を明示的に指定する必要があります。安全性モデルの詳細については、az-tool スキルを読み込んでください。

azdo-tool（Azure DevOps）

bun azdo-tool cmd --cmd "pipelines list"
bun azdo-tool cmd --cmd "pipelines show --id 123"
bun azdo-tool cmd --cmd "pipelines runs list --top 5"
bun azdo-tool cmd --cmd "pipelines runs show --id 456"
bun azdo-tool build summary --build-id 456      # Job status & duration
bun azdo-tool build timeline --build-id 456     # Full event timeline
bun azdo-tool build failed-jobs --build-id 456   # Just failures
bun azdo-tool build logs --build-id 456          # List available logs
bun azdo-tool build log-content --build-id 456 --log-id 78

logs-tool（アプリケーションログ）

bun logs-tool list --env local          # List available log files
bun logs-tool read --env local --file app.log  # Read specific log
bun logs-tool read --env test --file app.log --tail 50

session-tool（OpenCode セッション）

bun session-tool list                   # List recent sessions
bun session-tool read --session <session-id> # Read session messages
bun session-tool search "query"         # Search across sessions

設定

設定は、現在の作業ディレクトリから親ディレクトリをたどって agent-tools.json5（または agent-tools.json）を読み込みます。

設定の完全なリファレンス：https://github.com/blogic-cz/agent-tools#configuration

defaultEnvironment

設定ファイルのルートに defaultEnvironment: "test" を設定すると、すべてのコマンドで --env test を指定する必要がなくなります。安全のため、暗黙的な prod へのアクセスが検出された場合、ツールは明示的に失敗します。

認証情報ガード

このガードは、エージェントによる機密ファイルへのアクセスや、シークレットの漏えいを防ぎます。agent-tools.json5 の credentialGuard セクションで設定します。

ブロックされる操作：

• シークレットファイル（.env、.pem、.key、.ssh/ など）の読み取り
• 検出されたシークレット（API キー、トークン、パスワード）を含む書き込み
• 危険なシェルパターン（printenv、cat .env など）
• CLI の直接使用（gh、kubectl、psql、az）。ラッパーツールを使用する必要があります

認証

各ツールは個別に認証を行い、共通のトークンストアはありません。

ツール	認証
gh-tool	gh auth login または GITHUB_TOKEN 環境変数
observability-tool	設定の Grafana URL、および任意の tokenEnvVar トークン
k8s-tool	既存の kubectl コンテキスト（kubeconfig）
az-tool	az login セッション
azdo-tool	az login セッション
db-tool	設定の passwordEnvVar で定義された環境変数
logs-tool	認証不要。ローカルファイル、またはリモートアクセスには k8s-tool を使用
api-tool	呼び出し元の機能、およびクライアント設定のプロキシ HTTPS オリジン
api-proxy	サービス ID を分離した、保護されたオペレーター認証情報ストア