diff --git a/docs/base-app/agents/building-quality-agents.mdx b/docs/base-app/agents/building-quality-agents.mdx index f63ec37e9..306961f9f 100644 --- a/docs/base-app/agents/building-quality-agents.mdx +++ b/docs/base-app/agents/building-quality-agents.mdx @@ -1,16 +1,14 @@ ---- -title: 'UX Guidelines' -description: Learn the best practices and guidelines for creating quality agents -sidebarTitle: 'UX Guidelines' ---- +# UX Guidelines for Base App Agents + +*Updated for 2026* As you start building, review these guidelines to understand what makes an agent successful in the Base app. We recommend trying out existing agents in the app first to get a feel for the quality bar, what works well, and areas for improvement. -## Build a high quality foundation +## Build a High Quality Foundation Your agent should provide a seamless, professional experience that users will want to engage with repeatedly. Here are the core requirements: -### Responding to messages +### Responding to Messages **Multi-Channel Support** - Respond to both DMs and group chats appropriately @@ -34,8 +32,6 @@ In group chats, agents should only respond when: This prevents spam and ensures agents participate naturally in group conversations. ### Communication Style - -**Sound Human** - Use conversational, fun, and clear language - Keep responses polished but not robotic - Match the energy and tone of the conversation @@ -45,18 +41,15 @@ This prevents spam and ensures agents participate naturally in group conversatio - Always explain why the information is needed - Respect user privacy and data minimization principles -## Craft compelling onboarding - +## Craft Compelling Onboarding Your agent's first impression is critical. The onboarding message should immediately communicate value and give users a clear path forward. ### Great Onboarding Message Structure - 1. **Introduce the agent** - Quick, friendly greeting with the agent's name 2. **Explain capabilities** - Clear, specific examples of what it can do -4. **Use quick select buttons** - Make it easy for users to select an action to take with the agent +3. **Use quick select buttons** - Make it easy for users to select an action to take with the agent ### Example: High-Quality Onboarding - ``` hey, i'm bankr. i can help you trade, transfer, and manage your crypto. here's the rundown: @@ -75,18 +68,16 @@ what do you want to do first? - Ends with a direct call-to-action ### Example: Poor Onboarding - ``` Gm! What can I help you with? ``` - **Why this fails:** - Generic greeting with no context - No explanation of capabilities - Puts burden on user to figure out what to do - No clear value proposition -## Showcase unique value +## Showcase Unique Value ### Solve Real Problems @@ -111,12 +102,12 @@ Focus on helping users: - Create ongoing value that brings users back **Plan the User Journey** + 1. **Define the ideal user experience first** 2. **Craft agent messages around that journey** 3. **Guide users through progressive value discovery** ### Continuous Engagement Strategy - As users complete actions with your agent: - **Show clear next steps** - Always give users something else to try @@ -125,11 +116,116 @@ As users complete actions with your agent: - **Prevent one-and-done usage** - Build features that require return visits ### Examples of Engagement Features - - **Progressive features** - Unlock new capabilities as users engage more -- **Personalization** - Learn user preferences and customize experiences +- **Personalization** - Learn user preferences and customize experiences - **Social elements** - Enable sharing achievements or inviting friends - **Recurring value** - Automated tasks, alerts, or regular check-ins + - **Gamification** - Points, levels, or achievement systems +## 2026 Best Practices for AI Agents + +### Agentic UX: Designing for Autonomy + +Modern users expect agents to take initiative and complete tasks on their behalf. When designing agentic experiences: + +**Build Trust Through Transparency** +- Show clear previews of what actions the agent will take before executing +- Provide activity logs so users can review what happened +- Enable simple undo/stop controls for all autonomous actions +- Display clear role statements: "I can [do X]. I won't [do Y] without your approval." + +**Start Small, Scale Gradually** +- Begin with bounded, low-risk tasks (checking status, simple transfers) +- Progressively unlock more complex autonomous workflows as users build trust +- Design safe failure modes with graceful recovery paths + +**Context Awareness** + +- Make it clear what information the agent is using to make decisions +- Show what data sources are being accessed +- Explain what's missing or uncertain that might affect the action + +### Predictive & Adaptive Interfaces + +Agents should anticipate user needs based on patterns and context: + +**Smart Personalization** +- Reorder quick actions based on time of day or user history +- Surface frequently-used features more prominently +- Reduce repetitive inputs by remembering preferences + +**Correction Mechanisms** +- Always provide quick ways to reset or correct misguided predictions +- Let users easily override automated suggestions +- Learn from corrections to improve future predictions + +### Privacy-First Design (2026 Standards) + +With increasing regulatory requirements and user awareness: + +**Visible Privacy Controls** +- Make data usage visible at the moment of action, not hidden in settings +- Offer frictionless opt-outs for data collection and personalization +- Explain clearly where data goes and what it's used for +- Design consent flows that are respectful, clear, and fast + +**Data Minimization** +- Only request data that's truly necessary for the current task +- Provide clear explanations for why each piece of data is needed +- Offer alternatives that require less personal information when possible + +### Accessibility & Inclusive Design + +Accessibility is now mandatory in many jurisdictions. Your agent should: + +**Universal Design Principles** +- Support voice interactions for users with mobility challenges +- Ensure all visual information has text alternatives +- Provide clear, simple language that works across literacy levels +- Test with diverse user groups including people with disabilities + +**Sustainable UX** +- Optimize for low-bandwidth scenarios +- Minimize unnecessary animations or heavy assets +- Consider energy efficiency in your design choices + +### Micro-Interactions & Feedback + +Small details create trust and delight in 2026: + +**Intelligent Feedback** +- Use micro-interactions to communicate system state and progress +- Show when the agent is thinking, processing, or waiting +- Provide progressive disclosure of complex actions +- Celebrate completed tasks with subtle, satisfying animations + +**Error Recovery** +- Design for graceful failures with clear next steps +- Provide helpful error messages that explain what went wrong +- Offer alternative paths when the primary action fails + +## Measuring Success + +Track these key metrics to understand your agent's performance: + +**Engagement Metrics** +- Response time (target: < 5 seconds) +- Message completion rate +- Return user rate (7-day, 30-day) +- Actions per conversation + +**Quality Metrics** +- User satisfaction ratings +- Support ticket volume +- Error/failure rates +- Undo/correction frequency + +**Growth Metrics** +- New user acquisition +- Referral/share rate +- Feature adoption curve +- Long-term retention + +---