6. 비스트리밍/완성형 환경 적응 (Non-Streaming Environments)
WebSocket을 지원하지 않아 단일 메시지로만 응답을 렌더링해야 하는 서드파티 플랫폼 연동 게이트웨이(Discord, Slack, Webhook 등)에 대한 지침이다. §2~§5의 원칙은 이러한 환경에서도 최대한 준수하되, 플랫폼 제약에 따라 다음과 같이 적응한다.
6.1. 플랫폼 네이티브 상태 지시기 (Typing Indicator) 활용
슬랙(Slack), 디스코드(Discord) 등 대부분의 메신저 플랫폼은 자체적으로 '입력 중(Typing...)' 네이티브 UX 상태 지시기를 제공한다. 점진적 텍스트 렌더링이 불가능한 환경에서는 이러한 플랫폼 네이티브 기능을 최대한 활용하여 사용자에게 지연에 대한 시각적 피드백을 제공해야 한다 (MUST).
이벤트-지시기 매핑:
| 수신 이벤트 | 지시기 동작 | 비고 |
|---|---|---|
session.turn.start |
'입력 중' 활성화 시작 | 주기적 갱신 개시 |
agent.thinking.delta |
'입력 중' 유지 | 사고 중에도 활성 유지 |
tool.invoke.request |
'입력 중' 유지 또는 커스텀 상태 메시지 발송 | 플랫폼이 상태 메시지를 지원하면 "🔧 도구 실행 중…" 등의 임시 메시지를 발송할 수 있다 (MAY) |
agent.text.done 또는 session.turn.end |
'입력 중' 해제 | 최종 메시지 발송과 동시에 해제 |
agent.error (severity: fatal) |
'입력 중' 즉시 해제 | 에러 메시지로 대체 |
주기적 갱신(Heartbeat): 대부분의 플랫폼은 '입력 중' 상태가 일정 시간(510초) 후 자동 만료된다. 게이트웨이는 Turn이 진행 중인 동안 플랫폼의 만료 주기보다 짧은 간격(예: 35초)으로 '입력 중' API를 반복 호출하여 상태를 유지해야 한다 (MUST).
장시간 작업 대응: 에이전트 응답이 30초 이상 지연될 경우, 중간 상태 메시지 발송 또는 리액션/이모지 업데이트(⏳ → ✅)로 진행 상황을 보강해야 한다 (SHOULD).
6.2. 버퍼링 및 일괄 발송 (Buffered Rendering)
게이트웨이는 agent.text.delta를 메모리에 버퍼링하고, 조립된 전체 텍스트를 단일 메시지로 플랫폼에 발송해야 한다 (MUST).
플랫폼 제한 대응: 대상 플랫폼의 단일 메시지 길이 제한(예: Discord 2,000자)을 초과할 경우, 코드 블록이나 문단이 중간에 훼손되지 않도록 논리적 단위로 분할(Chunking)하여 연속 발송해야 한다 (MUST).
6.3. 사고 과정 텍스트 우회 처리
비스트리밍 환경에서는 긴 사고 과정 텍스트가 화면을 과도하게 점유할 수 있으므로, 플랫폼에서 지원하는 스포일러 태그(예: ||내용||)를 활용하여 기본적으로 가려진 상태로 전송하거나, 최종 응답과 별개의 스레드/메시지로 분리하여 발송해야 한다 (SHOULD).