Agentic UI Contract

Use this when building or refactoring toward agentic product behavior.

Core Contract

1. Model decides WHAT to do.
2. Tools decide HOW it is done.
3. UI schema decides HOW it is rendered.

This gives open-ended behavior without fragile freeform execution.

Architecture Shape

• Planner layer (LLM): intent interpretation + tool selection + sequencing.
• Tool layer (deterministic): typed side effects and data reads.
• UI contract layer (typed blocks): constrained rendering catalog.
• Control layer: auth, guardrails, tracing, evals, fallback.

Rules

• Never let model write directly to persistence.
• Never trust model-generated metrics; compute metrics deterministically.
• Keep tool interfaces deep (few, meaningful tools), avoid tiny tool explosions.
• Keep UI blocks strict and versionable.
• Treat planner failure as recoverable; fallback to deterministic behavior.

Implementation Workflow

1. Define typed block schema first.
2. Define deep tool surface second.
3. Implement server planner tool loop third.
4. Keep client thin: send messages, render blocks, apply client actions.
5. Add traces and eval fixtures before widening scope.

Readiness Checklist

• Tool args validated with schema.
• Tool outputs deterministic and structured.
• Planner cannot bypass tools for data claims.
• UI renders only whitelisted block types.
• Planner + tool traces available per turn.
• Deterministic fallback path exists.

Anti-Patterns

• Regex parser as primary intelligence layer.
• Model directly composing arbitrary UI markup/components.
• Over-fragmented tools that mirror internal implementation.
• Allowing model narration to replace data tool calls.
• No eval harness for prompt/tool regressions.