#region AgentChat.UxDecisions [C:3] [TYPE ADR] [SEMANTICS ux,decisions,agent-chat,native-stack]
@defgroup Ux UX design decisions — revised for LangChain v1 native stack + Gradio native features. Replaces prior decisions.md.
Screen: Agent Chat Panel
Phase 1 — Screen Decomposition
| Decision |
Choice |
Rationale |
| Navigation |
C — Гибрид: drawer 420px + кнопка «Развернуть» → /agent |
Быстрые вопросы в drawer; сложные на /agent |
| Layout |
B — Две колонки на /agent, одно колоночное в drawer |
Структурированно для /agent, drawer компактный |
| Data density |
B — Infinite scroll для сообщений и диалогов + поиск |
Для активного оператора с 50+ диалогами |
Phase 2 — State Exhaustion
| Decision |
Choice |
Rationale |
| Чипсы примеров |
A — Только в новом пустом диалоге |
Welcome-зона. Gradio examples рендерит их нативно |
| Cancel |
A — Единая кнопка Stop с момента отправки. submission.cancel() |
Нативный Gradio cancel |
| Confirmation timeout |
A — Карточка остаётся, кнопки заблокированы, «Повторить» |
Явный контроль |
| Reconnect |
A — 5×5s, затем disconnected_permanent + ручная кнопка |
Предсказуемо |
| Ошибка истории |
A — Сразу ошибка, без кэша |
Консистентность |
| Multi-tab |
A — Client-side gate: GET /api/agent/conversations/{id}/active перед отправкой. Отклоняет вторую вкладку |
Просто, без server-push. Per-user mutex в handler-е + REST gate; градио обрабатывает множественных пользователей нативно |
Phase 3 — Interaction Design
| Decision |
Choice |
Rationale |
| Отправка |
Gradio submit() с additional_inputs=[conversation_id] |
Нативный механизм. История и checkpoint continuity keyed by conversation_id / thread_id |
| Stop |
submission.cancel() — optimistic UI |
Нативный Gradio cancel. Частичный текст сохранён |
| Подтверждение |
Second submit() с additional_inputs[1]="confirm"/"deny" |
Два submit() к одному стриму. LangGraph interrupt_before + PostgresSaver checkpoint; resume uses interrupt_before=[] |
Phase 4 — API Design
| Decision |
Choice |
Rationale |
| Транспорт |
Gradio submit() через nginx proxy. Structured JSON metadata (ChatMessage.metadata.type) |
Нулевой custom код. LangGraph события → структурированные объекты |
| Диалоги REST |
Плоский список с сервера, группировка на клиенте |
API не зависит от визуализации |
Rejected Alternatives
- Custom WebSocket protocol — rejected: @gradio/client не raw WebSocket
- REST confirmation endpoints — rejected: LangGraph checkpointed resume protocol проще
- Ручная передача Gradio history — rejected: handler ignores Gradio
history; persisted messages/checkpoints are keyed by conversation_id
- WebSocket-based active/follower multi-tab pattern — rejected: сложный server-push, требует pub/sub на Gradio. Client-side gate + per-user mutex — accepted.
- @assistant_tool registry для новых тулов — rejected: нативные @tool функции LangChain
#endregion AgentChat.UxDecisions
