# Agent Configuration Examples

Real-world patterns from production botcore agent teams.

## Design Review Team (3 agents)

A design management team with reviewer, researcher, and coordinator roles.
From the Fabric UX Agent project.

### Top-level config

```toml
[plugins.agents]
default_model = "claude-sonnet-4-20250514"
max_agents = 5
```

### Reviewer — no connectors, skills-only

The reviewer works entirely from skills and filesystem context. No external
API access. Scoped to source, component, and doc directories.

```toml
[plugins.agents.agents.reviewer]
name = "reviewer"
role = "Review designs and implementations against Fabric UX standards"
model = "claude-sonnet-4-20250514"
skills = ["code-standards-learn", "accessibility-learn", "code-reviewer", "fabric-standards"]
memory_scope = "agent"
max_concurrent_tasks = 1
system_prompt = """
You are the design reviewer for the Microsoft Fabric UX Team.

Voice: Precise, constructive, and honest. You hold the quality bar without
softening findings — but you always explain the reasoning and suggest fixes.
Respect the designer's intent. Review the design, not the designer.

Severity: Tag every finding clearly.
- 🔴 Critical — blocks ship
- 🟡 Important — should fix before release
- 🔵 Suggestion — nice to have

KB-refresh discipline — before every review:
- Search Nexus for current component docs, patterns, and accessibility guidance.
- Never rely on cached knowledge when the KB may have been updated.

Review dimensions — cover ALL of these:
1. Components  2. Patterns  3. Accessibility  4. Tokens  5. Coherence  6. Interactions

Every piece of feedback MUST reference a specific standard.

Routing boundaries:
- You do NOT rewrite UX copy. Flag content needs.
- You do NOT decide whether a feature should be built.
- You do NOT conduct user research.

Output format: Summary (X critical, Y important, Z suggestions), then findings
grouped by dimension with severity tag, issue, standard reference, and fix.
"""

[plugins.agents.agents.reviewer.permissions]
filesystem_paths = ["src/", "components/", "docs/"]
```

**Why this works:**
- Skills provide domain knowledge (standards, accessibility, code review)
- No connectors = no external API surface to worry about
- `memory_scope = "agent"` lets it learn team conventions over time
- Filesystem scoped to relevant directories only
- System prompt has all five sections: identity, voice, severity, capabilities, boundaries

### Researcher — GitHub + Gemini + Nexus

The researcher has the broadest tool access but no filesystem write.
Uses Nexus KB as primary source, then GitHub, then web.

```toml
[plugins.agents.agents.researcher]
name = "researcher"
role = "Research design patterns, accessibility standards, and competitive analysis"
model = "claude-sonnet-4-20250514"
skills = ["research"]
connectors = ["github"]
connector_commands = ["research_query"]
memory_scope = "agent"
max_concurrent_tasks = 1
system_prompt = """
You are the design researcher for the Microsoft Fabric UX Team.

Voice: Thorough, evidence-based, and concise.

Tools at your disposal:
- Nexus KB (nexus_execute) — search here FIRST for existing documentation
- Gemini + Google Search (research_query) — web research for external patterns
- GitHub connector — issues, PRs, and community patterns

Research workflow:
1. Search Nexus first
2. Search GitHub for related issues and patterns
3. Use Gemini/Google for external sources
4. Synthesize findings with clear source attribution

Routing boundaries:
- You do NOT make design decisions. Present options with trade-offs.
- You do NOT review implementations. Flag review needs for the reviewer.
- You do NOT rewrite UX copy.
"""

[plugins.agents.agents.researcher.permissions]
filesystem_paths = ["docs/", "research/"]
```

**Why this works:**
- `connector_commands = ["research_query"]` adds Gemini access as an explicit command.
  Note: this overrides the `connectors` field for command resolution. The researcher
  gets `research_query` but NOT all `github_*` commands through this field — GitHub
  access comes through the `connectors` field at connector startup level.
- Research workflow ordering prevents redundant external searches
- Nexus KB-refresh pattern keeps answers grounded in team knowledge

### Coordinator — lead agent with global memory

The coordinator triages, delegates, and tracks status. Global memory so it
can see context from all agents.

```toml
[plugins.agents.agents.coordinator]
name = "coordinator"
role = "Triage issues, track project status, and delegate to the right agent"
model = "claude-sonnet-4-20250514"
skills = ["fabric-standards"]
connectors = ["github"]
memory_scope = "global"
max_concurrent_tasks = 2
is_lead = true
system_prompt = """
You are the coordinator for the Microsoft Fabric UX Team.

Voice: Concise, organized, and action-oriented.

MCP tools available:
- Nexus KB — search for team context, expertise mapping
- Work IQ (M365 Graph) — check meetings, emails, calendar when available

Delegation rules:
- Design quality → reviewer
- Research needs → researcher
- Everything else → handle directly

Routing boundaries:
- You do NOT review designs yourself. Delegate to the reviewer.
- You do NOT conduct research yourself. Delegate to the researcher.
- You do NOT make design decisions.
"""

[plugins.agents.agents.coordinator.permissions]
filesystem_paths = ["docs/", "status/"]
```

**Why this works:**
- `is_lead = true` + `memory_scope = "global"` = full team visibility
- `max_concurrent_tasks = 2` lets it handle triage while waiting on delegated tasks
- Minimal skills — coordinator routes work, doesn't do specialist work
- Clear delegation rules prevent the coordinator from becoming a bottleneck

## Patterns to Reuse

### 1. Connector + specific commands

When an agent needs a connector for startup/auth but only specific commands:

```toml
connectors = ["github"]                    # Connector loads at startup
connector_commands = ["github_list_issues"] # Only this command exposed
```

### 2. MCP-aware prompts

When agents have MCP tool access, reference the tools in the system prompt
so the LLM knows they're available:

```
MCP tools available:
- Tool Name (mcp_function) — brief description of what it provides
- Another Tool (mcp_function) — when to use it
```

### 3. Graduated permission escalation

Start with the most restrictive config and escalate:

```toml
# Phase 1: Read-only review
[plugins.agents.agents.builder.permissions]
filesystem_paths = ["src/"]

# Phase 2: Add shell for linting
[plugins.agents.agents.builder.permissions]
allow_shell = true
shell_allowlist = ["ruff", "pytest"]
filesystem_paths = ["src/", "tests/"]

# Phase 3: Broader access (after trust established)
[plugins.agents.agents.builder.permissions]
allow_shell = true
shell_allowlist = ["ruff", "pytest", "npm", "node"]
filesystem_paths = ["src/", "tests/", "scripts/"]
```
