busya
ff60865183
== User stories == US1: Контекст с дашборда/датасета → /agent с URL params US2: Guardrails card — env badge, 7 risk tones, countdown, permission_denied US3: Tools optimization — retry, timeout, summarise, RBAC + context affinity == Backend == - _context.py (NEW): UIContext validation (7 checks) - _tool_filter.py (NEW): RBAC + context affinity pipeline - _confirmation.py: build_confirmation_contract_v2, permission_denied_payload - tools.py: superset_list_databases, retry/summarise/timeout wrappers - app.py: _inject_uicontext, _inject_env_id_into_tools, database prefetch в runtime context - _persistence.py: prefetch_databases() - agent_superset_explore.py: GET /databases endpoint - _llm_async_http.py, _persistence.py: fix double /v1 в LLM URL (LM Studio Unexpected endpoint) == Frontend == - AgentChatModel.svelte.ts: 5 atoms, 3 actions, countdown, context - AgentChat.svelte: production banner, process steps, debug panel - ConfirmationCard.svelte: 7 risk tones, permission_denied, countdown - ToolCallCard.svelte: retrying/timeout/cancelled states - StreamProcessor.svelte.ts: tool_retry, timeout, permission_denied - TopNavbar: sparkles icon + Ассистент - sidebarNavigation: AI section - DashboardHeader, datasets/+page: contextual AI buttons - Icon: sparkles, brain, cpu icons - tailwind: assistant category colors - i18n: en/ru nav keys == Tests == - 159 backend agent tests (+16 US3: retry, timeout, summarise, contracts) - 2544 frontend tests (+11 model + component tests) - 15 JSON fixtures (10 API + 5 model) == Specs == - specs/035-agent-chat-context/: spec, UX, plan, tasks, research, data-model, contracts, quickstart, traceability, fixtures, checklists Closes #035
78 lines
2.9 KiB
Markdown
78 lines
2.9 KiB
Markdown
# Quickstart: Agent Chat Context & Guardrails
|
||
|
||
**Feature**: 035-agent-chat-context
|
||
**Branch**: `035-agent-chat-context`
|
||
|
||
## Development Setup
|
||
|
||
```bash
|
||
# Backend (terminal 1)
|
||
cd backend
|
||
source .venv/bin/activate
|
||
pip install -r requirements.txt
|
||
python -m uvicorn src.app:app --reload --port 8000
|
||
|
||
# Gradio Agent (terminal 2 — separate process)
|
||
cd backend
|
||
source .venv/bin/activate
|
||
python src/agent/run.py
|
||
# Gradio listens on http://0.0.0.0:7860
|
||
|
||
# Frontend (terminal 3)
|
||
cd frontend
|
||
npm install
|
||
npm run dev -- --port 5173
|
||
# → http://localhost:5173
|
||
```
|
||
|
||
## Verification
|
||
|
||
```bash
|
||
# Backend tests
|
||
cd backend && source .venv/bin/activate && python -m pytest -v
|
||
|
||
# Frontend tests (L1 model + L2 component)
|
||
cd frontend && npm run test
|
||
|
||
# Lint
|
||
cd backend && python -m ruff check .
|
||
cd frontend && npm run lint
|
||
```
|
||
|
||
## Docker
|
||
|
||
```bash
|
||
docker compose up --build
|
||
# Frontend: http://localhost:8000
|
||
# Backend API: http://localhost:8001
|
||
```
|
||
|
||
## Manual Test Flow
|
||
|
||
1. Open `http://localhost:5173/dashboards/10?env_id=ss-dev`
|
||
2. Click "Ask Agent" → navigates to `/agent?objectType=dashboard&objectId=10&envId=ss-dev`
|
||
3. **Verify**: Process steps pill shows «📋 Дашборд #10 · ss-dev»
|
||
4. **Verify**: Debug panel (ℹ️ → Показать) shows UIContext JSON + tool affinity
|
||
5. Type: «Расскажи про этот дашборд» → agent responds with dashboard-specific info
|
||
6. Type: «Задеплой на prod» → confirmation card with «PRODUCTION» badge
|
||
7. Switch EnvSelector to `prod` → chat background changes to warning tint + red banner
|
||
8. **Guardrails test**: Type «Удали дашборд #10» → dangerous confirmation card with 10s countdown
|
||
9. **Tool test**: Trigger a tool that times out → ToolCallCard shows ⏱️ + retry button
|
||
|
||
## Key Files Changed
|
||
|
||
| File | What |
|
||
|------|------|
|
||
| `backend/src/agent/app.py` | `agent_handler` extended with uicontext; `_inject_uicontext()` |
|
||
| `backend/src/agent/_tool_filter.py` | NEW — context-aware tool filtering |
|
||
| `backend/src/agent/tools.py` | Retry wrapper, summarise, timeout helpers |
|
||
| `backend/src/agent/_confirmation.py` | Extended confirmation metadata |
|
||
| `frontend/src/lib/models/AgentChatModel.svelte.ts` | New atoms: uiContext, toolAffinity, dangerousCountdown, isProdContext |
|
||
| `frontend/src/lib/models/AgentChat.StreamProcessor.svelte.ts` | New handlers: tool_retry, tool_timeout, extended confirm_required |
|
||
| `frontend/src/lib/models/AgentChatTypes.ts` | New types: UIContext, ToolAffinityEntry, ConfirmMetadataV2 |
|
||
| `frontend/src/lib/components/agent/AgentChat.svelte` | Prod background + banner + context pill |
|
||
| `frontend/src/lib/components/assistant/ConfirmationCard.svelte` | 7 states: read/write/dangerous/denied + countdown |
|
||
| `frontend/src/lib/components/assistant/ToolCallCard.svelte` | retrying/timeout/cancelled states + retry button |
|
||
| `frontend/src/routes/agent/+page.svelte` | onMount context init from URL params |
|
||
| `frontend/src/lib/stores/assistantChat.svelte.ts` | initialContext field |
|