Declarative Agents Architect

Your specialized agent for designing and building Microsoft 365 Copilot declarative agents using the latest JSON schema specifications, TypeSpec development, and Microsoft 365 platform integration.

When to Use This Agent

Choose Declarative Agents Architect when:

• Building Microsoft 365 Copilot declarative agents with the v1.5 JSON schema
• Designing agent capabilities, conversation starters, and action integrations
• Implementing API plugins, Graph connectors, or SharePoint knowledge sources
• Configuring agent manifests for Teams, Outlook, and Microsoft 365 deployment
• Debugging declarative agent behavior and API plugin connectivity

Consider alternatives when:

• You need general Microsoft development — use a Microsoft expert agent
• You need Teams bot development (Bot Framework) — use a Teams bot agent
• You need Power Platform agents — use a Power Platform specialist

Quick Start

Copy
# .claude/agents/declarative-agents.yml
name: Declarative Agents Architect
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Microsoft 365 Copilot declarative agent specialist for agent design, manifest configuration, and API plugin integration

Example invocation:

claude "Create a declarative agent manifest for a customer support agent that uses our REST API for ticket lookup, integrates SharePoint knowledge base articles, and includes conversation starters for common scenarios"

Core Concepts

Declarative Agent Architecture

┌─────────────────────────────────────┐
│      Microsoft 365 Copilot          │
│   ┌─────────────────────────────┐   │
│   │    Declarative Agent        │   │
│   │  ┌───────────────────────┐  │   │
│   │  │  Agent Manifest       │  │   │
│   │  │  - Instructions       │  │   │
│   │  │  - Capabilities       │  │   │
│   │  │  - Conversation starts│  │   │
│   │  └───────────────────────┘  │   │
│   │  ┌───────────────────────┐  │   │
│   │  │  Actions              │  │   │
│   │  │  - API Plugins        │  │   │
│   │  │  - Graph Connectors   │  │   │
│   │  └───────────────────────┘  │   │
│   │  ┌───────────────────────┐  │   │
│   │  │  Knowledge            │  │   │
│   │  │  - SharePoint         │  │   │
│   │  │  - Graph Connectors   │  │   │
│   │  └───────────────────────┘  │   │
│   └─────────────────────────────┘   │
└─────────────────────────────────────┘

Agent Manifest Structure

Component	Purpose	Configuration
Instructions	Agent behavior and persona	Natural language system prompt
Capabilities	What the agent can do	API plugins, connectors, code
Conversation Starters	Suggested prompts for users	Array of starter strings
Knowledge Sources	Data the agent can reference	SharePoint sites, Graph connectors
Actions	External API integrations	OpenAPI specs with auth config

Configuration

Parameter	Description	Default
schema_version	Manifest schema version	v1.5
deployment_target	Target platform (teams, outlook, m365)	m365
auth_method	API authentication (oauth2, api-key, none)	oauth2
knowledge_sources	Knowledge integration type (sharepoint, graph)	sharepoint
testing_mode	Development testing approach (sideload, dev-tenant)	sideload

Best Practices

1. Write clear, specific agent instructions. The instructions field is the agent's system prompt — vague instructions produce vague behavior. Define the agent's persona, capabilities, limitations, and preferred response format explicitly.

2. Design conversation starters that demonstrate capabilities. Each starter should showcase a different agent capability. "Look up ticket #12345," "Search our knowledge base for refund policies," and "Create a summary of this week's support trends" show users three different things the agent can do.

3. Use API plugins with complete OpenAPI specs. Declarative agents rely on OpenAPI descriptions to understand how to call your APIs. Include detailed parameter descriptions, example values, and response schemas so the agent can construct correct API calls.

4. Test agents with sideloading before publishing. Use Teams Toolkit or the Developer Portal to sideload agents during development. This allows rapid iteration without going through the full publishing and approval process.

5. Scope knowledge sources to relevant content only. Adding entire SharePoint sites as knowledge creates noise. Scope to specific document libraries or folders that contain the information relevant to the agent's domain. Less data with higher relevance produces better answers.

Common Issues

Agent doesn't use the API plugin for relevant questions. The OpenAPI spec lacks descriptive operation summaries that help the agent understand when to call which endpoint. Add detailed summary and description fields to each operation, and include example queries in the agent instructions.

Knowledge source returns irrelevant or outdated results. SharePoint content that's disorganized, duplicated, or outdated degrades agent quality. Curate the knowledge source — organize documents, remove duplicates, and mark outdated content for archival before connecting it to the agent.

Agent manifest fails validation during sideload. Schema validation errors are usually caused by missing required fields, incorrect JSON structure, or version mismatches. Validate the manifest against the v1.5 schema using the Teams Toolkit validator, and check that all referenced files (OpenAPI specs, icons) exist at the specified paths.