Skip to Content
Docker AIcagentベストプラクティス

ベストプラクティス

cagentエージェントを構築・運用する中で学んだパターンを紹介します。これらは機能や設定オプションではなく、実際にうまく機能するアプローチです。

大規模なコマンド出力の処理

大規模な出力を生成するシェルコマンドは、エージェントのコンテキストウィンドウを溢れさせる可能性があります。バリデーションツール、テストスイート、ビルドログなどは、しばしば数千行のログを生成します。この出力を直接キャプチャすると、利用可能なすべてのコンテキストを消費してしまい、エージェントが失敗します。

解決策：出力をファイルにリダイレクトし、そのファイルを読み取ります。読み取りツール（Read tool）は、大きなファイルを自動的に2,000行に切り詰め、エージェントは必要に応じてファイル内を移動（ナビゲート）できます。

やってはいけない例：

reviewer:
  instruction: |
    バリデーションを実行してください：`docker buildx bake validate`
    出力にエラーがないか確認してください。
  toolsets:
    - type: shell

バリデーションの出力が直接コンテキストに入ります。出力が大きい場合、エージェントはコンテキストオーバーフローエラーで失敗します。

推奨される方法：

reviewer:
  instruction: |
    バリデーションを実行し、出力を保存してください：
    `docker buildx bake validate > validation.log 2>&1`
 
    validation.log を読み取ってエラーを確認してください。
    ファイルが大きくなる可能性があるため、最初の2,000行を読み取ってください。
    エラーは通常、冒頭に表示されます。
  toolsets:
    - type: filesystem
    - type: shell

出力はコンテキストではなくファイルに送られます。エージェントはファイルシステムツールセットを使用して、必要なものを読み取ります。

エージェントチームの構造化

単一のエージェントが複数の責任を処理すると、指示が複雑になり、動作が予測不能になります。作業を専門のエージェントに分割することで、より良い結果が得られます。

コーディネーターパターンがうまく機能します。ルートエージェント（root agent）が全体のタスクを理解し、専門家に委任します。各専門家は一つのことに集中します。

例：ドキュメント執筆チーム

agents:
  root:
    description: テクニカルライティングコーディネーター
    instruction: |
      ドキュメント作業を調整してください：
      1. コンテンツ作成を writer（執筆担当）に委任する
      2. フォーマットの仕上げを editor（編集担当）に委任する
      3. バリデーションを reviewer（レビュー担当）に委任する
      4. reviewer が問題を見つけた場合は、editor に戻って修正させる
    sub_agents: [writer, editor, reviewer]
    toolsets: [filesystem, todo]
 
  writer:
    description: ドキュメントコンテンツの作成と編集
    instruction: |
      明確で実用的なドキュメントを執筆してください。
      コンテンツの質に集中してください。エディターがフォーマットを処理します。
    toolsets: [filesystem, think]
 
  editor:
    description: フォーマットとスタイルの磨き上げ
    instruction: |
      フォーマットの問題を修正し、行を折り返し、prettier を実行してください。
      AI特有の言い回しを削除し、スタイルを磨き上げてください。
      意味を変えたり、コンテンツを追加したりしないでください。
    toolsets: [filesystem, shell]
 
  reviewer:
    description: バリデーションツールの実行
    instruction: |
      バリデーションスイートを実行し、失敗を報告してください。
    toolsets: [filesystem, shell]

各エージェントは明確な責任を持っています。執筆担当（writer）は行の折り返しを気にしません。編集担当（editor）はコンテンツを生成しません。レビュー担当（reviewer）はツールを実行するだけです。

この例では sub_agents を使用しており、ルートが個別のタスクを委任し、結果を返してもらいます。ルートエージェントは制御を維持し、すべての作業を調整します。エージェントが互いに制御を移譲する別の調整パターンについては、設定リファレンスの handoffs メカニズムを参照してください。

チームを使用すべき場合：

  • ワークフローに複数の明確なステップがある

  • 異なるスキルが必要である（執筆 ↔ 編集 ↔ テスト）

  • 後のフィードバックに基づいて、あるステップを再試行する必要がある可能性がある

単一のエージェントを使用すべき場合：

  • シンプルで、焦点が絞られたタスク

  • すべての作業が一段階で行われる

  • 調整のオーバーヘッドを追加しても役に立たない

RAGパフォーマンスの最適化

