Amazon Q Developer CLI の「コンテキストフック」が非推奨になっていたので、カスタムエージェントのフックに移行してみた
いわさです。
Aamzon Q Developer CLI にはコンテキストフックという機能がありました。
会話前に事前にエージェントがコマンドを実行し、その結果をコンテキストとして利用させることができるものです。ブログで紹介したことがあります。
実は 2025 年 9 月 17 日から、このコンテキストフック機能が非推奨になりました。
Document history for Amazon Q Developer User Guide - Amazon Q Developer より
ただし、コマンドを実行した動的コンテキストの注入ができなくなるわけではありません。
このコンテキストフックは非推奨となりましたが、替わりにカスタムエージェントのフック機能への移行が推奨されています。
カスタムエージェントは 2025 年 7 月 31 日に追加されたエージェントをカスタマイズして事前定義しておける機能です。
このカスタムエージェントを定義する際に JSON ファイルを使うのですが、その中に従来のコンテキストフックと同様の機能があります。
本日はこの機能を実際に構成して使ってみたので紹介します。
/context hooks コマンドは警告がでる
コンテキストフックの公式ドキュメントにアクセスしてみると、非推奨になったのでカスタムエージェントに移行してねと記述されています。
実際に Amazon Q Developer 上では/context hooks
コマンドがまだ存在しているのですが、実行したところ次のように非推奨である旨が表示されます。
> /context hooks
The /context hooks command is deprecated.
Configure hooks directly with your agent instead: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md#hooks-field
また、コンテキストフックを追加するサブコマンドも、本日時点ではもう使えなくなっていました。
非推奨というか実質使えなくなったと考えて良いと思います。
> /context hooks add
error: unexpected argument 'add' found
カスタムエージェントのフックを使う
ということでカスタムエージェントを定義して、そこにフックを移行しましょう。
カスタムエージェントは次のコマンドで実行が出来ます。
> /agent create --name hoge0923agent
Agent hoge0923agent has been created successfully
Changes take effect on next launch
>
そうすると JSON ファイルでカスタムエージェントの定義が出来ます。
その場で編集しても良いですし、~/.aws/amazonq/cli-agents/
に保存される構成ファイルを変更してもどちらでも OK なのですが、ポイントとしては次のhooks
を定義することです。
{
"$schema": "https://raw.githubusercontent.com/aws/amazon-q-developer-cli/refs/heads/main/schemas/agent-v1.json",
"name": "hoge0923agent",
"description": "",
"prompt": null,
"mcpServers": {},
"tools": [
"*"
],
"toolAliases": {},
"allowedTools": [],
"resources": [
"file://AmazonQ.md",
"file://AGENTS.md",
"file://README.md",
"file://.amazonq/rules/**/*.md"
],
"hooks": {
"agentSpawn": [
{
"command": "git branch --show-current"
}
],
"userPromptSubmit": [
{
"command": "git status --porcelain",
"timeout_ms": 5000,
"cache_ttl_seconds": 30
}
]
},
"toolsSettings": {},
"useLegacyMcpJson": true,
"model": null
}
設定可能なのはコンテキストフックの時と同様で、agentSpawn
がエージェント起動後の初回会話時のみ実行されるコマンド、userPromptSubmit
は会話のたびに実行されるコマンドです。同じですね、そのままスムーズに移行出来そうです。
今回は公式ドキュメントの設定例を参考に Git コマンドの結果をコンテキストとして実行するものを設定しました。なんでも良いのですが。
カスタムエージェントを指定して起動してみましょう。
% q chat --agent hoge0923agent
✓ MicrosoftLearn loaded in 1.50 s
✓ GitHub loaded in 2.43 s
✓ awslabs.aws-documentation-mcp-server loaded in 2.57 s
⢠⣶⣶⣦⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣤⣶⣿⣿⣿⣶⣦⡀⠀
⠀⠀⠀⣾⡿⢻⣿⡆⠀⠀⠀⢀⣄⡄⢀⣠⣤⣤⡀⢀⣠⣤⣤⡀⠀⠀⢀⣠⣤⣤⣤⣄⠀⠀⢀⣤⣤⣤⣤⣤⣤⡀⠀⠀⣀⣤⣤⣤⣀⠀⠀⠀⢠⣤⡀⣀⣤⣤⣄⡀⠀⠀⠀⠀⠀⠀⢠⣿⣿⠋⠀⠀⠀⠙⣿⣿⡆
⠀⠀⣼⣿⠇⠀⣿⣿⡄⠀⠀⢸⣿⣿⠛⠉⠻⣿⣿⠛⠉⠛⣿⣿⠀⠀⠘⠛⠉⠉⠻⣿⣧⠀⠈⠛⠛⠛⣻⣿⡿⠀⢀⣾⣿⠛⠉⠻⣿⣷⡀⠀⢸⣿⡟⠛⠉⢻⣿⣷⠀⠀⠀⠀⠀⠀⣼⣿⡏⠀⠀⠀⠀⠀⢸⣿⣿
⠀⢰⣿⣿⣤⣤⣼⣿⣷⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⢀⣴⣶⣶⣶⣿⣿⠀⠀⠀⣠⣾⡿⠋⠀⠀⢸⣿⣿⠀⠀⠀⣿⣿⡇⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⢹⣿⣇⠀⠀⠀⠀⠀⢸⣿⡿
⢀⣿⣿⠋⠉⠉⠉⢻⣿⣇⠀⢸⣿⣿⠀⠀⠀⣿⣿⠀⠀⠀⣿⣿⠀⠀⣿⣿⡀⠀⣠⣿⣿⠀⢀⣴⣿⣋⣀⣀⣀⡀⠘⣿⣿⣄⣀⣠⣿⣿⠃⠀⢸⣿⡇⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠈⢿⣿⣦⣀⣀⣀⣴⣿⡿⠃
⠚⠛⠋⠀⠀⠀⠀⠘⠛⠛⠀⠘⠛⠛⠀⠀⠀⠛⠛⠀⠀⠀⠛⠛⠀⠀⠙⠻⠿⠟⠋⠛⠛⠀⠘⠛⠛⠛⠛⠛⠛⠃⠀⠈⠛⠿⠿⠿⠛⠁⠀⠀⠘⠛⠃⠀⠀⠘⠛⠛⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠿⢿⣿⣿⣋⠀⠀
⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⠿⢿⡧
╭─────────────────────────────── Did you know? ────────────────────────────────╮
│ │
│ You can execute bash commands by typing ! followed by the command │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
/help all commands • ctrl + j new lines • ctrl + s fuzzy search
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 You are chatting with claude-sonnet-4
[hoge0923agent] > こんにちは
✗ agentSpawn "git branch --show-current" failed with exit code: 128, stderr: fatal: not a git repository (or any of the parent directories): .git)
✗ 0 of 1 hooks finished in 0.08 s
✗ userPromptSubmit "git status --porcelain" failed with exit code: 128, stderr: fatal: not a git repository (or any of the parent directories): .git)
✗ 0 of 1 hooks finished in 0.09 s
> こんにちは!Amazon Q です。AWS や開発に関することでお手伝いできることがあれば、お気軽にお聞かせください。
カレントディレクトリで Git を管理していないのでコマンドエラーが出ていますが、カスタムエージェントのhooks
に定義したコマンドが実行されていることがわかりますね。
さいごに
本日は Amazon Q Developer CLI の「コンテキストフック」が非推奨になっていたので、カスタムエージェントのフックに移行してみました。
リリースから4ヶ月で使えなくなってしまいましたが、移行先のカスタムエージェントが互換性ある形でフック機能を持っているので運用上の問題はなさそうですね。良かった。