メインコンテンツへスキップ
見出し画像

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に移行してから安定しました。

 
 
面倒な作業をAIに任せる方法を試して書いてます。エンジニアじゃないけど、Claudeを使って通知・集計・レポートを自動化中。手順は全部公開。

あなたへのおすすめ