Known Issues#

A maintained register of real defects in the codebase — documented rather than hidden, so nobody rediscovers them the hard way. Fixing one (with its docs update) is the ideal first contribution.

Backend#

GET /agents/{id}/stats is actually a broken delete#

Severity: high (endpoint unusable) · File: routers/agents.py

Despite its name and AgentStatsResponse declaration, the handler counts related data and then deletes the agent (guarded by ?force=true when data exists). It never gets that far: the lookup filters on models.Agent.agent_id, a column that does not exist → AttributeError → 500 on every call. Additionally, its return dict doesn't match the response schema (which itself types agent_name: int).

Root cause: practice code merged into the production router. Fix: delete the endpoint, or rebuild it as an honest DELETE /agents/{id} using models.Agent.id with a correct response schema. Until then there is no supported agent update or delete (Agents lifecycle).

generate_rag_answer builds its prompts inside the context loop#

Severity: medium (latent crash) · File: services/openai_service.py

The system_prompt/user_prompt assignments are indented within the for loop over contexts. Non-empty contexts work (last iteration holds the full accumulated text); an empty list means the variables are never bound → NameError. Unreachable via the API today only because the graph routes empty retrievals to refusal first (details). Fix: dedent the prompt construction below the loop; add an explicit empty-context guard.

Ingestion partial-failure window#

Severity: medium · File: routers/documents.py

The Document row commits (status="indexed", final chunks_count) before per-chunk embedding begins. A mid-file embedding failure leaves a document that claims to be indexed, some vectors in Chroma, and no chunk rows. Recovery: re-upload (Ingestion). Fix: commit the document last, or use an indexing → indexed status transition.

Chroma vectors are never deleted#

Severity: medium (data hygiene / cost) · Files: models.py, document_service.py

SQL cascades remove documents/chunks, but nothing calls documents_collection.delete — vectors persist forever and remain matchable if an agent ID is reused (Models). Fix: delete by vector_id (or where={"document_id": ...}) whenever documents/agents are removed — once such endpoints exist.

Cost logging is inconsistent across endpoints#

Severity: low (misleading metrics)

Only the three workflow LLM stages log model_name/tokens/cost; chat, single-agent analyze, search, ask, and embeddings do not — so dashboard cost/token totals understate reality (coverage map). The documents router even has its own log_tool_call copy lacking the cost parameters. Fix: extract one shared log_tool_call, attach estimate_openai_cost at every LLM step.

Schema/prompt drift on priority#

Severity: low

EmailAnalysisResponse allows "urgent" but the analyzer prompt permits only low|medium|high — and the schema isn't bound as a response_model anyway, so nothing enforces either (Schemas). Fix: bind the schema and align the Literal with the prompt.

Numeric data stored as strings#

Severity: low (chronic friction)

ToolCall.success ("true"/"false"), estimated_cost, and WorkflowRun.quality_score are strings, forcing safe_int/safe_float parsing everywhere (Design Decisions). Fix: Boolean/Numeric columns + a startup migration — note additive-only limits mean new columns + backfill-on-read, or the Alembic move.

Minor code-hygiene items#

• Duplicate/shadowed import of generate_rag_answer in documents.py (harmless).
• Three separate OpenAI clients across services (OpenAI Integration).
• main.py FastAPI title has a leading space (" AgentOps AI").
• Scratch files (delete.py, practice_solution.py, …) live inside backend/app/ (Project Structure).

Frontend#

Placeholder affordances#

Severity: low (UX confusion) — documented in Frontend Overview:

• AgentCard Open → /agents/{id} (route not implemented); Edit and Run Workflow buttons have no handlers.
• Sidebar Workflows/Operations sections link to #.
• Topbar search input and Optimize Prompt button are decorative.
• Agent status pill hardcodes "Active".

Dashboard charts show sample data#

Severity: medium (can mislead) — the "Tool calls over time" bars and "Average latency" curve in MetricCharts are hardcoded shapes; only the cost banner reflects real data (Pages). Fix: a time-bucketed tool-calls endpoint, then real series.

Dashboard pinned to agent 1#

Severity: low — default AGENTOPS_DASHBOARD_API_URL hardcodes /agents/1/dashboard; fresh databases show the error panel until agent 1 exists (Configuration). Fix: agent-picker + route param.

Process for this page#

Fixed an issue? Remove its entry here, update the pages that reference it (each entry links them), and note the fix in your PR (Contributing). Found a new one? Add it with the same format: severity, file, behavior, root cause, fix sketch.