메타데이터

메타데이터 (1.0) (Metadata)

1.0 스펙의 메타데이터를 다루는 페이지예요. 거의 모든 것이 담기는 열린 채널(open channel)로서 무엇을 운반하고, 어떻게 병합되며, 어디에 도달하는지 설명합니다.

출처: 문서

본문

프로토콜의 거의 모든 것이 선택적인 metadata 객체를 담습니다 — 이벤트, 메시지, 도구 호출, 도구, 인터럽트, 재개 항목. 그것은 프로토콜이 모델링하지 않는 것들을 위한 열린 채널입니다. 프로바이더 이름, 지연 시간, 종료 사유, 토큰 수, 트레이스 키, 그리고 애플리케이션이 데이터와 함께 실어 가고 싶은 무엇이든요.

값 (The value)

metadata는 키 기준으로 열려 있습니다. 키 아래에는 null 포함해 어떤 JSON 값이라도 허용돼요 — 그곳의 null은 의미 있는 데이터입니다. 객체 자체는 없거나 객체여야 하며 MUST NOT be null입니다.

미지의 메타데이터 키는 인식할 수 없는 자료가 아니라 프로토콜 법적 항목입니다. 처리 모델은 어떤 키에서도 그것을 떼어내지 않습니다.

키 (Keys)

ag-ui 키는 프로토콜 자신의 용도로 예약되어 있어요. 그 밖의 모든 키는 애플리케이션 공간입니다. 생산자는 자신이 만든 키에 벤더나 애플리케이션 이름을 접두사로 붙여야 하며(SHOULD), 그래야 같은 스트림을 확장하는 두 당사자가 충돌하지 않습니다.

병합 (Merging)

스트리밍 항목은 여러 이벤트로 조립되며, 흥미로운 값들 — 토큰 사용량, 종료 사유 — 은 끝에서야 알 수 있습니다. 그래서 메타데이터는 항목이 열릴 때 고정되지 않고 누적됩니다. 소비자는 항목을 이루는 모든 이벤트의 메타데이터를 키 단위로 병합해야 하며(MUST), 각 키에 대해 마지막 쓰기가 이깁니다.

병합은 재귀하면 안 됩니다(MUST NOT). 키의 값은 완전히 교체되므로, 키 아래의 객체나 배열은 이전에 있던 것과 혼합되지 않고 통째로 교체됩니다.

각 이벤트의 메타데이터가 도달하는 곳 (Where each event's metadata lands)

병합에는 목적지가 필요하고, 그 목적지는 이벤트가 만드는 것 — 항상 메시지는 아닙니다:

Event(s) Merges into
TEXT_MESSAGE_START / CONTENT / END 텍스트 메시지
REASONING_MESSAGE_START / CONTENT / END 추론 메시지
TOOL_CALL_START / ARGS / END 도구 호출 자체 — 이를 소유한 어시스턴트 메시지가 아님
TOOL_CALL_RESULT 그것이 만드는 도구 메시지
ACTIVITY_SNAPSHOT / ACTIVITY_DELTA activity 메시지 — 누적된 메타데이터는 교체 스냅샷에서도 살아남음 (Activity)
chunks (*_CHUNK) 합성된 이벤트가 병합되는 그 무엇이든 (chunk metadata)
그 외 모든 것 (RUN_*, STEP_*, snapshots, RAW, CUSTOM, …) 아무것도 아님 — 아래 참고

참고: 도구 호출 메타데이터가 부모 메시지가 아니라 호출에 도달하는 것은 의도적입니다. 하나의 어시스턴트 메시지가 여러 도구 호출을 소유할 수 있으므로, 부모에 접으면 그 결과가 호출들이 섞인 순서에 따라 달라지게 됩니다. 각 호출이 자신만의 것을 유지하는 것이 모호함을 없애는 방법입니다.

영속 항목을 만들지 않는 이벤트는 병합 목적지가 없습니다. 그 메타데이터는 이벤트 자신의 것이며, 미들웨어와 스트림을 관찰하는 누구에게나 보입니다. 프로토콜은 그것을 다른 곳에 배정하지 않습니다. 소비자는 그것을 표면화할 수 있지만(MAY) — 예를 들어 실행의 RUN_FINISHED 메타데이터를 자기 장부에 — 어떤 규칙도 그것을 요구하지 않습니다.

저장된 메타데이터 (Stored metadata)

메시지, 도구 호출, 도구, 인터럽트, 재개 항목은 metadata를 평범한 저장 필드로 자신의 것으로 담습니다. 위에 나열된 이벤트 외에는 아무것도 그것에 병합되지 않습니다. 실행 입력의 도구 메타데이터나 인터럽트의 것은 단순히 운반자와 함께 여행하는 데이터입니다.

데이터 타입 (Data Types)

Metadata는 스키마 레퍼런스로 정의되며, 각 운반자의 항목은 거기에 metadata 필드를 나열합니다.

더 알아보기 (Learn more)