렌더 에이전트 아티팩트
아티팩트는 에이전트가 사용자에게 보여주는 시각적 내용을 설명하기 위해 도구 호출 또는 AI 응답에 첨부하는 작고 버전이 지정된 JSON 봉투입니다. 에이전트 분석은 봉투의 유효성을 검사하고 해당 시각적 요소를 세션 뷰에서 카드로 다시 그려, 리뷰어가 그 뒤에 있는 JSON 대신 사용자가 본 것을 볼 수 있도록 합니다. Amplitude는 뷰어의 테마를 따르는 내장 렌더러로 카드를 그립니다. 따라서 UI 코드를 배포하지 않으며 Amplitude는 귀하의 코드를 실행하지 않습니다.
시각적 항목이 답이었고 원시 페이로드는 에이전트가 생성한 차트나 제공한 선택 항목과 같이 답변이 좋았는지 여부를 알려주지 않는 경우 아티팩트를 내보내십시오. 분석을 위해 기본 숫자만 필요한 경우 아티팩트가 필요하지 않습니다. 도구 콘텐츠는 이미 차트와 코호트에서 쿼리할 수 있는 이벤트 속성으로 전송됩니다.
에이전트 분석은 모든 조직에 대해 유효한 $agent_artifact 엔벨로프를 자동으로 렌더링합니다.
작동 방식
- 에이전트는 오늘날처럼 사용자를 위해 비주얼을 생성합니다.
- 동시에 귀하의 코드는 도구 호출의
input또는output에, 또는 직접 답변을 위한 AI 응답 첨부 파일에 아티팩트 봉투를 첨부합니다. - Agent 분석은 엔벨로프를 인식하고 검증한 다음 대화 보기와 추적 패널 모두에서 카드를 렌더링합니다.
- 원래 도구 페이로드 또는 응답 텍스트는 카드 옆에 계속 표시됩니다. Amplitude는 절대로 이를 대체하거나 숨기지 않습니다.
페이로드 검증에 실패하면 에이전트 분석은 카드 대신 원시 출력 옆에 간단한 이유를 표시합니다. 데이터를 절대 추측하지 않으며 부분 결과도 렌더링하지 않습니다.
코딩 에이전트를 사용하여 아티팩트를 계측하십시오.
코딩 에이전트를 사용하여 애플리케이션이 시각적 요소를 생성하는 곳에 아티팩트 직렬화를 추가합니다. 코딩 에이전트에서 저장소를 연 다음 이 프롬프트를 복사하여 실행합니다. 애플리케이션이 아직 세션을 Agent 분석으로 전송하지 않는 경우 먼저 계측을 설정하십시오.
Add artifact instrumentation to this application's existing Amplitude
Agent Analytics integration.
Read the artifact contract:
https://amplitude.com/docs/amplitude-ai/agent-analytics/render-artifacts
Also read the instrumentation guide for the SDK or ingest path this
repository uses. If you can't access the documentation, ask me for it
before implementing the contract. Identify the existing content-capture
and redaction settings for the installed SDK or exporter. HTTP, OTLP,
and imported data do not inherit AI SDK settings.
1. Find the code that produces charts, summaries, tables, choices, or
static HTML shown to users. Trace each visual to its tool call and
existing instrumentation. Don't infer a displayed visual from arbitrary
JSON. Find the actual data used to render each visual; a chart ID, URL,
or configuration without values isn't a data snapshot. Preserve the
displayed filters, time range, timezone, and transformations. If that
data or an editable emission point is unavailable, report the gap.
Prefer capturing that data where the application produces the visual,
before truncation, then attaching it through existing instrumentation.
Avoid fetching it again just for analytics. If a reference needs a new
read, preserve resource permissions, bound the total work, and disclose
that the snapshot may differ from what the user originally saw.
2. Write reusable serializer functions in the project's language that
return a root-level $agent_artifact envelope with v: 1, the appropriate
type, and its required fields. Prefer chart, summary, table, or options.
If those types would lose meaningful content, implement a static html
fallback when feasible. Examples include choices with descriptions,
tables with semantic highlights, and reports containing several visuals.
Generate self-contained HTML/CSS/inline SVG from the actual source data,
escaping dynamic text. Follow the documented HTML restrictions and
per-type size limits. The result captures what was shown; controls stay
inert. For script-dependent visuals, generate a faithful static snapshot
from their data rather than simply removing scripts. Before skipping a
visual, evaluate both structured types and static html. If neither fits,
explain what content or meaning would be lost or what data is missing.
3. Derive labels, values, units, ordering, and scope from the application
code. Ask me about ambiguous mappings, such as cents versus dollars or
missing values. Don't invent values, silently truncate data, or change
the meaning of the visual to make an envelope validate.
4. Attach the envelope to the corresponding tool output, or tool input
for an input-side artifact such as a choice prompt. For a direct final-answer
visual, use an explicit artifact attachment on the existing AI response.
Follow the existing SDK, HTTP, or OTLP path and its serialization rules. Reuse session,
trace, and tool or message identifiers. Preserve application behavior and existing
payload fields, and avoid recording the same tool call or response twice.
Account for every visual the tool or final answer produces. For multiple visuals, evaluate one
static html report that preserves all meaningful content within the
documented limits. If that isn't feasible and no structured type fits,
explain the limitation and ask me how to proceed. Don't silently select
one visual or invent a multi-artifact envelope. Keep snapshot-only
failures from failing the underlying tool or response. Preserve request
cancellation and existing background persistence; don't add a storage
wait solely to capture data already available at the producer.
5. Preserve content-capture, exclusion, and redaction settings. Don't enable
capture to bypass metadata-only mode. The producer owns the content it
sends, including raw HTML, attributes, CSS, and inline SVG. Select only
source data approved for analytics capture. Use the existing SDK redaction
path without private helpers or an additional redaction pass. For HTTP,
OTLP, and imports, apply the source pipeline's policy before export.
Ordinary string redaction is best-effort; it doesn't interpret rendered
HTML or guarantee detection of values split across markup or encoded in
styles. Don't build a rendered-HTML PII detector, or omit HTML solely
because redaction is enabled. Viewer sanitization protects rendering,
not sensitive data at ingestion. Use synthetic fixtures for tests.
6. Add focused tests for representative inputs, optional or missing
fields, and invalid or oversized data. Validate the artifact envelope
and the complete serialized content field, including sibling fields,
against artifact and transport limits. Report an oversized snapshot
without truncating it or dropping the underlying event. Verify capture
exclusions, configured redaction, and the actual outbound payload.
Redaction can change markup or serialized JSON; check that the resulting
envelope remains parseable and represents the approved content faithfully.
Show the changed files, mapping assumptions, test results, and a
representative emitted envelope. Test slow or failed snapshot work and
cancellation. Record fixed omission reasons, such as missing data,
unsupported representation, size limit, or timeout, using existing span
identifiers. Don't log source content or exception bodies. Distinguish
expected capture exclusions from failures and ordinary nonvisual output.
Explain how to verify the artifact in
an Agent Analytics test session. Distinguish local serializer/contract
checks from live ingestion and visual verification; report which checks
you actually performed. For HTML fallbacks, verify that meaningful
content remains visible under the documented rendering restrictions.
7. Finish with an instrumented / skipped / needs a decision checklist.
For each visual path, name its source and emission point, coverage,
representation, and any limitation or unanswered mapping question. For
skipped visuals, explain why neither a structured type nor static html
works. Don't claim full coverage based on one successful example.
생성된 변경 사항 및 커버리지 체크리스트, 특히 건너뛴 비주얼, 유닛, 필드 매핑을 사용하기 전에 검토하십시오. 테스트를 실행한 후 테스트 세션을 전송하고 아티팩트가 에이전트가 표시한 시각적 표시와 일치하는지 확인하십시오. 에이전트 분석에서 Artifact not rendered라고 보고하는 경우 유효성 검사 이유를 사용하여 직렬 변환기를 수정하십시오.
직접 직렬화를 구현하려면 엔벨로프, 아티팩트 유형 및 도구 호출 예제를 사용하십시오.
엔벨로프
모든 아티팩트는 단일 예약된 키 아래에 있는 JSON 객체입니다. 핵심은 의도적으로 공급업체 중립적이며 페이로드 문법의 어떤 것도 Amplitude 전용이므로, 동일한 빌더가 다른 플랫폼으로 방출할 수 있습니다 이 모양을 채택합니다. 코드가 아니라 키를 변경합니다.
{
"$agent_artifact": {
"v": 1,
"spec": "https://amplitude.com/docs/amplitude-ai/agent-analytics/render-artifacts",
"type": "chart",
"title": "Monthly payouts",
"caption": "August was the highest month.",
"scope": { "label": "Aug 2026" },
"locale": "en-IN",
"payload": {}
}
}
| 필드 | 필수 | 참고 사항 |
|---|---|---|
v | 예 | 계약 버전. 항상 1. |
spec | 아니오 | 이 페이로드가 따르는 계약의 URL입니다. 키는 공급업체에 중립적이므로, spec은(는) 페이로드가 어떤 스키마를 따르는지 나타내는 방식입니다. Amplitude는 렌더링 시 이를 무시합니다. |
type | 예 | chart, summary, options, table, html 중 하나입니다. |
title | 유형별 | chart, table 및 html의 경우 필수이며, summary 및 options의 경우 선택 사항입니다. |
caption | 아니오 | 카드 아래에 있는 한 줄의 서술. |
scope | 아니오 | { label, dateRange? }, 데이터가 포함되는 기간 또는 모집단입니다. Amplitude는 제목 옆에 이를 렌더링하므로 월간 수치가 전체 기간으로 표시되지 않습니다. |
locale | 아니오 | BCP-47 태그. 숫자 서식을 제어합니다. |
generatedAt, id | 아니오 | 출처. Amplitude는 이를 저장하지만 렌더링하지 않습니다. |
payload | 예 | 유형별 본문. Artifact 유형을 참조하십시오. |
두 가지 규칙이 모든 곳에 적용됩니다:
unit는 개념이 아니라 표시 문자열입니다."INR","%","ms","req/s"또는 그 외 다른 것을 전송하세요. Amplitude는 이를 as-is로 값에 추가하며 해석하지 않습니다. 숫자 서식은locale에 의해 지정됩니다.- 색상은 의미론적이며 결코 문자 그대로의 의미를 갖지 않습니다.
primary,success, 또는danger을(를) 전송하면 Amplitude가 이를 밝은 모드와 어두운 모드 모두에서 작동하고 색각 이상이 있는 독자도 구별할 수 있는 테마 색상으로 매핑합니다. Hex 값, 글꼴 및 크기는 계약에 포함되지 않습니다.
도구 호출에 엔벨로프를 첨부하십시오
아티팩트는 해당 항목을 생성한 도구 호출을 통해 이동합니다. 엔벨로프를 도구의 output(으)로 전달하거나, 아티팩트가 입력인 경우 사용자에게 질문한 것과 같이 input(으)로 전달합니다.
const artifact = {
$agent_artifact: {
v: 1,
type: "chart",
title: "Monthly payouts",
payload: {
shape: "categorical",
kind: "bar",
unit: "INR",
items: [
{ label: "Aug 2026", value: 37279.7, color: "danger" },
{ label: "Jul 2026", value: 23925, color: "primary" },
],
},
},
};
session.trackToolCall("render_payouts_chart", latencyMs, true, {
input: JSON.stringify({ range: "last-3-months" }),
output: JSON.stringify(artifact),
});
도구 콘텐츠는 input및 output 옵션에서 제공됩니다. Amplitude는 오류가 없는 다른 철자를 무시하므로 아티팩트가 도착하지 않습니다. 여기에는 결과 이벤트 속성의 이름인 toolInput 및 toolOutput이(가) 포함됩니다. 제로 코드 계측을 위해 patch()에 의존하는 경우, 자동 추출된 도구 호출은 입력이나 출력을 포함하지 않으므로 아티팩트에는 명시적 trackToolCall이(가) 필요합니다. SDK 참조에서 Track 도구 호출에 대해 알아보십시오.
AI 응답에 직접 답변 아티팩트를 첨부하십시오.
애플리케이션이 어시스턴트 답변에 직접 시각적 항목을 표시하는 경우, 해당 Envelope를 해당 기존 AI 응답에 첨부하십시오. 도구 아티팩트와 동일한 v: 1 Envelope와 아티팩트 유형을 사용하십시오. 각 첨부 파일에는 type: "artifact"필드와 루트 수준 $agent_artifact필드가 있습니다.
Python SDK는 첨부 파일을 사전으로 받아들이고 직렬화를 처리합니다:
agent = ai.agent(
"Your agent",
user_id=user_id,
session_id=session_id,
trace_id=trace_id,
)
agent.track_ai_message(
content=response_text,
model=model,
provider=provider,
latency_ms=latency_ms,
message_id=message_id,
attachments=[{
"type": "artifact",
"$agent_artifact": {
"v": 1,
"type": "table",
"title": "Sessions by region",
"payload": {
"columns": ["Region", "Sessions"],
"rows": [["Alpha", 12], ["Beta", 18]],
},
},
}],
)
HTTP 수집의 경우 첨부 파일 목록을 기존 [Agent] AI Response 이벤트의 [Agent] Attachments 이벤트 속성으로 직렬화합니다. 응답 텍스트와 세션, 추적 및 메시지 식별자를 유지하십시오. 동일한 답변에 대해 두 번째 응답이나 합성 도구 호출을 발생시키지 마십시오. 애플리케이션이 최종 답변을 수락한 후에만 첨부를 추가하십시오. 중간 초안은 최종 답변 스냅샷이 아닙니다.
Agent 분석은 텍스트가 없는 응답을 포함하여 대화 및 추적 뷰 모두에서 아티팩트 첨부 파일을 목록 순서대로 렌더링합니다. 이 채널에서는 명시적인 첨부 파일 type: "artifact"만 인식합니다. 응답 텍스트에서 시각적 요소를 추론하거나 첨부 파일 URL을 가져오지 않습니다.
첨부 파일 목록은 다른 첨부 파일 유형을 포함하여 최대 32개의 항목과 256KB의 직렬화된 데이터를 지원합니다. 각 아티팩트도 유형별 제한을 준수합니다. SDK 또는 ingest 경로에서 더 작은 제한을 적용할 수 있습니다. 직렬화된 출력을 확인하고 제한을 초과하는 스냅샷을 자르는 대신 거부하십시오. 하나의 리포트를 구성하는 여러 시각적 요소의 경우, 전체 리포트를 유지하는 하나의 정적 html 아티팩트를 선호합니다.
SDK 첨부 파일은 SDK의 콘텐츠 캡처 및 가림 처리 설정을 따릅니다. metadata_only 모드에서는 첨부 파일의 본체를 생략하므로 아티팩트 카드가 렌더링되지 않습니다. 직접 HTTP의 경우 첨부 파일 목록을 내보내기 전에 소스 파이프라인의 개인정보 보호 정책을 적용하십시오.
모든 수집 경로에서 내보내기
Envelope는 모든 경로에서 동일합니다. 바뀌는 것은 위치뿐입니다: 아티팩트는 도구 호출의 기존 콘텐츠 필드에 탑재되므로, 도구 콘텐츠가 포함된 모든 경로에 아티팩트가 포함됩니다.
AI SDK
위의 예제와 같이 output(또는 input) 옵션으로 엔벨로프를 전달합니다. Amplitude는 이를 [Agent] Tool Output 속성으로 직렬화합니다.
HTTP API 또는 표준 Amplitude SDK
[Agent] Tool Output 속성을 [Agent] Tool Call 이벤트에 직접 설정합니다. 모든 이벤트에 필요한 전체 이벤트 계약 및 ID 필드에 대해서는 에이전트 분석 설정을 참조하십시오.
curl -X POST https://api2.amplitude.com/2/httpapi \
-H "Content-Type: application/json" \
-d '{
"api_key": "YOUR_API_KEY",
"events": [{
"event_type": "[Agent] Tool Call",
"user_id": "user-123",
"event_properties": {
"[Agent] Session ID": "ticket-42",
"[Agent] Turn ID": 2,
"[Agent] Trace ID": "trace-abc",
"[Agent] Agent ID": "support-bot",
"[Agent] Tool Name": "render_refund_summary",
"[Agent] Tool Success": true,
"[Agent] Tool Input": "{\"order_id\":\"A-1\"}",
"[Agent] Tool Output": "{\"$agent_artifact\":{\"v\":1,\"type\":\"summary\",\"title\":\"Refund total\",\"payload\":{\"headline\":{\"value\":42.5,\"label\":\"Refunded\",\"unit\":\"USD\"}}}}"
}
}]
}'
두 속성 모두 JSON 문자열을 사용하므로 할당하기 전에 Envelope를 직렬화하십시오.
OTLP
도구 스팬에서 이미 사용하고 있는 결과 속성에 Envelope를 넣습니다. Amplitude는 다음 순서로 첫 번째 값을 읽습니다.
| 속성 | 규약 |
|---|---|
gen_ai.output.messages | OpenTelemetry GenAI |
gen_ai.tool.call.result | OpenTelemetry GenAI |
output.value | OpenInference |
도구 입력은 gen_ai.tool.call.arguments 또는 input.value에서와 같이 동일한 패턴을 따릅니다. 도구 이름은 gen_ai.tool.name또는 tool.name에서 가져옵니다. OTLP 엔드포인트 및 헤더에 대한 에이전트 분석 설정을 참조하십시오.
아티팩트 유형
차트
Amplitude가 검증하는 데이터 모양과 그려진 차트의 모습을 암시하는 선택 사항인 kind을(를) 사용하여 차트를 설명하십시오.
shape | 페이로드 | 다음에 대한 사용 |
|---|---|---|
categorical | items: [{ label, value, color? }] | 막대, 열, 파이, 도너츠 |
series | series: [{ label, color?, points: [{ x, y }] }] | 정렬된 x축 상의 선 및 면 |
steps | steps: [{ label, value }] | 퍼널, 워터폴 |
points | points: [{ x, y, size? }], 여기서 x 및 y은(는) 숫자입니다 | 분산형, 거품형 |
matrix | xLabels, yLabels, values: number[][] | 히트맵, 그리드 |
kind은(는) 자유 문자열입니다: bar, column, pie, donut, line, area, 또는 차트라고 부르는 기타 항목. Amplitude는 자체 렌더러를 가진 종류를 그런 식으로 그립니다. 이외의 모든 항목은 모양의 기본 프레젠테이션으로 렌더링되며, 표시되는 메모가 포함되므로 검토자는 항상 자신이 대체를 보고 있다는 것을 알 수 있습니다. 아직 전용 렌더러가 없는 모양(steps, points, matrix)은 레이블이 지정된 테이블로 렌더링되며 동일한 메모를 포함합니다.
선택적 차트 필드: unit, xLabel, yLabel, 및 highlightedIndex (categorical의 경우, 한 항목 강조).
{
"$agent_artifact": {
"v": 1,
"type": "chart",
"title": "Monthly cash flow",
"locale": "en-IN",
"payload": {
"shape": "series",
"kind": "line",
"unit": "INR",
"xLabel": "Month",
"yLabel": "Amount",
"series": [
{
"label": "Cash-in",
"color": "success",
"points": [
{ "x": "Apr 2026", "y": 222389 },
{ "x": "May 2026", "y": 42810 }
]
},
{
"label": "Cash-out",
"color": "danger",
"points": [
{ "x": "Apr 2026", "y": 61453 },
{ "x": "May 2026", "y": 32580 }
]
}
]
}
}
}
요약
필요한 밀도에 맞는 하나의 숫자 카드: 간단한 헤드라인, 비교가 포함된 헤드라인 또는 뒷받침 지표와 사실이 포함된 전체 요약. headline;를 보내십시오. 다른 모든 필드는 선택 사항입니다.
{
"$agent_artifact": {
"v": 1,
"type": "summary",
"title": "Net cash flow",
"scope": { "label": "Sep 2026" },
"payload": {
"headline": {
"value": 25008,
"label": "Net cash flow",
"unit": "SAR",
"tone": "positive"
},
"delta": { "value": 80192, "direction": "up", "comparedTo": "vs August" },
"metrics": [{ "label": "Entries", "value": 41, "tone": "neutral" }],
"facts": [
{ "label": "All-time balance", "value": 918220, "tone": "positive" }
],
"suggestions": ["Show entries for this month"]
}
}
}
tone은(는) positive, negative, 또는 neutral입니다. 이는 판단이 아닌 지시를 전달합니다. suggestions는 에이전트가 제공한 후속 작업입니다. 세션 뷰는 무슨 일이 일어났는지에 대한 기록이며 대화를 계속하는 곳이 아니기 때문에 이들은 레이블로 렌더링됩니다.
옵션
사용자에게 제시한 선택 항목입니다. 누군가가 세션을 검토할 때까지 사용자가 이미 답변했으므로 선택 항목이 레이블로 렌더링됩니다.
{
"$agent_artifact": {
"v": 1,
"type": "options",
"payload": {
"question": "Which quarter should I show?",
"options": [
{ "id": "2026-q1", "label": "Jan – Mar 2026" },
{ "id": "2026-q2", "label": "Apr – Jun 2026" }
],
"reason": "too_many_results"
}
}
}
이것은 도구가 받은 내용을 묻는 것이므로 도구의 input에 이 항목을 첨부하십시오. reason은(는) 에이전트가 질문한 이유에 대해 귀하가 지정한 짧은 코드로, 분석을 위해 저장되며 렌더링되지는 않습니다.
테이블
{
"$agent_artifact": {
"v": 1,
"type": "table",
"title": "Spend by region",
"payload": {
"columns": ["Region", "Sessions", "Spend"],
"rows": [
["EU", 1200, 4517.5],
["US", 880, 91000]
]
}
}
}
셀은 문자열 또는 숫자이며, 숫자는 locale에 의해 형식화되고 오른쪽으로 정렬됩니다. 모든 행에는 열당 정확히 하나의 셀이 필요합니다. Amplitude는 패딩을 적용하는 대신 다른 길이의 행을 거부합니다. 이는 패딩이 데이터를 잘못 표시할 수 있기 때문입니다.
html
다른 유형에서 표현할 수 없는 비주얼의 경우, 자체적 마크업을 전송하십시오.
{
"$agent_artifact": {
"v": 1,
"type": "html",
"title": "Custom SLA gauge",
"payload": {
"html": "<html><head><style>…</style></head><body>…</body></html>"
}
}
}
Amplitude는 다음을 모두 시행합니다:
- 정적 마크업 전용: Amplitude는 스크립트 태그를 거부하며, 렌더링 프레임은 스크립트를 전혀 실행할 수 없습니다. 상호작용은 선언적 유형에 속합니다.
- 완전 독립형: CSS 및 데이터를 인라인합니다. Amplitude는 이미지(
data:포함)와 글꼴, 스타일시트 및 API에 대한 외부 요청을 차단합니다. 시각적 자료에 HTML, CSS 또는 인라인 SVG를 사용합니다. - 탐색 없음: Amplitude는 링크 목적지를 제거하므로 클릭 시 링크가 탐색되지 않고 콘텐츠로 표시됩니다.
- 사용자 정의 스타일 적용: 프레임이 문서를 격리하므로 Amplitude의 테마가 내부에 닿지 않습니다.
- 최대 100,000자.
Amplitude는 html아티팩트를 축소된 상태로 표시하고 렌더링 버튼을 제공하며, 이후 주변 페이지에 영향을 미치지 않는 밀봉된 프레임에 이를 그립니다.
적합한 곳에는 항상 선언적 유형을 사용하는 것이 좋습니다. 이러한 카드는 뷰어의 테마를 따르고, 화면 판독기에서 작동하며, 내보내기에 포함됩니다. html반면, 자유로운 레이아웃을 위해 이 모든 기능을 포기할 수도 있습니다.
제한
Agent 분석 뷰어는 부분 데이터를 렌더링하는 대신 과도한 아티팩트 페이로드를 거부합니다. SDK 또는 내보내기는 수집하기 전에 더 작은 제한을 적용하거나 콘텐츠를 잘라낼 수 있습니다. Envelope, 이스케이프 및 형제(sibling) 필드를 포함하여 전체 직렬화된 콘텐츠 필드를 확인하십시오. 스냅샷이 제한을 초과하는 경우 실패를 리포트하고 크기가 큰 스냅샷 없이 기본 이벤트를 유지하십시오. 맞추기 위해 스냅샷을 잘라내지 마십시오.
| 제한 | 값 |
|---|---|
차트 항목(categorical) | 12 |
| 차트 시리즈 | 4, 각 최대 100 포인트 |
| 단계 | 12 |
| 테이블 | 8열 × 50행 |
| 요약 지표 / 사실 / 제안 | 12 / 12 / 8 |
| 옵션 | 12 |
html | 100,000자 |
| 전체 페이로드 | 256 KB |
개인정보 보호
원시 HTML, 속성, CSS 및 인라인 SVG를 포함하여 Amplitude로 전송할 아티팩트 콘텐츠를 제어합니다. 분석에 대해 승인된 소스 데이터를 선택하고 애플리케이션의 리소스 권한 관리 및 제외 설정을 유지하십시오. Viewer 유효성 검사와 샌드박싱은 렌더링을 보호하지만 수집 전에 민감한 데이터를 제거하지는 않습니다.
AI SDKs
아티팩트 엔벨로프(Artifact Envelope)는 다른 도구 콘텐츠 및 메시지 첨부 파일과 동일한 콘텐츠 캡처 및 편집 설정을 사용합니다. 기존 추적 방법과 구성된 편집 파이프라인을 사용하십시오. 비공개 SDK 헬퍼를 호출하거나 두 번째 편집 패스를 추가하지 마십시오. metadata_only및 customer_enriched와 같은 모드는 콘텐츠 본문을 생략하므로 아티팩트가 렌더링되지 않습니다.
SDK 편집은 구성된 패턴과 콜백을 문자열에 적용합니다. 이는 'best-effort' 방식이며 브라우저 렌더링을 해석하지 않습니다. 예를 들어 HTML 요소로 분할되거나 CSS로 인코딩된 이메일은 페이로드에 남아 있을 수 있습니다. HTML 아티팩트를 전송한다고 해서 해당 콘텐츠에 민감한 데이터가 포함되어 있지 않다는 것을 확인하는 것은 아닙니다. Redaction 설정은 HTML별 생략 정책을 추가하지 않습니다.
구성된 리댁터는 마크업이나 직렬화된 JSON도 변경할 수 있습니다. 가상 픽스처를 사용하여 실제 아웃바운드 엔벨로프의 구문 분석 가능성과 충실도를 확인합니다. 일반적인 SDK 편집 구성을 유지하면서 HTML을 구성하기 전에 제외된 소스 값을 선택하거나 마스크하십시오. 아티팩트별 HTML 준비 API는 필요하지 않습니다. 설치된 SDK의 추적 방법과 전송 제한을 확인하십시오.
HTTP, OTLP 및 가져오기
HTTP, OTLP, Batch, S3 및 웨어하우스 가져오기는 AI SDK 개인정보 보호 설정을 상속받지 않습니다. 데이터가 소스를 떠나기 전에 소스 파이프라인의 캡처, 제외 및 편집 정책을 적용하십시오. 비 SDK 개인정보 보호 가이드 및 연동 절차를 따르십시오.
| 경로 | 정책 시행 지점 |
|---|---|
| HTTP 포워더, 표준 Amplitude SDK, Batch 또는 S3 | 이벤트 콘텐츠를 전송하거나 업로드하기 전에 |
| Native OTLP 또는 stored-span replay | 내보내기가 span 콘텐츠를 전송하기 전에 |
| Warehouse import | Amplitude가 읽기 전에 소스 뷰에서 |
| AI SDK를 통해 추적되는 게이트웨이 또는 로컬 모델 | SDK 추적 방법 및 구성된 콘텐츠 정책 |
Raw HTML은 모든 경로에서 동일한 프로듀서 소유 콘텐츠 경계를 갖습니다. 외부 파이프라인에는 아티팩트별 SDK 도우미가 필요하지 않습니다. 기존 소스 레디터는 여전히 적용되며, 문자열 일치와 동일한 제한이 적용됩니다. 성공적인 이벤트-스키마 또는 아티팩트 유효성 검사는 페이로드에 민감한 데이터가 포함되어 있지 않다는 것을 증명하지 않습니다. 다른 속성과 오류 텍스트를 포함하여 최종 내보낸 콘텐츠에 대해 정책을 확인하십시오.
문제 해결
| 증상 | 원인 |
|---|---|
| Raw JSON, 카드 없음 | The $agent_artifact envelope 키가 누락되었거나 철자가 잘못되었습니다. Envelope가 도구 호출의 input 또는 output에 있는지, 혹은 명시적 AI 응답 아티팩트 첨부파일인지 확인하십시오. |
| 전혀 없으며, 카드와 원시 콘텐츠 없음 | 도구 콘텐츠가 Amplitude에 도달하지 않습니다. input/output (toolInput/toolOutput가 아닌)를 전달하고 있는지, 그리고 콘텐츠 모드가 도구 콘텐츠를 캡처하는지 확인하십시오. |
| "Artifact not rendered"와 이유 포함 | Amplitude가 Envelope를 인식했지만 페이로드가 유효성에 실패했습니다. 이유는 필드의 이름을 지정합니다. 수정하고 다시 emit 하세요. |
| 대체된 프레젠테이션에 대한 참고 사항 | 사용자의 kind 또는 shape에는 아직 전용 렌더러가 없으므로 Amplitude는 가장 근접한 대등한 표현을 그렸습니다. 데이터는 그대로 유지됩니다. |
깨진 것으로 보이는 html카드 | 문서는 외부에 있는 항목을 로드하거나 스크립트에 의존합니다. 해당 데이터에서 충실한 정적 스냅샷을 생성합니다. |
이 내용이 도움이 되었나요?
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.