
Claude Agent SDK `query()` 実践ガイド — Slack Bot実装で踏んだ地雷と設計判断
26日間・144リクエスト・84回の再接続・2件のAPIエラー。Claude Agent SDKでSlack常駐AIボットを24時間運用して得た、ドキュメントに書いていない知見をまとめました。
この記事で得られること
・query() のストリーミングで返ってくるメッセージ型の実態(公式型定義がないため、実観測ベース)
・resume(セッション継続)が失敗する条件と対処法
・permissionMode: "bypassPermissions" のセキュリティリスクと制御手段
・Socket ModeがLLM処理中に切断される問題と解決策
・26日間の運用データ(コスト分布、再接続頻度、エラー事例)
対象読者
・Claude APIまたはAgent SDKを触ったことがある開発者
・Slack Botを作ったことがあり、LLMと統合したい人
・自律型AIエージェントの構築に興味がある人
1. なぜサブプロセスではなくSDKなのか
当初は claude -p "質問" をサブプロセスで呼ぶ方式で実装しました。2週間で断念した理由:
【サブプロセス方式 vs SDK query()】
・セッション継続: 不可能(毎回新規) → resumeで継続可能
・起動オーバーヘッド: 2-3秒/回 → 初回のみ
・コスト追跡: stdout解析が必要 → total_cost_usdフィールドで取得
・中断制御: killシグナル → AbortController
・stderr: 混在して不安定 → 専用イベントで分離
設計判断: サブプロセス方式は「とりあえず動く」が「運用できない」。SDKに移行してから安定しました。