🛠️ Bonus: Agent Design Assistant¶
Primary Feature: Meta-agent — helps users design and build agents in Agent Builder Status: ✅ Built (Corp) Built in: Corp ✅ 2026-04-09 | Lab ⬜
Inspired by: RIA (Reliable Instruction Author) by Kris Wilson — we built a significantly enhanced version that covers the full agent design lifecycle, not just instructions.
🎯 Problem It Solves¶
"I want to build an agent but I don't know where to start. What should the instructions say? What knowledge sources do I need? What are the gotchas?"
This is a meta-agent — an agent that helps people design and build other agents. It walks users through:
- Discovery questions (understand the use case)
- Feasibility check (Agent Builder vs Copilot Studio)
- Full spec generation (name, description, instructions, knowledge, prompts, tests)
- Review and refinement
Why This Agent?¶
After building 10 agents, we captured every gotcha, best practice, and design pattern into one agent. It's the distillation of everything we learned.
Compared to RIA (Kris Wilson's Version)¶
| Aspect | RIA (Original) | Agent Design Assistant (Ours) |
|---|---|---|
| Scope | Instructions only | Full agent design lifecycle |
| Knowledge guidance | ❌ None | ✅ Recommends sources based on use case |
| Limitation awareness | ❌ None | ✅ Warns when Studio is needed |
| Boundary enforcement | ❌ Not covered | ✅ CAPS technique, fallback text, redirects |
| Starter prompt design | ❌ Not covered | ✅ Working + boundary test prompts |
| Real-world gotchas | ❌ None | ✅ SP indexing, Excel toggle, URL depth, etc. |
| Test plan | ❌ None | ✅ Suggests test scenarios including boundary tests |
| Feasibility check | ❌ None | ✅ Agent Builder vs Copilot Studio assessment |
🏗️ Architecture¶
┌──────────────────────────────────────────────────────────────┐
│ User: "I want to build an agent for X" │
└──────────────────────┬───────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Agent Design Assistant │
│ │
│ Step 1: DISCOVERY │
│ Ask about: problem, users, data sources, capabilities, scope │
│ │
│ Step 2: FEASIBILITY CHECK │
│ Agent Builder OK? Or needs Copilot Studio? │
│ ⚠️ Flag: actions, APIs, workflows, multi-channel │
│ │
│ Step 3: GENERATE SPEC │
│ Name | Description | Instructions | Knowledge | Prompts │
│ │
│ Step 4: REVIEW & REFINE │
│ "Want me to adjust anything?" │
│ │
│ Knowledge: │
│ 📤 agent-builder-complete-guide.txt (all our learnings) │
│ 🎨 Artifacts ON (generates formatted specs) │
└──────────────────────────────────────────────────────────────┘
✅ Capabilities Used¶
| Capability | Used? | Details |
|---|---|---|
| SharePoint Knowledge | ❌ | Not used |
| Web Grounding | ❌ | MS Learn URLs too deep (Gotcha!) — using file upload instead |
| File Uploads | ✅ | Complete guide with all learnings from 10 agent builds |
| Graph Connectors | ❌ | Not used |
| Office Artifacts | ✅ | ON — generates formatted agent specs |
| Teams + Email | ❌ | Not used |
| Instructions | ✅ | 4-step guided process with feasibility checks |
| Starter Prompts | ✅ | 5 working + 1 boundary |
📝 Instructions Used¶
Copy-paste these instructions when building the agent:
You are the Agent Design Assistant — an expert guide that helps people design and build declarative agents in Microsoft 365 Agent Builder. You walk users through the FULL design process step by step.
## Your Process (follow this order)
### Step 1: Discovery — Understand the Use Case
Ask these questions ONE AT A TIME (don't dump them all at once):
1. "What problem are you trying to solve? Describe the daily pain point."
2. "Who will use this agent? (e.g., your team, whole org, specific department)"
3. "What kind of information does the agent need to answer from?" (internal docs, public websites, emails, chats, external systems)
4. "Should the agent create documents (Word, Excel, PPT) or just answer questions?"
5. "Are there things the agent should REFUSE to do? (e.g., no legal advice, no personal data)"
### Step 2: Feasibility Check — Agent Builder vs Copilot Studio
Based on the answers, assess whether Agent Builder can handle the requirements:
If the user needs ANY of these, flag it clearly:
- Custom API integrations → "This requires Copilot Studio, not Agent Builder"
- Multi-step workflows with branching → "This requires Copilot Studio"
- Actions (send emails, create events, update records) → "Agent Builder can't take actions — only answer questions and generate documents. For actions, you need Copilot Studio"
- Multi-channel deployment (web, Slack, WhatsApp) → "Agent Builder only deploys to M365 Copilot Chat and Teams. For other channels, use Copilot Studio"
- Custom UI widgets or Adaptive Cards → "Agent Builder doesn't support custom UI"
If Agent Builder IS sufficient, say: "Great news — Agent Builder can handle this! Let's design it."
### Step 3: Generate the Agent Specification
Based on the discovery, generate ALL of these:
Name: Suggest 2-3 names (clear, specific, memorable)
Description: Draft a 1-2 sentence description
Icon suggestion: Suggest an emoji or icon theme
Instructions: Generate complete instructions using this structure:
- Purpose/Role statement
- Rules (with CAPS enforcement for critical boundaries using NEVER, ALWAYS, ONLY, MUST)
- Topics covered
- Topics NOT covered (with exact fallback response text for each)
- Response format
Note: Maximum 8,000 characters. Warn if instructions are getting long.
Knowledge Sources: Recommend which sources to use:
- SharePoint sites (for internal docs — warn about new site indexing delay)
- Web URLs (for public sites — max 4, 2 levels deep, warn about limitations)
- File uploads (for specific docs — max 20, warn Excel needs capability toggle)
- Teams + Email (for communication search — warn email can't be scoped)
- Graph Connectors (for external systems — must be pre-configured by admin)
Capabilities: Recommend ON or OFF for "Generate documents, charts, and code"
Starter Prompts: Generate 8-10 prompts:
- 6-8 working prompts testing different capabilities
- 2-3 boundary test prompts (prefixed with B1, B2)
Test Plan: Suggest 3-5 test scenarios including boundary tests
### Step 4: Review and Refine
After generating the spec, ask: "Want me to adjust anything — the name, instructions, knowledge sources, or prompts?"
## Key Warnings to Include (from real-world experience)
- SharePoint: New private sites can take hours to be indexed. Workaround: use File Upload instead
- Web URLs: Only 4 max, 2 levels deep, no PDFs crawled, no query parameters
- Email: Cannot be scoped to specific folders or senders
- Excel files: Require the "Generate documents" capability to be ON
- Boundaries: Soft rules get ignored. ALWAYS use the three-part formula: CAPS keyword + exact fallback text + positive redirect
- "Search all websites" toggle is DIFFERENT from specific web URLs
- File uploads work almost immediately (even while showing "Preparing")
- Always test boundary prompts before sharing the agent
## Response Format
ALWAYS format your output in Markdown so the user can easily copy-paste into Agent Builder.
## What You Do NOT Do
- NEVER build the agent yourself (you design the spec, the user builds it in Agent Builder)
- NEVER guarantee that specific features will work in the user's tenant (suggest testing)
- NEVER answer questions unrelated to agent design. If asked, respond: "I specialise in helping you design agents for Agent Builder. For other questions, try asking Copilot directly!"
🛠️ Quick Build Guide (Copy-Paste Ready)¶
| Step | Action |
|---|---|
| 1 | Go to microsoft365.com/chat → Agents → Create Agent → Skip to configure |
| 2 | Name: Agent Design Assistant |
| 3 | Description: Helps you design and build agents in Agent Builder — asks discovery questions, recommends knowledge sources, generates instructions, and warns about limitations |
| 4 | Instructions: Paste the full instruction block from above |
| 5 | Knowledge → Files: Upload agent-builder-complete-guide.txt from C:\ssClawy\agent-builder-demo-content\a11-agent-helper\ |
| 6 | Knowledge → Everything else: OFF (no web — MS Learn URLs are too deep, no Teams, no email) |
| 7 | Search all websites: OFF |
| 8 | Generate documents, charts, and code: ✅ ON (so it can generate formatted specs) |
| 9 | Starter Prompts: Add all prompts from the table below |
| 10 | Create and test with T4 (feasibility check) — it should flag Copilot Studio requirement |
Demo Files to Have Ready¶
| File | Location | Purpose |
|---|---|---|
agent-builder-complete-guide.txt |
a11-agent-helper/ |
Upload as knowledge (all learnings) |
demo-test-scenarios.txt |
a11-agent-helper/ |
7 customer scenarios for your reference (don't upload — use manually) |
🚨 Gotchas & Design Decisions¶
🌐 Gotcha 1: MS Learn URLs Too Deep for Web Grounding¶
We wanted to add MS Learn best practices as a web URL:
https://learn.microsoft.com/en-us/microsoft-365/copilot/extensibility/declarative-agent-instructions
domain lvl1 lvl2 lvl3 lvl4 lvl5
❌ 5 LEVELS — max is 2
Workaround: Downloaded the content and included it in the uploaded knowledge file. Actually works better because our file also contains real-world gotchas not in the official docs.
🤖 Gotcha 2: The Agent Can't Build Agents — Only Design Them¶
The Agent Design Assistant generates a complete specification (name, instructions, knowledge config, prompts). The user then takes that spec and builds the agent manually in Agent Builder. The meta-agent cannot programmatically create agents.
📋 Knowledge File Contains All Session Learnings¶
The agent-builder-complete-guide.txt file includes:
- All Agent Builder capabilities and limits
- Knowledge source selection guide with gotchas
- Instructions best practices with CAPS technique
- Starter prompt design guidance
- Common mistakes from our 10-agent build experience
📁 Demo Assets¶
| File | Location | Purpose |
|---|---|---|
agent-builder-complete-guide.txt |
a11-agent-helper/ | Knowledge file (uploaded to agent) |
demo-test-scenarios.txt |
a11-agent-helper/ | 7 customer demo scenarios |
💬 Starter Prompts¶
| # | Title | Prompt |
|---|---|---|
| T1 | 🆕 Help me build | I want to create an agent but I am not sure where to start. Can you help me design one? |
| T2 | 📝 Review instructions | I have written some instructions for my agent. Can you review them and suggest improvements? |
| T3 | 🔍 What sources? | My team has internal policies on SharePoint, public web data, and IT uses ServiceNow. What knowledge sources should I use? |
| T4 | ⚠️ Feasibility | I need an agent that reads customer emails, searches our CRM, and automatically sends follow-up emails. Is this possible in Agent Builder? |
| T5 | 🎯 Quick design | I need a quick FAQ agent for my team's SharePoint site about holiday and leave policies. Design it for me. |
| B1 | 🚫 Off topic | What is the best laptop for coding? |
🧪 Demo Test Scenarios (7 scenarios)¶
| # | Scenario | Customer Type | Key Test |
|---|---|---|---|
| 1 | 🏢 HR Policy Bot | Simple | Full guided design + Studio warning |
| 2 | 💼 Sales RFP Helper | Medium — multi-source | Web + Files combo recommendation |
| 3 | 👔 Executive Assistant | Complex — hits limits | Correctly splits "can do" vs "needs Studio" |
| 4 | 🎧 Customer Support | Needs Studio entirely | Flags website + API + handoff = Studio |
| 5 | ❓ Quick FAQ Bot | Very simple | Simplest possible 5-minute design |
| 6 | ⚖️ Compliance Agent | Sensitive data | Permissions, labels, mandatory disclaimers |
| 7 | 🔧 Instructions Review | Improving existing | Spots weak boundaries, rewrites with CAPS |
👍 Pros & Cons¶
| Pros | Cons |
|---|---|
| ✅ Captures all learnings from building 10 agents | ❌ Can't actually build the agent (spec only) |
| ✅ Guided step-by-step process | ❌ MS Learn URLs too deep for web grounding |
| ✅ Honest about limitations (flags Studio requirements) | ❌ Knowledge file needs updating as Agent Builder evolves |
| ✅ Perfect customer enablement tool | ❌ May give slightly outdated advice if features change |
| ✅ Great standalone video/demo content |
🎤 Demo Talking Points¶
- "An agent that builds agents" — Meta-level demo that shows the art of the possible
- "Everything we learned, in one agent" — 10 agents worth of gotchas, patterns, and best practices
- "Honest about limits" — Try asking for something Agent Builder can't do. It'll tell you to use Copilot Studio instead of pretending it can help
- "Customer enablement tool" — Give this agent to your customers. It helps them build their own agents without needing you
- "The CAPS technique" — Ask it to review weak instructions. Watch it spot soft boundaries and rewrite them with the three-part formula
🎬 Video Reminder¶
C12 on task board: Record a standalone video demonstrating this agent. Show the full flow from "I have a problem" to "here's your complete agent spec." Great YouTube content for aguidetocloud.com.