Anthropic SDKを使用したRubyでのAIエージェント構築

この記事では、Anthropic SDKを使用してRubyアプリケーションでAIエージェントを構築する方法を詳細に説明します。AIエージェントはループシステムであり、言語モデルが目標を受け取り、ツールを呼び出すかどうかを決定し、ツールを実行して結果をフィードバックし、タスクが完了するまで繰り返します。これは、LLMとツールを事前定義されたコードパスで調整するワークフローとは異なり、エージェントはLLMが自身のプロセスとツール使用を動的に制御します。Anthropicは最も単純な解決策を見つけ、必要な場合にのみ複雑性を増やすことを推奨しています。多くの機能では、適切なコンテキストを持つ単一のモデル呼び出しが自律エージェントよりも安価で高速かつデバッグが容易です。

最小限のエージェントループ

まずanthropic gemをインストールし、クライアントインスタンスを作成します。単純なループのコード例：

message = ANTHROPIC.messages.create(
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "第1四半期を一文で要約してください。" }]
)

エージェントにするにはループとツールが必要です。手動ループは十数行で記述できます：モデルがツール使用を要求したかチェックし、ツールを実行し、結果を会話に追加し、モデルがツールを要求しなくなるまで繰り返します。SDKのtool_runnerメソッドでこのプロセスを自動化できます。

ツール設計

ツールはエージェントの中核です。各ツールはAnthropic::Toolを継承し、name、description、input_schemaを定義します。callメソッドは入力を受け取り結果文字列を返します。ツールの説明とパラメータ設計は重要であり、モデルはこれらに基づいてツールを呼び出すタイミングを決定します。ベストプラクティスとして、すべてのパラメータに例を提供し、列挙型で選択肢を制限し、明確で詳細な説明を記述します。

ストリーミング

ストリーミングによりモデル出力をチャンク単位で返し、ユーザー体験を向上させます。streamパラメータとブロックを使用すると、各チャンクが即座にブロードキャストされます。RailsアプリではTurbo StreamsやActionCableと組み合わせて、コントローラの往復なしでリアルタイム更新を実現できます。

バックグラウンド実行と本番環境の考慮事項

エージェントループは時間がかかる可能性があるため、バックグラウンドジョブ（Sidekiqなど）で実行し、WebSocketやポーリングで結果をストリーミングしてユーザーに返すべきです。セキュリティ面では、ツールの権限を制限（例：読み取り専用）、プロンプトインジェクションを防止（構造化出力を使用）、ジェイルブレイク攻撃を防ぐ（システムプロンプトで不適切な動作を明示的に禁止）ことが重要です。エラーハンドリングはHTTPエラー（レート制限、ネットワーク障害）とエージェントロジックエラー（ツール呼び出し失敗、収束しないループ）を区別し、無限ループを防ぐために最大反復回数を設定します。

可観測性

各ツール呼び出しの名前、引数、ユーザー、所要時間、およびモデル呼び出しのトークン使用量を記録します。これらのログはデバッグ、監査、コスト帰属に使用できます。トラフィックが多い場合は、時系列データを効率的にクエリするためにTimescaleDBの使用を検討します。

テスト

テストは2つの層に分けます：ツールのロジックと認可を個別にテストし、WebMockやVCRでAPIレスポンスをスタブしてエージェントループをテストします。ツールテストが最も重要で、どのツールも他のテナントのデータを返せないことを検証します。ループテストではHTTPリクエストをスタブし、ツール実行結果が正しくフィードバックされることを確認します。

要約すると、RubyでAIエージェントを構築することは強力ですが、慎重な設計が必要です。この記事は概念から本番環境まで、信頼性が高く保守可能なエージェントシステムを作成するための完全なガイドを提供します。