ファイル数が多い場合、RAGのインデックス作成には時間がかかります。コードベース全体をインデックス化する構成では、開始までに数分かかることがあります。エージェントが実際に必要とするものに合わせて最適化してください。

スコープを絞り込む：

すべてをインデックス化しないでください。エージェントの作業に関連するものだけをインデックス化します。

# 広すぎる設定 - コードベース全体をインデックス化
rag:
  codebase:
    docs: [./]
 
# より良い設定 - 関連するディレクトリのみをインデックス化
rag:
  codebase:
    docs: [./src/api, ./docs, ./examples]

エージェントがAPIコードのみを扱う場合、テスト、vendorディレクトリ、または生成されたファイルをインデックス化しないでください。

バッチ処理と並列性を高める：

1回のAPI呼び出しあたりのチャンク数を増やし、並列リクエストを行います。

strategies:
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    batch_size: 50 # 1回のAPI呼び出しあたりのチャンク数を増やす
    max_embedding_concurrency: 10 # 並列リクエスト数
    chunking:
      size: 2000 # チャンクサイズを大きく = 総チャンク数を減らす
      overlap: 150

これにより、API呼び出し回数とインデックス作成時間の両方が削減されます。

高速なローカル検索のためにBM25を検討する：

正確な用語の一致（関数名、エラーメッセージ、識別子など）が必要な場合、BM25は高速で、API呼び出しなしにローカルで実行されます。

strategies:
  - type: bm25
    database: ./bm25.db
    chunking:
      size: 1500

セマンティックな理解と正確な一致の両方が必要な場合は、ハイブリッド検索を使用して埋め込み（embeddings）と組み合わせます。

ドキュメントのスコープを維持する

ドキュメントを更新するエージェントを構築する際、よくある問題があります。エージェントが最小限のガイドをチュートリアルに変えてしまうことです。前提条件、トラブルシューティング、ベストプラクティス、例、詳細な説明をあらゆるところに追加してしまいます。

これらの追加は個々には良いかもしれませんが、ドキュメントの性格を変えてしまいます。焦点の絞られた90行のハウツー記事が、200行のリファレンスになってしまいます。

これを指示（instruction）に組み込む：

writer:
  instruction: |
    ドキュメントを更新する際：
 
    1. 現在のドキュメントのスコープ（範囲）と長さを理解すること
    2. その性格に合わせてください。最小限のガイドをチュートリアルに変えないこと
    3. 本当に欠けているものだけを追加すること
    4. 簡潔さを重視すること。すべてのトピックに包括的な説明が必要なわけではありません
 
    良い追加はギャップを埋めるものです。悪い追加はドキュメントの性格を変えてしまいます。
    迷ったときは、多く追加するよりも少なく追加することを選んでください。

既存のドキュメントのスコープを維持するよう、エージェントに明示的に伝えてください。このガイダンスがないと、彼らはデフォルトで包括的（comprehensive）であろうとします。

モデルの選択

エージェントの役割と複雑さに基づいてモデルを選択してください。

大型モデル（Sonnet, GPT-5）を使用すべきケース：

  • 複雑な推論と計画

  • コンテンツの執筆と編集

  • 複数のエージェントの調整

  • 判断力と創造性を必要とするタスク

小型モデル（Haiku, GPT-5 Mini）を使用すべきケース：

  • バリデーションツールの実行

  • シンプルな構造化されたタスク

  • ログの読み取りとエラーの報告

  • 高ボリュームで低複雑度の作業

ドキュメント執筆チームの例：

agents:
  root:
    model: anthropic/claude-sonnet-4-5 # 複雑な調整
  writer:
    model: anthropic/claude-sonnet-4-5 # 創造的なコンテンツ作業
  editor:
    model: anthropic/claude-sonnet-4-5 # スタイルに関する判断
  reviewer:
    model: anthropic/claude-haiku-4-5 # バリデーションを実行するだけ

レビュー担当（reviewer）はHaikuを使用しています。これはコマンドを実行してエラーをチェックするためです。複雑な推論は必要なく、Haikuの方が高速で安価です。

次のステップ

  • すべての利用可能なオプションについては、設定リファレンスを確認してください

  • エージェントが使用できるツールを理解するには、ツールセットリファレンスを確認してください

  • 実際に動作する完全なエージェントについては、設定例 を参照してください

  • 検索の最適化の詳細については、RAGガイドを読んでください

Last updated on
コーディングエージェントの構築エージェントの共有