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

【完全版】Claude Agent SDK設計の極意|Anthropic流「Bash is All You Need」の哲学を徹底解説

    「AIエージェントを作りたいけど、どのフレームワークを使えばいいかわからない」

    「Claude Codeは使っているけど、自分でエージェントを構築する方法がわからない」

    そんな悩みを持つ方に朗報です。Anthropicが公開した技術セッション「Building agents with the Claude Agent SDK」では、エージェント構築の核心的なノウハウが惜しみなく共有されました。

    本記事では、このセッションの内容を完全解説。Anthropicのエンジニアが実際に使っている設計哲学から、プロトタイピングの実践手法まで、エージェント開発に必要なすべてを網羅します。

    画像

    Claude Agent SDKとは?なぜClaude Codeがベースなのか

    Claude Agent SDKは、Claude Codeのエージェントハーネス(制御機構)を汎用化したツールキットです。

    「なぜコーディングツールがベースなの?」と思われるかもしれません。実は、Anthropic社内で興味深い現象が起きていました。

    非エンジニアもClaude Codeを使い始めた

    Claude Codeをリリースした当初、エンジニアだけが使うと想定していました。しかし実際には、財務チーム、データサイエンスチーム、マーケティングチームまでもがClaude Codeを活用し始めたのです。

    なぜでしょうか?答えはBashツールにあります。

    Bashツールがあれば、エージェントは:

    • ファイルの検索・編集ができる

    • スクリプトの作成・実行ができる

    • 外部ツール(ffmpeg、jqなど)を自由に使える

    • 結果をファイルに保存して再利用できる

    つまり、**「コードを書く」ではなく「コンピュータを自由に操作する」**という汎用的な能力を獲得していたのです。

    SDKに含まれるもの

    Claude Agent SDKには、以下のコンポーネントがパッケージ化されています:

    • モデル連携: Claude APIとの接続

    • ツール管理: カスタムツールの追加・管理

    • ファイルシステム: コンテキストエンジニアリングの基盤

    • Bashツール: 汎用的なコンピュータ操作

    • サブエージェント: 並列処理とコンテキスト管理

    • メモリ: 長期記憶の管理

    • スキル: 再利用可能な知識パッケージ

    • フック: ライフサイクルイベントへの介入

    • コンパクティング: コンテキストウィンドウの管理

    これらすべてを自分で実装すると膨大な時間がかかりますが、Claude Agent SDKを使えば数十行のコードでエージェントが構築できます。

    画像

    「Bash is All You Need」の哲学

    Anthropicのエンジニアが強調する最も重要なメッセージは「Bash is all you need(Bashがあれば十分)」です。

    なぜBashがそこまで強力なのか

    従来のエージェント設計では、必要な機能ごとにツールを作成していました:

    - 検索ツール
    - リントツール
    - 実行ツール
    - テストツール
    - ... (際限なく増える)

    しかしClaude Codeでは、エージェントは単に`grep`コマンドを使って検索し、`npm run lint`でリントを実行します。ツールを増やすのではなく、Bashで何でもできるのです。

    具体例:メールエージェントの場合

    「今週、ライドシェアにいくら使った?」という質問に対するエージェントの動作を比較してみましょう。

    Bashなしの場合:

    1. メール検索APIを呼び出す

    2. 100件のメールが返ってくる

    3. 全メールをコンテキストに読み込む

    4. モデルが1件ずつ確認して金額を抽出

    5. 精度が低く、処理も遅い

    Bashありの場合:

    1. Gmail検索スクリプトを実行

    2. 結果をファイルに保存

    3. `grep`で金額を抽出

    4. スクリプトで合計を計算

    5. 結果をファイルに保存して検証可能

    Bashがあれば、エージェントは自分で作業を検証できます。「この金額は本当に正しいか?」と確認するスクリプトを書いて実行できるのです。

    Bashの3つの強み

    1. コンポーザビリティ: パイプ(`|`)で処理を連結できる

    2. 既存ソフトウェアの活用: ffmpeg、jq、libra officeなどを直接使える

    3. 動的なスクリプト生成: 必要に応じてスクリプトを作成・実行

    エージェントループの設計:3ステップフレームワーク

    エージェントを設計する際、Anthropicでは以下の3ステップで考えます:

    ステップ1: コンテキストの収集(Gathering Context)

    エージェントがタスクを実行するには、まず必要な情報を集める必要があります。

    重要な設計ポイント:

    • エージェントに「渡す」のではなく「探させる」

    • ユーザーがどう作業するかを観察する

    • 検索インターフェースを複数用意する

    例えば、スプレッドシートエージェントなら:

    • SQLクエリに変換して検索

    • XMLパスで検索

    • セル範囲指定(B3:B5)で検索

    • grep で特定の値を検索

    どの方法が最適かは、トランスクリプト(実行ログ)を読んで判断します。エージェントがどう動いているかを観察し、より良い方法を試行錯誤するのです。

    画像

    ステップ2: アクションの実行(Taking Action)

    情報を集めたら、実際にタスクを実行します。

    アクションの3つの手段

    • ツール

      • 特徴: 構造化・高信頼性

      • 適したケース: アトミックな操作(メール送信、ファイル書き込み)

    • Bash

      • 特徴: 高いコンポーザビリティ

      • 適したケース: 検索、リント、メモリ管理

    • コード生成

      • 特徴: 最も柔軟

      • 適したケース: API連携、データ分析、複雑なロジック

    重要な判断基準:

    • 取り消し不可能な操作 → ツールとして定義(ユーザー承認を得る)

    • コンポーザブルな操作 → Bash

    • 複雑なロジック → コード生成

    ステップ3: 作業の検証(Verifying Work)

    「エージェントを作るなら、作業を検証できるか考えろ」とAnthropicのエンジニアは強調します。

    良いエージェント候補の条件:

    • コード → コンパイル・リントで検証可能 ✅

    • スプレッドシート → null値チェック、数式検証が可能 ✅

    • 深層リサーチ → ソース引用で部分的に検証可能 △

    検証のベストプラクティス:

    1. できる限りルールベース(決定的)で検証

    2. 必要に応じてサブエージェントで検証

    3. 検証は最後だけでなく、各ステップで実施

    例えば、Claude Codeでは「まだ読んでいないファイルに書き込もうとした」場合、エラーを返して先に読むよう促します。これは決定的な検証の良い例です。

    サブエージェントの活用

    Claude Agent SDKの強みの一つが、サブエージェントのネイティブサポートです。

    サブエージェントを使うべきケース

    1. 大量の情報を精査する必要がある場合

      • 例:100シートのスプレッドシートから特定の情報を探す

      • 各シートをサブエージェントに割り当てて並列処理

    2. コンテキストを汚染したくない場合

      • メインエージェントには要約だけを返す

      • 詳細な中間処理はサブエージェントのコンテキストで完結

    3. 敵対的検証が必要な場合

      • 「マッキンゼーの新人アナリストが作った資料」として検証させる

      • メインエージェントとは別のコンテキストで厳しくチェック

    サブエージェント設計の注意点

    サブエージェントはそれぞれ独立したコンテキストウィンドウを持ちます。これにより:

    • ✅ コンテキストの効率的な管理

    • ✅ 並列処理による高速化

    • ⚠️ 共有状態の管理が複雑になる

    Anthropicでは、サブエージェント間の通信にはファイルシステムを使うことを推奨しています。HTTPサーバーや特別なプロトコルではなく、Markdownファイルを介して情報を共有するのです。

    画像

    実践:Claude Codeでエージェントをプロトタイピング

    セッションでは、ポケモンエージェントを例にプロトタイピングの実演が行われました。

    プロトタイピングの流れ

    1. トランスクリプトを読んで改善

      • エージェントがどう動いたかを確認

      • 想定と違う動きがあれば、CLAUDE.mdを調整

    重要な学び

    「シンプルなのと簡単なのは違う」

    最終的なエージェントのコードはシンプルであるべきですが、そこに至るプロセスは簡単ではありません。

    // 実際のエージェントコードは50行程度
    const result = await query({
      prompt: "ユーザーのクエリ",
      workingDirectory: "./",
    });

    この50行に至るまでに、以下の試行錯誤があります:

    • どんな検索インターフェースが最適か?

    • どのファイル構造がエージェントに適しているか?

    • どんな検証ステップを入れるべきか?

    トランスクリプトを何度も読み、調整を繰り返すことが、良いエージェント設計の鍵です。

    ツール vs Bash vs コード生成の使い分け

    最後に、3つのアクション手段の使い分けをまとめます。

    ツールを使うべきケース

    • 取り消し不可能な操作: メール送信、決済処理

    • 構造化された入出力が必要: ファイル書き込み、API呼び出し

    • ユーザー承認が必要: 機密データへのアクセス

    Bashを使うべきケース

    • コンポーザブルな操作: grep、awk、パイプ処理

    • 既存CLIツールの活用: git、npm、docker

    • メモリ/状態管理: ファイルへの保存・検索

    コード生成を使うべきケース

    • 複雑なロジック: データ分析、API連携

    • 動的なスクリプト: 条件に応じた処理

    • パターンの再利用: テンプレートからのコード生成

    まとめ:Anthropic流エージェント設計の要点

    1. Bashを中心に設計する: ツールを増やすのではなく、Bashで汎用的に対応

    2. 3ステップで考える: コンテキスト収集 → アクション実行 → 検証

    3. 検証可能性を重視する: 検証できないタスクはエージェント向きではない

    4. トランスクリプトを読む: エージェントの動作を観察して改善

    5. サブエージェントを活用する: コンテキスト管理と並列処理

    Claude Agent SDKは、これらのベストプラクティスをパッケージ化したものです。自分でゼロから構築するよりも、ドメイン固有の問題(検索インターフェース、検証ロジック)に集中できます。

    エージェント開発の世界は急速に進化しています。6ヶ月後には前提が変わっているかもしれません。だからこそ、今動くものを作り、市場投入し、必要に応じてコードを捨てる覚悟を持つことが大切です。

    あなたも今日から、Claude Agent SDKでエージェント開発を始めてみませんか?


    📚 さらに深く学びたい方へ

    本記事で紹介したエージェント設計をさらに深く学びたい方には、こちらの書籍がおすすめです:

    大規模言語モデル入門II〜生成型AIのエンジニアリング

    LLMを使ったアプリケーション開発の実践的なノウハウが詳しく解説されています。エージェント構築の基礎知識を固めるのに最適な一冊です。


    🎯 AI JONBIN Guildのご案内

    AI活用をもっと深く学びたい方へ。限定コミュニティで一緒にスキルアップしませんか?

    • 定期的なAI勉強会・セミナー

    • n8nサーバーへのアクセス

    • AI専門家による限定セミナー

    • メンバー同士の情報交換

    ▶️ AI JONBIN Guildの詳細はこちら

    💬 AI活用の相談は公式LINEへ

    AIの使い方や仕事への取り入れ方で迷っていることがあれば、私の公式LINEで気軽に相談してください。AIに関することは無料で相談できます。

    ▶️ 公式LINEで相談する


    X: @sumo_wonderful
    YouTube: AI大学~ヨッピーch~
    note: note.com/samurai_worker

    #ClaudeAgentSDK #AIエージェント #Claude #Anthropic #AI開発 #LLM #エージェント設計

     
     
    実業務で活用できるAIエージェントの使い方やn8n・Difyなどの作成手順を発信中| YouTube | AI講師 | AI法人顧問・コンサルタント| 日経AIリスキリング掲載|AIコミュニティ『AI Jonbin』、YouTube『のAI大学 ~ヨッピーCH~』

    あなたへのおすすめ