액티비티

액티비티 (Activity)

UI가 자체 위젯으로 렌더링하는 구조화된 진행, 메시지 시퀀스에 유지 — 1.0 버전을 설명드릴게요.

출처: 문서

본문

액티비티는 대화 콘텐츠가 아닌 구조화된 진행이에요 — 검색이 실행 중이거나, 체크리스트가 채워지거나, UI가 자체 위젯으로 렌더링하는 단계 같은 것요. 그것은 시퀀스에서 자기 자리를 유지하도록 메시지로 구체화되지만, 그 콘텐츠는 텍스트가 아닌 객체입니다.

이벤트 (Events)

액티비티는 snapshot–delta 패턴을 바인딩하며, 액티비티 메시지별로 스코프되고 messageId로 매칭돼요.

ACTIVITY_SNAPSHOT

하나의 액티비티 메시지를 생성하거나 교체해요.

{
  "type": "ACTIVITY_SNAPSHOT",
  "messageId": "act-1",
  "activityType": "web_search",
  "content": { "query": "…", "found": 3 }
}
  • activityType은 개방 문자열입니다: 그 집합은 프로토콜이 아니라 프로듀서의 것이에요. 소비자는 인식하지 못하는 유형을 인내해야 해요(MUST).
  • 소비자가 본 적 없는 messageId에 대한 스냅샷은 도착 지점의 시퀀스 위치에 액티비티 메시지를 생성해요.
  • 기존 액티비티에 대한 스냅샷은 그 콘텐츠와 activityType을 교체해요. replace는 선택(OPTIONAL)이며; 부재하면 교체한다는 뜻이고, 그 의미는 규범적입니다. 명시적 replace: false는 소비자에게 기존 메시지를 그대로 두도록 요청합니다 — 콘텐츠 및 activityType; 스냅샷의 값은 그것이 메시지를 생성할 때만 적용돼요. 병합이 아니에요.
  • 교체는 콘텐츠를 교체하지, 지금까지 축적된 메타데이터를 교체하지 않아요 — 메타데이터는 메타데이터 규칙 아래에서 계속 병합돼요. 귀속이 예외입니다: 교체하는 스냅샷은 액티비티를 다시 민팅하므로, 메시지의 subagentRunId는 스냅샷 자신의 것이 되며, 부재하게 되는 것도 포함해요.
  • 기존 액티비티에 대한 replace: false 스냅샷은 소유권을 다시 민팅하지 않아요: 확립된 소유자가 유지되며, 스냅샷 자신의 귀속은 그것과 반드시 일치해야 해요(MUST). 프로듀서 의무는 서브에이전트 규칙이 스트리밍 연속에 두는 것과 같고; 소비자 의무는 의도적으로 더 약합니다 — 확립된 소유자가 유지되며 소비자는 불일치를 거부할 필요가 없는데, 스트리밍 연속의 불일치는 거부되어야 해요.

ACTIVITY_DELTA

하나의 액티비티 메시지의 콘텐츠를 그것에 대한 RFC 6902 패치로 보정해요. 델타의 activityType은 메시지의 그것을 교체해요 — 델타는 그것이 보정하는 액티비티를 재유형화할 수 있고(MAY), 그렇게 하지 않으려는 델타는 필드가 필수이므로 현재 유형을 반복해야 해요(MUST).

  • 프로듀서는 스냅샷으로 생성하지 않은 액티비티 메시지에 대해 델타를 보내선 안 돼요(MUST NOT) — 스냅샷은 패턴이 요구하는 기준선이에요.
  • 존재하지 않는 메시지나 액티비티 메시지가 아닌 것을 명명하는 델타는 건너뜁니다; 소비자는 경고를 표면화해야 하고(SHOULD) 실행을 실패시켜선 안 돼요(MUST NOT).
  • 패치된 결과는 여전히 객체여야 해요: content는 스키마상 객체이며, 프로듀서는 그것을 다른 무엇으로 만들 적용될 패치 — 예를 들어 루트 교체 — 를 보내선 안 돼요(MUST NOT). 소비자는 위반을 감지할 필요가 없어요.
  • 패치 실패 처리는 패턴의 것이며, 같은 messageId의 새 스냅샷으로 재동기화해요.

대화에서의 액티비티 메시지 (Activity messages in the conversation)

액티비티 메시지는 고정 역할 activity로 역사에 나타나요. 그것은 에이전트가 재개하는 대화가 아니라 소비자를 위한 렌더링 자료입니다: 소비자는 run input에 보내는 messages에서 액티비티 메시지를 반드시 제거해야 해요(MUST). 액티비티 메시지가 MESSAGES_SNAPSHOT에서 어떻게 살아남는지는 그 이벤트로 명시됩니다.

메시지 흐름 (Message Flow)

sequenceDiagram
    participant Agent
    participant UI

    Agent->>UI: ACTIVITY_SNAPSHOT (act-1, "web_search", {query, found: 0})
    Note over UI: search widget appears
    Agent->>UI: ACTIVITY_DELTA (act-1, replace /found → 3)
    Agent->>UI: ACTIVITY_DELTA (act-1, add /results/0 …)
    Note over UI: widget updates in place

데이터 타입 (Data Types)

ActivitySnapshotEvent, ActivityDeltaEvent, ActivityMessage는 스키마 참조가 정의합니다. ActivityMessage는 콘텐츠가 문자열이 아닌 객체이므로 기본 메시지를 구성하지 않고 단독으로 서요.

오류 처리 (Error Handling)

잘못된 액티비티 이벤트는 잘못된 알려진 값으로서 치명적이에요. 허용되는 두 실패 — 누락되거나 비액티비티 메시지에 대한 델타, 그리고 적용되지 않는 잘 구성된 패치 — 는 경고하고 건너뜁니다; 둘 다 프로듀서와 소비자가 그 액티비티에 대해 어쩌면 불일치한 채로 남게 하며, 프로듀서의 다음 스냅샷이 수리해요.

더 알아보기 (Learn more)