Agentic UI Contract

Use this when building or refactoring toward agentic product behavior.

Core Contract

• Model decides WHAT to do.

• Tools decide HOW it is done.

• 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

• Define typed block schema first.

• Define deep tool surface second.

• Implement server planner tool loop third.

• Keep client thin: send messages, render blocks, apply client actions.

• 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.