ss-tools/quickstart.md at e174c11d4a8cd809bb6fdb14244d93436cddd039

Files

busya 12678c637b fix(agent-chat): streaming state leak, document parser magic bytes, HITL flow

### Bugfixes — Agent Chat 'Думаю' State Leak
- fix(agent-chat): loadHistory() now resets streamingState/idle + cancels stale
  submission — prevents 'Думаю' state leak across conversation switches
- fix(agent-chat): onDisconnected/onDisconnectedPermanent cascade to
  streamingState — prevents permanent hang on connection loss during stream
- fix(agent-chat):  guard on isLoadingHistory — prevents false commit
  of 'agent unavailable' fallback when switching conversations
- fix(agent-chat): remove race in _sendNow empty-response check vs Svelte
   microtask (duplicate logic removed,  handles correctly)
- fix(stream-processor): confirm_resolved now appends msg.text to partialText
  instead of dropping it

### Bugfixes — Backend PDF Upload
- fix(document-parser): _detect_format_by_magic() — reads file header magic
  bytes as fallback when Gradio loses filename
- fix(document-parser): improved name extraction — tries orig_name, path stem
- fix(document-parser): @RELATION AgentChatTypes -> AgentChat.Types

### HITL Flow & Agent Chat Improvements
- feat(agent): HITL resume confirm/deny with userId/userJwt/envId propagation
- feat(agent): confirm_required metadata fallback via aget_state() after
  'Event loop is closed' error during interrupt
- feat(agent): interrupt_before re-enabled via AGENT_CONFIRM_TOOLS env var
- feat(frontend): debug panel with connection/stream state monitoring
- feat(frontend): AgentChatModel constructor options + onBeforeSend callback
- feat(frontend): crypto.randomUUID() for local conversation ID on first send

### Backend Agent Refactoring
- refactor(agent): langgraph_setup — monkey-patch for PydanticSerializationError
- refactor(agent): tools.py — dual identity headers, expanded tool set
- refactor(agent): run.py — _find_free_port, Gradio server port fallback
- refactor(agent): app.py — file size validation, message truncation, HITL path

### Frontend
- feat(dashboard-hub): DashboardHubModel with filters, pagination, git actions
- feat(ui): DateRangeFilter component
- feat(i18n): new dashboard keys; cache tooltips fix
- fix(i18n): full run tooltips — cache is NOT ignored

### Semantic Protocol
- chore(agents): update all agents with canonical format
- chore(skills): sync semantics-core, semantics-contracts, molecular-cot-logging

### Housekeeping
- chore: remove stale semantic reports (10 files, Jan 2026)
- chore: update 033-gradio-agent-chat specs, contracts, UX, tasks, tests
- chore: add .agents/ directory (mirrors .opencode/ agent layouts)
- chore: update run.sh with DEV_MODE, port management

2026-06-29 17:15:25 +03:00

2.3 KiB

Raw Blame History

#region AgentChat.Quickstart [C:2] [TYPE ADR] [SEMANTICS quickstart,agent-chat,langchain-v1] @BRIEF Developer quickstart — Gradio + LangChain v1 native stack.

Quick Start (Docker)

docker compose build superset-tools-agent
docker compose up -d
# Frontend: http://localhost:5173 → login → assistant toggle
# Gradio proxy: http://localhost:8000/api/agent/gradio

Quick Start (Local)

# Preferred local launch
DEV_MODE=true ./run.sh

# Open:
# http://localhost:5173/agent

Manual split terminals remain supported:

# Terminal 1: FastAPI
cd backend && source .venv/bin/activate
uvicorn src.app:app --reload --port 8000

# Terminal 2: Gradio Agent
cd backend && source .venv/bin/activate
GRADIO_SERVER_PORT=7860 BACKEND_URL=http://127.0.0.1:8000 python -m src.agent.run

# Terminal 3: Svelte
cd frontend && npm install @gradio/client && GRADIO_URL=http://127.0.0.1:7860 npm run dev -- --port 5173

Verification

# Current backend agent slice
AUTH_SECRET_KEY=test-secret-key-for-agent-run-tests backend/.venv/bin/python -m pytest \
  backend/tests/test_agent/test_agent_handler.py \
  backend/tests/test_agent/test_langchain_tools.py \
  backend/tests/test_agent/test_langgraph_setup.py \
  backend/tests/test_agent/test_run.py

# Current frontend model slice
cd frontend && npm run test -- src/lib/models/__tests__/AgentChatModel.test.ts --run

# Frontend build
cd frontend && npm run build

# Gradio health
curl http://localhost:7860/health

Environment

LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o
JWT_SECRET=<shared with FastAPI>
FASTAPI_URL=http://superset-tools-api:8000
SERVICE_TOKEN_SECRET=<for POST /api/auth/service-token>
AGENT_PREFETCH_DASHBOARD_LIMIT=25
GRADIO_ALLOW_PORT_FALLBACK=false

Troubleshooting

If LM Studio or another local OpenAI-compatible runtime returns request exceeds the available context size, verify the request is using get_tools_for_query() and keep AGENT_PREFETCH_DASHBOARD_LIMIT at or below 25.
The /agent header has a toggleable debug block. Use it to inspect conv_id, pending thread_id, connection/streaming state, active tool calls, and current error.
Repeated guardrail cards after pressing Confirm indicate a regression: resume must create the graph with interrupt_before=[].

#endregion AgentChat.Quickstart

2.3 KiB Raw Blame History