AIゲートウェイとルーターのトラフィックをエージェント分析に送信する
AIゲートウェイまたは推論ルーターを通過するトラフィックは、クライアントをAI SDKでラップする、ゲートウェイにOpenTelemetry GenAIスパンをエクスポートさせる、あるいはすでに保存されている会話の場合はHTTP API経由で[Agent]イベントを送信する、という3つの方法でエージェント分析に到達できます。クライアントをラップするのが完全な方法です。この機能は、ターン、ツール呼び出し、ユーザーのフィードバック、実験コンテキスト、ゲートウェイのリクエストIDをキャプチャします。
AIコーディングエージェントを使用した設定(推奨)
このプロンプトを、Cursor、Claude Code、Windsurf、GitHub Copilot、CodexなどのAIコーディングエージェントに貼り付けます。エージェントはAI SDKをインストールし、そのバンドルされている手順を読み取り、すべてのモデル呼び出しを検出し、それをインストルメントします。
Instrument this app with Amplitude Agent Analytics using the Node SDK. Our model calls go through an AI gateway or inference router.
Fetch and follow https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/amplitude-ai.md
Then install the SDK as that guide says:
npm install @amplitude/ai @amplitude/analytics-node
Also fetch https://raw.githubusercontent.com/amplitude/Amplitude-AI-Node/main/docs/integrations/routers.md
and follow it for the base URL, the gateway tag, and routed-model pricing.
If @amplitude/ai is installed, the same file is under node_modules/@amplitude/ai/docs/integrations/.
提案された変更を確認し、今すぐ始めるの手順に従って検証します。
お客様への影響
すべてのパスは、すべてのリクエストについて、同じ3つの事実を必要とします。つまり、ユーザーは誰であるか、リクエストがどの会話に属しているか、どのエージェントがそれを実行したかです。 ゲートウェイはモデル、トークン、レイテンシを認識していますが、ユーザーや会話については認識していないため、アプリケーションから供給されます。
クライアントをラップしてください
AI SDKのラップされたOpenAIクライアントを、ゲートウェイのOpenAI互換URLに指定し、エージェントにゲートウェイ名をタグ付け、エージェントセッション内で各リクエストを実行します。 ラッピングされたクライアントが新しいユーザーメッセージを追跡するため、手動で追跡する必要はありません。
import { AmplitudeAI, OpenAI } from "@amplitude/ai";
const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY! });
const client = new OpenAI({
amplitude: ai,
apiKey: process.env.OPENROUTER_API_KEY,
baseUrl: "https://openrouter.ai/api/v1",
});
const agent = ai.agent("support-bot", {
context: { ingestion_path: "gateway", gateway: "openrouter" },
});
export async function handleChat(
userId: string,
sessionId: string,
messages: { role: "user"; content: string }[],
) {
return agent.session({ userId, sessionId }).run(async () => {
const response = await client.chat.completions.create({
model: "openai/gpt-4o-mini",
messages,
});
return response.choices[0]?.message.content;
});
}
お使いのゲートウェイのベースURLとタグを使用してください。
| ゲートウェイ | ベースURL | gatewayタグ | OpenTelemetryのエクスポート |
|---|---|---|---|
| OpenRouter | https://openrouter.ai/api/v1 | openrouter | Partial |
| LiteLLM | たとえば、プロキシなど http://localhost:4000/v1 | litellm | Partial |
| Requesty | https://router.requesty.ai/v1 | requesty | Noneのため、クライアントをラップしてください |
| Fireworks AI | https://api.fireworks.ai/inference/v1 | fireworks | Fireworks-managed。 Fireworks AIを参照してください。 |
[Agent] Contextの値とingestion_pathの値はgatewayに保存されるため、ゲートウェイトラフィックとプロバイダー直接呼び出しをチャート内で区別できます。ゲートウェイのルートがA/Bテストの場合(1つのエイリアスの背後に2つのモデルがある場合など)、割り当てをcontextにではなく、セッション上のexperimentsとして渡します。実験バリアントの記録を参照してください。
コスト
AI SDKは、ゲートウェイが選択したモデルの公開レートに基づいて各レスポンスの価格を設定します。 ルーティングされたモデル名(openai/gpt-4o-miniなど)を選択する場合は、それを渡します。openrouter/autoなどのゲートウェイのエイリアスには価格がないため、レスポンスには$0ではなく[Agent] Cost USDが含まれます。請求額がわかっている場合は、totalCostUsd(Nodeの場合)またはtotal_cost_usd(Pythonの場合)を渡します。
ゲートウェイのトレースをエクスポートする
OpenRouterとLiteLLMはOpenTelemetryのスパンをAmplitudeのOTLPエンドポイントにエクスポートできますが、いずれも3つのIDファクトをすべては保持しないため、どちらの場合もクライアントをラップすることが完全なパスになります。
- OpenRouter:BroadcastはユーザーとセッションをAmplitudeに送信しますが、エージェントIDのフィールドがないため、エージェントはエクスポート側のサービス名です。ジェネレーションは、独自のOpenTelemetry Collectorを事前に
gen_ai.operation.nameに設定している場合を除き、[Agent] AI Responseイベントではなく、モデル、トークン、コストを持つ[Agent] Spanイベントとして到着します。AmplitudeのプライバシーモードをOpenRouterのプライバシーモードに一致させます。 - LiteLLM:プロキシのスパンにはconversation IDがないため、すべてのリクエストは独自のワンターンセッションになります。メッセージテキストを含めるには、プロキシに
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLYを設定します。
エージェントフレームワークには、OpenTelemetryを独自にエクスポートするフレームワークの一覧が表示されます。 アプリがすでにAmplitude AI SDKを実行している場合、AmplitudeAgentExporterまたはenableOtel()によって、プロセス内でこれらのスパンをマッピングできます。コストの算出には、各スパンにモデルと両方のトークン数が必要です。
エンドポイントと属性のマッピングについては、「OpenTelemetryトレースをAgent Analyticsに送信」を参照してください。
Fireworks AI
インストルメンテーションからトレーニング用のスコアリングセッションのエクスポートまでのFireworksワークフロー全体については、「Agent AnalyticsとFireworks AIの使用」を参照してください。
Fireworks のAIトラフィックは、FireworksのOpenAI互換クライアントをラッピングするAI SDK経由、またはFireworksがエクスポートするOTLPトレース経由の2つの方法でAgent Analyticsに到達します。 どちらも同じ[Agent]イベントを生成します。
- クライアントのラップ:ベースURL(
https://api.fireworks.ai/inference/v1)と、クライアントをラップするにある手順を使用します。SDKは、ルーターリクエストIDを[Agent] Provider Request IDとしてキャプチャします。Fireworksのx-multi-turn-session-idヘッダーを自動的に送信することはありません。 - Fireworks-managed OTLP:Fireworksがトレースをエクスポートするとき、AmplitudeプロジェクトのAPIキーを使用して米国またはEUのOTLPエンドポイントに送信します。 エクスポータの設定を参照してください。Amplitudeは有効化リクエストを必要としません。Fireworksは、
user、会話IDまたはセッションID、およびgen_ai.response.idを、すべてのRouterルートを通じて永続化する必要があります。
今すぐ始める
AIゲートウェイとルーターに関するガイドに従ってください。検証するには、複数リクエストからなる会話を送信し、これらの会話が1つのセッションとして表示されること、および各AIレスポンスに[Agent] Provider Request IDが含まれることを確認します。
ガイドは2026年10月6日に最後に確認されました。
これは役に立ちましたか?
For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.