Agent UX Patterns | Cessy Builder Docs

Good agent UX is visible and bounded. The user should understand what the agent read, what it changed, and what remains uncertain.

Pattern: inspect before action

Builder agents should inspect app design before proposing changes. Runtime agents should inspect projection state before executing commands.

Do not let an agent jump from a natural-language request directly to mutation unless the state and authority are obvious and low risk.

Pattern: use the right channel

For runtime work, open or reuse the relevant channel:

entity channel for a specific business object
workspace or team channel for shared coordination
DM only for private user-specific conversation

Put user-visible state changes where the affected users can see them.

Pattern: read before write

Agents should prefer narrow reads:

one projection query with the necessary filters
one entity channel
one user lookup
one reference topic

Broad scans create noise and make review harder.

Pattern: explain important actions

Before executing a sensitive command, the agent should state the intended action and why. After execution, it should confirm the result or explain the failure.

Anti-pattern: mixed authority

Do not put Design MCP mutation tools and runtime user-operation tools into the same casual agent prompt unless the task requires both. Mixed authority makes it harder to review whether the agent changed design or merely operated the app.

Anti-pattern: hidden business logic

Agents should not compensate for a missing command, policy, or permission by inventing private rules. If the model is missing behavior, fix the model through the builder path.