에이전트 분석에서 실험 변형 기록
experiments 옵션은 에이전트가 실행된 A/B 테스트 또는 기능 플래그 변형을 기록합니다. 플래그 클라이언트가 이미 반환한 할당을 전달하세요. 그러면 세션 내 모든 [Agent] 이벤트에 [Agent] Experiments이(가) 포함되며, 단일 실험의 경우에는 [Agent] Experiment Variant도 포함됩니다. 차트를 해당 속성별로 속성화하여 프롬프트, 모델, 라우터 또는 도구 테스트의 품질, 비용 또는 포기를 비교합니다.
에이전트 동작을 변경하는 변형에 experiments을(를) 사용합니다. UI 표면과 같은 다른 세그멘테이션 차원에는 [Agent] Context을(를) 사용하고, 무작위로 지정되지 않은 릴리스의 경우 agentVersion(Node) 또는 agent_version(Python)을(를) 사용하십시오.
이 experiments 옵션을 사용하려면 0.24.1을 초과하는 Node @amplitude/ai 릴리즈 또는 1.20.1을 초과하는 Python amplitude-ai 릴리즈가 필요합니다. Amplitude는 변형을 할당하지 않습니다: Amplitude 실험, Statsig 또는 LaunchDarkly와 같은 기존 플래그 또는 실험 SDK를 유지하고 해당 결과를 전달합니다.
AI SDK를 사용하여 할당을 전달합니다.
에이전트, 세션 또는 단일 추적 호출에 experiments을(를) 설정합니다. 각 항목은 key 및 variant, 및 선택적으로 provider(플래그 시스템의 이름) 및 unit을(를) 취합니다.
const variant = await flags.getVariant('planner'); // your existing flag client
const agent = ai.agent('support-bot', { userId });
await agent
.session({ sessionId, experiments: [{ key: 'planner', variant, provider: 'statsig' }] })
.run(async (s) => {
// Provider wrappers, tools, and tracking calls in the session all carry the experiment.
});
SDK는 다음 순서로 항목을 적용합니다.
- 에이전트. 에이전트의 모든 세션에 적용됩니다. 하위 에이전트는 상위의 실험을 상속받으며 항목을 추가하거나 재정의할 수 있습니다.
- 세션. 동일한 키를 사용하여 에이전트 항목을 재정의합니다.
- 통화. 단일 에이전트 또는 세션 추적 호출은 해당 이벤트에 대해서만 두 항목 모두를 재정의합니다.
재정의는 해당 공급자와 유닛을 포함한 전체 항목을 대체합니다. 항목은 해당 키가 처음 나타난 위치를 유지합니다.
각 이벤트의 속성
| 속성 | 유형 | 가 설정된 경우 |
|---|---|---|
[Agent] Experiments | 문자열 배열 | 유효한 실험이 하나 이상 포함된 모든 이벤트. 각 값은 key:variant이며, 예: planner:v2입니다. |
[Agent] Experiment Key | 문자열 | 정확히 하나의 실험이 적용됩니다. |
[Agent] Experiment Variant | 문자열 | 정확히 하나의 실험이 적용됩니다. |
[Agent] Experiment Unit | 문자열 | 정확히 하나의 실험이 적용됩니다: agent_session, turn, 또는 span. |
[Agent] Experiment Provider | 문자열 | 정확히 하나의 실험이 적용되며 유효한 공급자가 있습니다. |
두 개 이상의 실험을 사용하는 경우 이벤트는 배열만 전달합니다. 모든 개인정보 보호 모드에서 이러한 속성을 전송합니다.
단위 선택
unit 플래그 클라이언트가 무작위로 지정한 내용을 기록하므로 분석 시 동일한 대상을 비교할 수 있습니다.
agent_session(기본값). 대화가 시작될 때 선택한 프롬프트 또는 모델과 같이 세션당 하나의 할당.turn. 각 턴마다 평가되는 라우터와 같은 사용자 메시지당 새로운 할당.span. 도구 또는 검색 전략과 같이 턴 내에 있는 작업당 새로운 할당입니다. OpenTelemetry 평가의 기본값은span입니다.
검증 및 제한
SDK, OpenTelemetry 리시버 및 웨어하우스 가져오기 템플릿에는 동일한 규칙이 적용됩니다. 잘못된 입력은 절대로 오류를 발생시키지 않습니다.
key,variant및provider은(는) ASCII 공백을 자른 후의 1~256자입니다.key은(는):를 포함할 수 없습니다.variant은(는) 예를 들어openai:gpt-4o이(가) 될 수 있습니다.- Amplitude는 유효한 키나 변형이 없는 항목을 삭제합니다. SDK는 삭제된 각 항목을 디버그 수준에서 기록합니다.
- 알 수 없는
unit은(는) 기본값으로 대체되며, 유효하지 않은provider은(는) 제외됩니다. - 최대 10개의 실험이 이벤트에 적용되며, 이는 에이전트, 세션 및 호출 항목이 병합된 후 계산됩니다.
키, 변형 및 공급자는 편집되지 않습니다. 플래그와 변형 이름을 사용하고 사용자 데이터를 사용하지 마십시오.
OpenTelemetry에서 할당 보내기
Agent 분석은 GenAI 스팬으로부터 OpenTelemetry 기능 플래그 평가를 읽습니다. 각 feature_flag.evaluation span 이벤트와 span의 자체 feature_flag.* 속성은 span이 생성하는 모든 이벤트에 대한 하나의 실험이 됩니다. 속성 이름에 대해서는 OTLP 참조의 기능 플래그 속성을 참조하십시오.
HTTP API 또는 웨어하우스 가져오기를 통해 할당을 전송하세요
직접 전송하는 이벤트에는 동일한 5가지 속성이 있습니다. [Agent] Experiments을(를) key:variant 문자열 배열로 설정하고, 실험이 하나만 적용될 때만 단일 실험 속성을 설정하십시오. AI SDK 없이 에이전트 이벤트 전송을 참조하십시오.
웨어하우스 가져오기 템플릿은 선택적 experiment_key 및 experiment_variant 열을 읽으며, 행당 한 개의 실험이 있고, 단위는 agent_session입니다. 데이터 웨어하우스에서 에이전트 대화 가져오기를 참조하십시오.
차트를 변형별로 분할합니다
[Agent]세션 비용이나 포기와 같은 이벤트를 기반으로 구축된 차트를 엽니다.[Agent] Experiment Variant에 속성화를 추가합니다. 여러 실험이 있는 세션의 경우 대신[Agent] Experiments기준으로 속성화하십시오: 배열의 각 값이 자체 그룹이 됩니다.[Agent] Experiment Key을(를) 필터링하여 테스트 하나만 표시합니다.
[Agent] Context에서 마이그레이션
이전 지침에서는 변형을 context에 포함합니다(예: context: { experiment_variant: 'treatment' }). 이러한 값은 [Agent] Context필터에서 계속 작동합니다. 새 코드의 경우 할당을 experiments(으)로 전달하고 context에서 제거하십시오. 그러면 각 이벤트는 할당을 한 번씩 기록하고 차트는 전용 속성별로 속성화할 수 있습니다.
이 내용이 도움이 되었나요?
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.