M2.9 — UI tools generative (`render_*`) déclarés dans les agents

[zestones]

Note

Milestone: M2 — MCP Server
Planning doc: docs/planning/M2-mcp-server/issues.md

Ajoutée après alignement front/back. Contexte complet dans docs/planning/ALIGNMENT.md.

Scope. En plus des 14 data tools MCP, exposer 9 tools render_* aux agents
pour qu'ils puissent émettre des events ui_render consommés par le frontend
(generative UI inline dans le chat).

Pas d'implémentation Python. Ces tools n'ont pas de code métier — ce sont
juste des schémas passés au LLM. Quand un agent appelle render_signal_chart,
l'orchestrateur capture le tool_use, broadcast un event ui_render via WSManager,
et retourne immédiatement un tool_result = "rendered" sans effet DB.

Fichier. backend/agents/ui_tools.py — module avec les 9 schémas + helper.

Les 9 tools.

Tool name	Used by	Props schema (résumé)
render_signal_chart	Investigator, Q&A	{signal_def_id, window_hours, mark_anomaly_at?, threshold?}
render_equipment_kb_card	KB Builder, Q&A	{cell_id, highlight_fields?}
render_work_order_card	Work Order Gen	{work_order_id, printable}
render_diagnostic_card	Investigator	{title, confidence, root_cause, contributing_factors[], pattern_match_id?}
render_correlation_matrix	Investigator	{sources[], impact_matrix[][]}
render_pattern_match	Investigator	{current_event, past_event_ref, similarity}
render_bar_chart	Q&A	{title, x_label, y_label, bars[]}
render_alert_banner	Sentinel (auto-emit)	{severity, cell_id, message, anomaly_id}
render_kb_progress	KB Builder	{steps[{label, status}]}

Note

Decided — tools locaux agent, pas via FastMCP.
Même règle que submit_rca
(cf. M4.3) : tool d'output structuré = local, tool de lecture/écriture DB = MCP.
Les render_* sont déclarés inline dans chaque agent concerné et concaténés à
tools_schema avant l'appel Anthropic.

Pattern d'intégration dans le system prompt de chaque agent.

Pour rendre visuels tes résultats, tu peux appeler :
- render_signal_chart(...) pour afficher une courbe
- render_diagnostic_card(...) pour afficher ton diagnostic final
- render_work_order_card(...) pour afficher un WO
Appelle-les quand c'est plus parlant qu'une réponse texte seule.

Handler orchestrateur.

if tool_name.startswith("render_"):
    await ws_manager.broadcast("ui_render", {
        "agent": agent_id,
        "component": tool_name.removeprefix("render_"),  # SignalChart, DiagnosticCard, ...
        "props": args,
        "turn_id": turn_id,
    })
    tool_result = {"type": "tool_result", "tool_use_id": tu_id, "content": "rendered"}
    # pas de persistence DB, pas de side-effect

Pourquoi critique. Sans ces tools, Q&A/Investigator répondent en markdown texte
uniquement. Avec, le chat affiche inline des graphes, cards, diagnostics rendus
par l'agent lui-même — pattern Generative UI / Claude artifacts. C'est ce qui
rend la démo visuellement agentique et distingue ARIA d'un chatbot classique.

Acceptance.

• Investigator émet ui_render pour render_diagnostic_card à la fin du RCA
• Q&A émet ui_render pour render_signal_chart sur question relative à un signal
• Frontend (M7.5 + M8.1–M8.3) rend les composants correctement

Bloque. Frontend M7.5 (artifact registry), M8.1 / M8.2 / M8.3 (artifacts).

---

Generative UI flow

sequenceDiagram
    autonumber
    participant LLM as Claude (Investigator)
    participant Orch as Agent orchestrator
    participant WS as WSManager
    participant Reg as Artifact Registry (M7.5)
    participant UI as Chat / Dashboard

    LLM->>Orch: tool_use render_diagnostic_card({props})
    Orch->>WS: broadcast('ui_render', {agent, component, props, turn_id})
    Orch-->>LLM: tool_result 'rendered' (no DB hit)
    WS-->>Reg: ui_render event
    Reg->>Reg: validate Zod schema
    Reg->>UI: render <DiagnosticCard {...props} />

Loading

Important

No backend persistence, no side-effect. The render tools are pure UI signals
the LLM is allowed to emit. The frontend ArtifactRenderer (M7.5) is the only
consumer.

[zestones]

Audit findings — M2.9

Important

Full audit at docs/audits/M2-mcp-server-audit.md §1 (M2.9). Status: clean architecture, two props-data mismatches that will visibly break the demo if left unaddressed.

Gaps to close before coding

1. render_signal_chart — props carry NO chart data

Props are {signal_def_id, window_hours, mark_anomaly_at?, threshold?}. The actual time-series is not there. The M8.1 frontend component must re-fetch the data via GET /api/v1/signals/{def_id}/data?....

• Confirm the data endpoint exists and returns bucketed data fast enough for an inline chart (< 500 ms for a 24 h window). If only raw data exists today, consider exposing the new signal_data_bucketed method (see M2.3 audit) as an HTTP endpoint too — otherwise the UX is "LLM finishes → 3 s of blank chart → data appears".
• Document in this issue: chart data flow is tool call → ui_render event → frontend component → REST fetch back to backend. Anyone looking at the chart "where does the data come from?" deserves an answer.

2. render_correlation_matrix — NO data source behind it

Warning

