ss-tools/quickstart.md at b2d5aa5bf852e7b5b474c78e2fefc4407d6f31f7

Files

busya a99c1d6d01 Improve agent UX and spec sync

2026-07-03 16:47:10 +03:00

3.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 -- AgentChatModel.test.ts

# Hidden runtime-context regression
AUTH_SECRET_KEY=test-secret JWT_SECRET=test-secret backend/.venv/bin/python -m pytest \
  backend/tests/test_agent/test_app.py::TestAgentHandler::test_normal_send_hides_runtime_context_from_saved_history -q

# 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 Диагностика menu. Use it to show the debug panel, copy JSON diagnostics, or force an LLM status check. The debug panel includes conv_id, pending thread_id, connection/streaming state, env/user, active tool calls, and current error.
The /agent process strip is the operator-facing source of truth for current UI state. Ожидаю первый ответ means the request reached streaming state but no first token/tool/confirmation has arrived yet.
If the recovery card appears after 60 seconds, use Проверить LLM first, then retry the last request. Скопировать debug is intended for bug reports and must not be pasted as a normal chat message.
Repeated guardrail cards after pressing Confirm indicate a regression: resume must create the graph with interrupt_before=[].
If an agent asks for exact ISO datetime despite a relative maintenance request ("сейчас", "на 15 минут"), verify hidden runtime context is present in the LLM-facing message and absent from saved history.

#endregion AgentChat.Quickstart

3.3 KiB Raw Blame History