AI 게이트웨이 및 라우터 트래픽을 에이전트 분석으로 전송

AI 게이트웨이 또는 추론 라우터를 통과하는 트래픽은 세 가지 방법으로 에이전트 분석에 도달할 수 있습니다. 즉, 클라이언트를 AI SDK로 감싸거나, 게이트웨이가 OpenTelemetry GenAI 스팬을 내보내도록 하거나, 이미 저장된 대화에 대해 HTTP API를 통해 [Agent] 이벤트를 전송합니다. 클라이언트를 감싸는 것이 전체 경로입니다. 이 기능은 턴, 도구 호출, 사용자 피드백, 실험 컨텍스트 및 게이트웨이의 요청 ID를 캡처합니다.

AI 코딩 에이전트로 설정(권장)

이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오. 에이전트는 AI SDK를 설치하고, 번들로 제공되는 지침을 읽고, 모든 모델 호출을 찾아 계측합니다.

text
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/.

제안되는 변경 사항을 검토한 다음 시작하기의 단계에 따라 확인하십시오.

이것이 여러분에게 의미하는 바

모든 경로는 모든 요청에 대해 사용자가 누구인지, 요청이 속한 대화, 어느 에이전트가 작성했는지와 같은 세 가지 사항을 필요로 합니다. 게이트웨이는 모델, 토큰 및 지연 시간을 알고 있지만 사용자나 대화는 알고 있지 않으므로 애플리케이션이 이를 제공합니다.

클라이언트 래핑

AI SDK의 래핑된 OpenAI 클라이언트를 게이트웨이의 OpenAI 호환 URL로 가리키고, 에이전트에 게이트웨이 이름을 지정한 후 각 요청을 에이전트 세션 내에서 실행합니다. 래핑된 클라이언트는 각 새 사용자 메시지를 추적하므로 수동으로 추적하지 마십시오.

typescript
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과 태그를 사용하십시오:

ingestion_path 및 gateway 값이 [Agent] Context에 저장되므로 차트에서 게이트웨이 트래픽을 직접 공급자 호출과 분리할 수 있습니다. 게이트웨이 경로가 A/B 테스트(예: 하나의 별칭 뒤에 두 모델이 있는 경우)인 경우, 할당을 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 엔드포인트로 내보낼 수 있지만, 어느 쪽도 세 가지 ID 팩트를 모두 포함하지 않으므로 클라이언트를 래핑하는 것이 두 가지 모두에게 완전한 해결책입니다.

  • OpenRouter: Broadcast는 사용자와 세션을 Amplitude로 전송하지만 에이전트 ID를 위한 필드가 없으므로 에이전트는 exporter의 서비스 이름입니다. 생성물은 모델, 토큰 및 비용이 포함된 [Agent] Span 이벤트로 도착하며 [Agent] AI Response 이벤트로는 도착하지 않습니다. 단, 자체 OpenTelemetry Collector가 먼저 gen_ai.operation.name를 설정하는 경우는 예외입니다. Amplitude 개인정보 보호 모드를 OpenRouter의 개인정보 보호 모드로 일치시킵니다.
  • LiteLLM: 프록시의 스팬에는 대화 ID가 없으므로 모든 요청이 각각 개별 1턴 세션이 됩니다. 메시지 텍스트를 포함하려면 프록시에서 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY을(를) 설정하십시오.

Agent 프레임워크는 OpenTelemetry를 자체적으로 내보내는 프레임워크를 나열합니다. 앱이 이미 Amplitude AI SDK를 실행하는 경우, AmplitudeAgentExporter 또는 enableOtel()는 프로세스에서 해당 스팬을 매핑할 수 있습니다. Cost에는 모델과 각 스팬의 두 토큰 카운트가 필요합니다.

엔드포인트 및 속성 매핑에 대한 자세한 내용은 에이전트 분석으로 OpenTelemetry 추적 보내기를 참조하십시오.

Fireworks AI

계측부터 트레이닝을 위해 점수화된 세션을 내보내는 것에 이르는 전체 Fireworks 워크플로우에 대해서는 에이전트 분석(Agent Analytics)과 함께 Fireworks AI 사용을 참조하십시오.

Fireworks AI 트래픽은 두 가지 방법으로 에이전트 분석(Agent Analytics)에 도달합니다. 즉, Fireworks의 OpenAI 호환 클라이언트를 래핑하는 AI SDK를 통하거나, Fireworks가 내보내는 OTLP 추적을 통하는 방법입니다. 둘 모두 동일한 [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, 그리고 gen_ai.response.id을(를) 유지해야 합니다.

시작하기

AI 게이트웨이 및 라우터 가이드를 따르십시오. 확인하려면 다중 요청 대화를 전송하고 이것이 하나의 세션으로 나타나는지, 그리고 각 AI 응답에 [Agent] Provider Request ID이(가) 포함되는지 확인하십시오.

Guide는 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.

이 페이지에서