Article by: Martin Linzmayer（読了時間：4分）
先日のAgent Hackweek（好きなAIやエージェント関連のプロジェクトに1週間取り組めるSentryの社内イベント）で、同僚からLaravel AIインテグレーションを作らないかと誘われました。他のフレームワーク向けにすでに提供しているAgent TracingのサポートをLaravel AIで構築したエージェントにも広げることが目的です。
いいアイデアだと思いました。彼は以前、PythonベースのエージェントのためにSentryのAgent Tracingを構築しており、ドメイン知識をすでに持っていましたし、このイベントではAIを使うことになっていたので、言語の壁も大きな問題にはなりませんでした。
不要だった防御的なコード
Claudeならコーディングはそれなりにこなしてくれるだろうと、かなり自信がありました。Laravelは型付きのデータを持つEventsを公開しているので、データの形はほぼ把握できるはずです。
ところが最初のレビューで、Claudeは実際にはデータの正しい形を把握できておらず、フィールドにできるかぎり汎用的な方法でアクセスするヘルパーを作っていたので、少し驚きました。
しばらくPHPから離れている方のために説明すると、このスニペットは構造に関係なく、配列やオブジェクトから値を取り出そうとする汎用ヘルパーです。$source->{$key} は $key を文字列の値に解決し、そのフィールドにアクセスします。言うまでもなく、これは良いPHPコードとは言えません。たいていの場合、データの形はもっと限定されているため、役に立つ場面はほとんどありません。
Laravel AIのライフサイクルにフックする
PythonやJavaScriptでのインストルメンテーションは、比較的簡単なことが多く、関数をラップしたり、パッチを当てたりするだけで済みます。しかし、PHPではそうはいきません。フレームワークやライブラリのフックに頼るか、ユーザーにクラスを独自のものへ置き換えてもらう必要があります。後者をできるだけ避けているのは、ユーザーにコードの書き換えを求めるようでは、インテグレーションとは呼べないからです。幸い、Laravel AIは重要な部分のほとんどでイベントを発行します。ただし、すべてではありません。
Laravel AIにはライフサイクルにフックする手段が十分そろっているように見えました。PromptingAgent と AgentPrompted イベントはエージェントとのやり取り全体を、InvokingTool と ToolInvoked は個々のツール呼び出しをカバーしています。
Agent Tracingには、もう一段細かい粒度が必要です。LLMの呼び出しを1回ずつ、個別のChatスパンとして表示しなければなりません。Laravel AIはこうした呼び出しに対するイベントを公開していないため、ライフサイクルイベントだけに頼ると、トレースに大きな抜けが生じてしまいます。
LLM呼び出しとHTTPリクエストを照合する
ほとんどのLLM呼び出しは、最終的にHTTPリクエストになります。Laravelにはそのためのイベントとして RequestSending と ResponseReceived があります。エージェントとのやり取り中に発生したすべてのHTTPリクエストにChatスパンを作成することもできますが、それではツールによるHTTP呼び出しなど、無関係なリクエストまでキャプチャしてしまいます。
LaravelのHTTPイベントにはAI呼び出しのIDが含まれていないため、リクエストを直接関連付けることはできません。そこで、アクティブな呼び出しごとに設定済みのプロバイダーURLのプレフィックスを保存し、送信されるすべてのリクエストのURLと比較することにしました。複数のアクティブな呼び出しが一致した場合は、最後に開始されたものにリクエストを関連付けます。一致したリクエストだけがChatスパンになるため、個々のLLM呼び出しを取りこぼすことなく、無関係なHTTPトラフィックを除外できます。
設定不要のトレーシング
Laravel AIインテグレーションは、sentry-laravel 4.27でリリースされました。すでにSentryのトレーシングを有効にしているアプリケーションなら、SDKをアップデートするだけです。インテグレーションの登録も、Sentry固有のコードの追加も必要ありません。通常のLaravel AIエージェントは自動的にトレースされ、Conversational を実装すればConversationsにも対応します。
Sentryのコードはどこにもありません。このクラスからのエージェント呼び出し、LLMリクエスト、ツール呼び出しはAgent Tracingに表示され、会話のコンテキストはExploreのAgentsセクションに表示されます。
Sentryで確認する
最初のトレースがSentryに届くと、ExploreのAgentsセクションに会話の一覧が表示されます。所要時間、メッセージ数とエラー数、推定コスト、使用されたツールを確認できます。
会話を開くと、ユーザーのメッセージやエージェントの返答とあわせて、ツール呼び出しを含むトランスクリプトが表示されます。
ツール呼び出しを選択すると、その入力と出力が表示されます。これにより、ツールが返した内容とエージェントの応答を見比べることができます。
始めるのはとても簡単です。LaravelアプリですでにSentryのトレースを設定しているなら、SDKをバージョン4.27にアップデートするだけです。laravel/ai がインストールされていてトレーシングが有効であれば、Laravel Agent Tracingはデフォルトで有効になります。セットアップの詳しい手順はLaravel Agent Tracingのドキュメントをご覧ください。そのうえで、Explore > Agentsでエージェントのトレースと会話を確認してみてください。
Original Page: Building Sentry’s Laravel AI Integration
IchizokuはSentryと提携し、日本でSentry製品の導入支援、テクニカルサポート、ベストプラクティスの共有を行なっています。Ichizokuが提供するSentryの日本語サイトについてはこちらをご覧ください。またご導入についての相談は「お問い合わせ」からお気軽にお問い合わせください。
