AI SDK를 사용하여 에이전트를 계측합니다
Amplitude AI SDK(Node용 @amplitude/ai, Python용 amplitude-ai)는 LLM 클라이언트를 감싸고 각 대화를 에이전트 세션으로 그룹화하므로 에이전트 분석이 예상하는 모든 [Agent] 이벤트를 발생시킵니다. 또한 세션을 닫고, 개인정보 보호 모드를 적용하며, 모델 호출에 대해 가격을 지정합니다.
Node 또는 Python 코드베이스가 수정될 수 있는 경우 AI SDK를 사용하십시오. 런타임에서 실행할 수 없는 경우, 브라우저, Edge 런타임, Java, Go 또는 Ruby 등, 대신 AI SDK 없이 에이전트 이벤트를 전송하십시오. 이미 OpenTelemetry GenAI 스팬을 내보낸 경우 OpenTelemetry 추적을 전송하십시오.
시작하기 전에 세션 ID와 사용자 ID와 개인정보 보호 모드를 결정하십시오. 전체 SDK API에 대해서는 AI SDK 설명서를 참조하십시오.
AI 코딩 에이전트를 사용하여 계측(권장)
이 프롬프트를 Cursor, Claude Code, Windsurf, GitHub Copilot 또는 Codex와 같은 AI 코딩 에이전트에 붙여넣으십시오. 에이전트는 SDK를 설치하고, 번들로 제공되는 지침 파일을 읽고, 코드베이스를 스캔하며, 모든 LLM 호출 사이트와 세션 생애주기 분석을 찾은 후 계측합니다. 또한 검증 테스트를 작성합니다.
Instrument this app with Amplitude Agent Analytics using the Node SDK.
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
제안되는 변경 사항을 검토한 다음 계측을 확인하십시오.
수동으로 계측
LLM 클라이언트를 래핑하고, 에이전트를 지정하고, 세션 내에서 각 대화를 실행합니다. 이 패턴은 Agent Analytics가 예상하는 모든 이벤트 유형을 생성합니다.
import { AmplitudeAI, OpenAI } from "@amplitude/ai";
const ai = new AmplitudeAI({ apiKey: process.env.AMPLITUDE_AI_API_KEY });
const openai = new OpenAI({
amplitude: ai,
apiKey: process.env.OPENAI_API_KEY,
});
const agent = ai.agent("my-agent");
const session = agent.session({ userId, sessionId });
await session.run(async (s) => {
s.trackUserMessage(message);
return openai.chat.completions.create({ model, messages });
});
await ai.flush();
래핑된 프로바이더(Node의 new OpenAI({ amplitude: ai }), Python의 patch(amplitude_ai=ai))는 완료 응답에서 채팅 텍스트를 포함한 [Agent] AI Response을(를) 캡처합니다. 래핑된 프로바이더가 없으면 Amplitude는 해당 이벤트나 메시지 콘텐츠를 추적하지 않습니다. SDK가 래핑하지 않는 프로바이더를 사용하거나 래핑되지 않은 클라이언트를 직접 호출하는 경우, 완료가 반환된 후 trackAiMessage()(Node) 또는 track_ai_message()(Python)을 호출하십시오. 모든 추적 방법에 대해서는 SDK 참조에서 수동 계측을 참조하십시오.
개인정보 보호 모드를 적용하려면 AIConfig에 contentMode(Node) 또는 content_mode(Python)을(를) 설정합니다. SDK 구성을 참조하십시오.
에이전트가 A/B 테스트 또는 기능 플래그 환경에서 실행되는 경우, 플래그 클라이언트가 반환한 변형을 experiments(으)로 ai.agent() 또는 agent.session()에서 전달하십시오(예: experiments: [{ key: 'planner', variant }]). 그러면 세션의 모든 이벤트는 [Agent] Experiment Variant을(를) 포함합니다. Agent 분석에서 실험 변형 기록을 참조하십시오.
에이전트와 세션을 수명이 긴 서버에 배치합니다.
많은 턴과 사용자를 처리하는 HTTP 서버에서 세 가지 배치 규칙은 세션을 올바르게 그룹화하도록 유지합니다.
모듈 범위에서 에이전트 정의
요청 핸들러 내부에 ai.agent(...)을(를) 생성하면 매 턴마다 새로운 [Agent] Agent ID이(가) 만들어지며 세션 그룹화가 작동하지 않게 됩니다. 모듈 로드 시 에이전트를 한 번 생성하고 참조를 재사용하십시오.
// agent.ts (module scope)
export const agent = ai.agent("support-bot");
// handler.ts
export async function POST(req: Request) {
const { sessionId, userId, message } = await req.json();
return agent.session({ userId, sessionId }).run(async (s) => {
s.trackUserMessage(message);
// ...
});
}
안정적인 세션 ID를 사용하여 요청당 하나의 세션을 엽니다.
각 요청 핸들러 내에서 agent.session({ sessionId })을(를) 호출하고 동일한 작업의 모든 턴에서 동일한 sessionId을(를) 사용하십시오. 턴은 프로세스를 공유해서가 아니라 ID를 공유하기 때문에 함께 연결됩니다.
각 세션 ID는 한 명의 사용자에게만 할당하십시오.
공유 또는 글로벌 세션 ID는 서로 다른 사용자의 대화를 병합하며 사용자별 분석을 방해합니다. 세션 ID 선택을 참조하십시오.
세션 닫기 및 플러시
run()(Node) 또는 session() 컨텍스트 관리자(Python)로 열린 세션은 범위가 종료될 때 닫힙니다. 여러 요청에 걸쳐 있는 세션의 경우 작업이 완료될 때 trackSessionEnd()(Node) 또는 track_session_end()(Python)을(를) 호출하십시오. 종료 방식은 세션 닫기 방법을 참조하십시오.
SDK는 이벤트를 메모리에 일괄 처리하고 주기적으로 전송합니다. 짧은 세션(1분 미만)의 경우 배치가 투명합니다. 몇 시간 동안 작업한 티켓, 하루에 걸쳐 작업한 코딩 작업 또는 백그라운드 작업과 같이 장기간 실행되는 세션의 경우 close 이벤트가 버퍼에 있을 수 있습니다. 프로세스가 전송되기 전에 다시 시작되는 경우, 세션은 유휴 시간 초과로 닫힐 때까지 열린 상태로 유지됩니다.
닫은 직후에 ai.flush()을(를) 호출하여 프로세스가 종료되거나 다시 시작되기 전에 완료되도록 하십시오.
agent.trackSessionEnd({ sessionId: ticketId });
await ai.flush();
Serverless 핸들러는 session.run()이(가) 완료될 때 자동으로 플러시되므로 여기서 명시적 호출이 필요하지 않습니다. 장기간 실행되는 서버의 경우, 프로세스가 중지되기 전에 모든 열린 세션의 버퍼링된 이벤트가 전송되도록 SIGTERM 핸들러에서도 ai.flush()을(를) 호출하십시오.
세션을 기본값인 30분보다 오래 열어 두려면 세션 시간 초과 구성을 참조하십시오.
이 내용이 도움이 되었나요?
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.