Props are {sources[], impact_matrix[][]}. A numeric correlation matrix. There is no MCP tool that computes correlations. The LLM will either (a) synthesise plausible-looking but made-up numbers — lethal for a predictive-maintenance pitch to judges — or (b) refuse to call the tool.

• Decide one of:
  • (A) Drop the artifact. render_signal_chart with multi-signal overlay (see M2.3 signal_def_ids: list[int] recommendation) already carries the visual message for the demo. Recommended — cheapest and lowest risk.
  • (B) Add a new MCP tool compute_correlations(signal_def_ids, window_start, window_end) -> {matrix: list[list[float]], labels: list[str]}. ~45 min using Postgres corr() or numpy in-process. Keeps the artifact but raises scope.

3. Multi-tenant cell_id filter gap

ROADMAP §2.9 says "frontend filters by cell_id in payload". render_signal_chart props has signal_def_id, not cell_id. Frontend would need a cached signal_def → cell map.

• Add cell_id: int to every render_* props where not already present. Redundant with signal_def_id technically, but explicit filtering is worth 4 bytes per event.

4. render_alert_banner is NOT LLM-exposed

Sentinel has no LLM loop — it emits ui_render events directly via ws_manager.broadcast(...). render_alert_banner is therefore never in any agent's tools_schema; it's a pure frontend-channel event reusing the render event shape.

• Add a one-line note in this issue so a future reader doesn't search for render_alert_banner in Sentinel's tools_schema (it's not there, and that's correct).

Confirmed sound

• Local-tool-per-agent split (vs via FastMCP) is architecturally right. Output-shape tools do not belong in a DB-access server.
• "rendered" string as tool_result is fine — the LLM just needs any non-error result to keep the loop alive.
• Per-agent tools_schema = await mcp_client.get_tools_schema() + [RELEVANT_RENDER_TOOLS] is the right composition pattern.

Event contract summary (frontend consumers)

sequenceDiagram
    participant Agent as Investigator / Q&A / KB Builder
    participant Orch as Orchestrator
    participant WS as WSManager
    participant FE as Frontend
    participant API as /api/v1/signals/.../data

    Agent->>Orch: tool_use render_signal_chart
    Orch->>WS: broadcast ui_render {component, props, cell_id, turn_id}
    Orch->>Agent: tool_result "rendered"
    WS->>FE: ui_render event
    FE->>FE: filter by cell_id
    FE->>API: GET bucketed data (REST re-fetch)
    API-->>FE: time series
    FE->>FE: render <SignalChart props + data/>

Loading

Blocks

• Frontend M7.5 (artifact registry/dispatcher) — contract must be stable before it wires components.
• Frontend M8.1 / M8.2 / M8.3 — each component needs its props schema locked.

[zestones]

Implementation summary — M2.9 UI render tool schemas

Note

Delivered backend/agents/ui_tools.py with 7 LLM-callable render tools and the ALERT_BANNER_SCHEMA sentinel constant. All audit gaps addressed. 72 unit tests pass (+8 new).

Decisions taken

Audit gap	Decision
#1 render_signal_chart data flow	Documented in module docstring: frontend component fetches actual time-series from GET /api/v1/signals/data/{signal_def_id} after the ui_render event arrives. Endpoint already exists.
#2 render_correlation_matrix	Dropped. No MCP tool computes correlations; the LLM would synthesise plausible-looking but hallucinated numbers — fatal for a predictive-maintenance pitch. render_signal_chart with multi-signal overlay covers the visual message. A future compute_correlations MCP tool can re-introduce it.
#3 cell_id on all tools	Added as required prop to all tools except render_bar_chart (optional there — Q&A can produce general charts not tied to one cell).
#4 render_alert_banner not LLM-exposed	ALERT_BANNER_SCHEMA exported separately, explicitly excluded from all per-agent LLM lists. Module comment explains Sentinel emits this directly via ws_manager.broadcast.

Files

File	Change
backend/agents/__init__.py	NEW — package marker
backend/agents/ui_tools.py	NEW — 7 LLM render tool schemas + ALERT_BANNER_SCHEMA + per-agent lists
backend/tests/unit/agents/test_ui_tools.py	NEW — 8 unit tests

Per-agent tool composition

flowchart LR
    A["mcp_client.get_tools_schema()"] --> I["Investigator"]
    A --> Q["Q&A"]
    A --> K["KB Builder"]
    A --> W["Work Order Gen"]

    SC["render_signal_chart"] --> I
    SC --> Q

    DC["render_diagnostic_card"] --> I
    PM["render_pattern_match"] --> I

    BC["render_bar_chart"] --> Q
    KB["render_equipment_kb_card"] --> Q
    KB --> K

    KBP["render_kb_progress"] --> K
    WO["render_work_order_card"] --> W

Loading

Orchestrator pattern (for M3/M4 implementers)

if tool_name.startswith('render_'):
    await ws_manager.broadcast('ui_render', {
        'agent': agent_id,
        'component': tool_name.removeprefix('render_'),
        'props': args,
        'turn_id': turn_id,
    })
    tool_result = 'rendered'   # no DB hit

Quality gates

Gate	Result
make lint	0 errors
make typecheck	0 errors (5 pre-existing warnings unrelated)
make test	72 passed, 1 deselected (was 64, +8)

Note

ACs #1 and #2 (Investigator/Q&A emitting ui_render events) are M3/M4 scope — they require the agent orchestrator loop which does not exist yet. This issue delivers the schema contracts that unblock those milestones. AC #3 (frontend rendering) is M7.5/M8.x scope.