Declarative Agents

Microsoft 365 declarative agents

Create, validate, or optimize Microsoft 365 Copilot declarative agents by choosing the right workflow, enforcing v1.5 schema limits, using TypeSpec when helpful, and integrating Microsoft 365 Agents Toolkit and Agents Playground.

When to invoke

• "Create a Microsoft 365 Copilot declarative agent."
• "Validate this declarative agent manifest."
• "Convert this agent JSON to TypeSpec."
• "Choose capabilities for an enterprise declarative agent."
• "Optimize conversation starters and instructions for a Microsoft 365 agent."

Workflow selection

Basic agent creation

1. Define agent purpose, target users, core tasks, and success criteria.
2. Select capabilities from the available capability catalog, respecting the maximum of 5.
3. Generate a compliant JSON manifest with required fields and constraints.
4. Offer a TypeSpec alternative for type-safe definitions that compile to JSON.
5. Configure Agents Playground for local testing.
6. Use Microsoft 365 Agents Toolkit for development, debugging, and environment management.

Advanced enterprise design

Validation rules

Capability catalog

Choose no more than 5 capabilities.

Microsoft 365 Agents Toolkit and TypeSpec

model MyAgent {
  name: string;
  description: string;
  instructions: string;
  capabilities: AgentCapability[];
  conversation_starters?: ConversationStarter[];
}

{
  "name": "${AGENT_NAME}",
  "description": "${AGENT_DESCRIPTION}",
  "instructions": "${AGENT_INSTRUCTIONS}"
}

Criteria

• The chosen workflow matches the user's maturity: basic, advanced, or validation.
• Capability count is 5 or fewer and each capability maps to a user task.
• Conversation starter count is 4 or fewer and each starter is task-oriented.
• name, description, and instructions respect 100, 1000, and 8000 character limits.
• TypeSpec and JSON outputs stay equivalent when both are produced.
• Agents Playground testing is included for local validation.
• Enterprise designs address tenant, compliance, localization, lifecycle, and monitoring concerns.

Gotchas

• Do not start with all capabilities: overbroad capability selection weakens behavior and can violate the max-5 limit.
• Do not exceed character limits: long instructions silently damage validation and usability.
• Do not create generic conversation starters: starters should be specific user tasks, not marketing copy.
• Do not skip local testing: schema-valid manifests can still behave poorly in Agents Playground.

Output template

## Declarative agent result

**Status:** ready | needs changes | blocked
**Workflow:** Basic Agent Creation | Advanced Enterprise Agent Design | Validation & Optimization
**Agent name:** `<name>`

| Area | Decision or finding | Evidence |
| --- | --- | --- |
| Purpose | <agent purpose> | <user requirement> |
| Capabilities | <selected capabilities> | <count <= 5> |
| Conversation starters | <starters> | <count <= 4> |
| Schema | v1.5 compliant | pass | fail |
| Testing | Agents Playground | pass | fail | not run |

### Artifacts
- `<manifest path or TypeSpec path>`

### Validation
- `name` <= 100: pass | fail
- `description` <= 1000: pass | fail
- `instructions` <= 8000: pass | fail

Quality gate

• The response states which workflow was used and why.
• Manifest or TypeSpec content follows Microsoft 365 declarative agent v1.5 constraints.
• Capability selection uses no more than 5 capabilities from the catalog.
• Conversation starters use no more than 4 entries.
• AGENT_NAME, AGENT_DESCRIPTION, and AGENT_INSTRUCTIONS placeholders are preserved when environment substitution is intended.
• Microsoft 365 Agents Toolkit and Agents Playground validation steps are included when building or debugging.
• Validation findings include concrete fixes instead of generic advice.