{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"typespec-m365-copilot","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Guidelines and best practices for building TypeSpec-based declarative agents and API plugins for Microsoft 365 Copilot'\napplyTo: '**/*.tsp'\n---\n\n# TypeSpec for Microsoft 365 Copilot Development Guidelines\n\n## Core Principles\n\nWhen working with TypeSpec for Microsoft 365 Copilot:\n\n1. **Type Safety First**: Leverage TypeSpec's strong typing for all models and operations\n2. **Declarative Approach**: Use decorators to describe intent, not implementation\n3. **Scoped Capabilities**: Always scope capabilities to specific resources when possible\n4. **Clear Instructions**: Write explicit, detailed agent instructions\n5. **User-Centric**: Design for the end-user experience in Microsoft 365 Copilot\n\n## File Organization\n\n### Standard Structure\n```\nproject/\n├── appPackage/\n│   ├── cards/              # Adaptive Card templates\n│   │   └── *.json\n│   ├── .generated/         # Generated manifests (auto-generated)\n│   └── manifest.json       # Teams app manifest\n├── src/\n│   ├── main.tsp           # Agent definition\n│   └── actions.tsp        # API operations (for plugins)\n├── m365agents.yml         # Agents Toolkit configuration\n└── package.json\n```\n\n### Import Statements\nAlways include required imports at the top of TypeSpec files:\n\n```typescript\nimport \"@typespec/http\";\nimport \"@typespec/openapi3\";\nimport \"@microsoft/typespec-m365-copilot\";\n\nusing TypeSpec.Http;\nusing TypeSpec.M365.Copilot.Agents;  // For agents\nusing TypeSpec.M365.Copilot.Actions; // For API plugins\n```\n\n## Agent Development Best Practices\n\n### Agent Declaration\n```typescript\n@agent({\n  name: \"Role-Based Name\",  // e.g., \"Customer Support Assistant\"\n  description: \"Clear, concise description under 1,000 characters\"\n})\n```\n\n- Use role-based names that describe what the agent does\n- Make descriptions informative but concise\n- Avoid generic names like \"Helper\" or \"Bot\"\n\n### Instructions\n```typescript\n@instructions(\"\"\"\n  You are a [specific role] specialized in [domain].\n  \n  Your responsibilities include:\n  - [Key responsibility 1]\n  - [Key responsibility 2]\n  \n  When helping users:\n  - [Behavioral guideline 1]\n  - [Behavioral guideline 2]\n  \n  You should NOT:\n  - [Constraint 1]\n  - [Constraint 2]\n\"\"\")\n```\n\n- Write in second person (\"You are...\")\n- Be specific about the agent's role and expertise\n- Define both what to do AND what not to do\n- Keep under 8,000 characters\n- Use clear, structured formatting\n\n### Conversation Starters\n```typescript\n@conversationStarter(#{\n  title: \"Action-Oriented Title\",  // e.g., \"Check Status\"\n  text: \"Specific example query\"   // e.g., \"What's the status of my ticket?\"\n})\n```\n\n- Provide 2-4 diverse starters\n- Make each showcase a different capability\n- Use action-oriented titles\n- Write realistic example queries\n\n### Capabilities - Knowledge Sources\n\n**Web Search** - Scope to specific sites when possible:\n```typescript\nop webSearch is AgentCapabilities.WebSearch\u003cSites = [\n  { url: \"https://learn.microsoft.com\" },\n  { url: \"https://docs.microsoft.com\" }\n]\u003e;\n```\n\n**OneDrive and SharePoint** - Use URLs or IDs:\n```typescript\nop oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint\u003c\n  ItemsByUrl = [\n    { url: \"https://contoso.sharepoint.com/sites/Engineering\" }\n  ]\n\u003e;\n```\n\n**Teams Messages** - Specify channels/chats:\n```typescript\nop teamsMessages is AgentCapabilities.TeamsMessages\u003cUrls = [\n  { url: \"https://teams.microsoft.com/l/channel/...\" }\n]\u003e;\n```\n\n**Email** - Scope to specific folders:\n```typescript\nop email is AgentCapabilities.Email\u003c\n  Folders = [\n    { folderId: \"Inbox\" },\n    { folderId: \"SentItems\" }\n  ],\n  SharedMailbox = \"support@contoso.com\"  // Optional\n\u003e;\n```\n\n**People** - No scoping needed:\n```typescript\nop people is AgentCapabilities.People;\n```\n\n**Copilot Connectors** - Specify connection IDs:\n```typescript\nop copilotConnectors is AgentCapabilities.GraphConnectors\u003c\n  Connections = [\n    { connectionId: \"your-connector-id\" }\n  ]\n\u003e;\n```\n\n**Dataverse** - Scope to specific tables:\n```typescript\nop dataverse is AgentCapabilities.Dataverse\u003c\n  KnowledgeSources = [\n    {\n      hostName: \"contoso.crm.dynamics.com\";\n      tables: [\n        { tableName: \"account\" },\n        { tableName: \"contact\" }\n      ];\n    }\n  ]\n\u003e;\n```\n\n### Capabilities - Productivity Tools\n\n```typescript\n// Python code execution\nop codeInterpreter is AgentCapabilities.CodeInterpreter;\n\n// Image generation\nop graphicArt is AgentCapabilities.GraphicArt;\n\n// Meeting content access\nop meetings is AgentCapabilities.Meetings;\n\n// Specialized AI models\nop scenarioModels is AgentCapabilities.ScenarioModels\u003c\n  ModelsById = [\n    { id: \"model-id\" }\n  ]\n\u003e;\n```\n\n## API Plugin Development Best Practices\n\n### Service Definition\n```typescript\n@service\n@actions(#{\n  nameForHuman: \"User-Friendly API Name\",\n  descriptionForHuman: \"What users will understand\",\n  descriptionForModel: \"What the model needs to know\",\n  contactEmail: \"support@company.com\",\n  privacyPolicyUrl: \"https://company.com/privacy\",\n  legalInfoUrl: \"https://company.com/terms\"\n})\n@server(\"https://api.example.com\", \"API Name\")\n@useAuth([AuthType])  // If authentication needed\nnamespace APINamespace {\n  // Operations here\n}\n```\n\n### Operation Definition\n```typescript\n@route(\"/resource/{id}\")\n@get\n@action\n@card(#{\n  dataPath: \"$.items\",\n  title: \"$.title\",\n  file: \"cards/card.json\"\n})\n@capabilities(#{\n  confirmation: #{\n    type: \"AdaptiveCard\",\n    title: \"Confirm Action\",\n    body: \"Confirm with {{ function.parameters.param }}\"\n  }\n})\n@reasoning(\"Consider X when Y\")\n@responding(\"Present results as Z\")\nop getResource(\n  @path id: string,\n  @query filter?: string\n): ResourceResponse;\n```\n\n### Models\n```typescript\nmodel Resource {\n  id: string;\n  name: string;\n  description?: string;  // Optional fields\n  status: \"active\" | \"inactive\";  // Union types for enums\n  @format(\"date-time\")\n  createdAt: utcDateTime;\n  @format(\"uri\")\n  url?: string;\n}\n\nmodel ResourceList {\n  items: Resource[];\n  totalCount: int32;\n  nextPage?: string;\n}\n```\n\n### Authentication\n\n**API Key**\n```typescript\n@useAuth(ApiKeyAuth\u003cApiKeyLocation.header, \"X-API-Key\"\u003e)\n\n// Or with reference ID\n@useAuth(Auth)\n@authReferenceId(\"${{ENV_VAR_REFERENCE_ID}}\")\nmodel Auth is ApiKeyAuth\u003cApiKeyLocation.header, \"X-API-Key\"\u003e;\n```\n\n**OAuth2**\n```typescript\n@useAuth(OAuth2Auth\u003c[{\n  type: OAuth2FlowType.authorizationCode;\n  authorizationUrl: \"https://auth.example.com/authorize\";\n  tokenUrl: \"https://auth.example.com/token\";\n  refreshUrl: \"https://auth.example.com/refresh\";\n  scopes: [\"read\", \"write\"];\n}]\u003e)\n\n// Or with reference ID\n@useAuth(Auth)\n@authReferenceId(\"${{OAUTH_REFERENCE_ID}}\")\nmodel Auth is OAuth2Auth\u003c[...]\u003e;\n```\n\n## Naming Conventions\n\n### Files\n- `main.tsp` - Agent definition\n- `actions.tsp` - API operations\n- `[feature].tsp` - Additional feature files\n- `cards/*.json` - Adaptive Card templates\n\n### TypeSpec Elements\n- **Namespaces**: PascalCase (e.g., `CustomerSupportAgent`)\n- **Operations**: camelCase (e.g., `listProjects`, `createTicket`)\n- **Models**: PascalCase (e.g., `Project`, `TicketResponse`)\n- **Model Properties**: camelCase (e.g., `projectId`, `createdDate`)\n\n## Common Patterns\n\n### Multi-Capability Agent\n```typescript\n@agent(\"Knowledge Worker\", \"Description\")\n@instructions(\"...\")\nnamespace KnowledgeWorker {\n  op webSearch is AgentCapabilities.WebSearch;\n  op files is AgentCapabilities.OneDriveAndSharePoint;\n  op people is AgentCapabilities.People;\n}\n```\n\n### CRUD API Plugin\n```typescript\nnamespace ProjectAPI {\n  @route(\"/projects\") @get @action\n  op list(): Project[];\n  \n  @route(\"/projects/{id}\") @get @action\n  op get(@path id: string): Project;\n  \n  @route(\"/projects\") @post @action\n  @capabilities(#{confirmation: ...})\n  op create(@body project: CreateProject): Project;\n  \n  @route(\"/projects/{id}\") @patch @action\n  @capabilities(#{confirmation: ...})\n  op update(@path id: string, @body project: UpdateProject): Project;\n  \n  @route(\"/projects/{id}\") @delete @action\n  @capabilities(#{confirmation: ...})\n  op delete(@path id: string): void;\n}\n```\n\n### Adaptive Card Data Binding\n```json\n{\n  \"type\": \"AdaptiveCard\",\n  \"$schema\": \"http://adaptivecards.io/schemas/adaptive-card.json\",\n  \"version\": \"1.5\",\n  \"body\": [\n    {\n      \"type\": \"Container\",\n      \"$data\": \"${$root}\",\n      \"items\": [\n        {\n          \"type\": \"TextBlock\",\n          \"text\": \"Title: ${if(title, title, 'N/A')}\",\n          \"wrap\": true\n        }\n      ]\n    }\n  ]\n}\n```\n\n## Validation and Testing\n\n### Before Provisioning\n1. Run TypeSpec validation: `npm run build` or use Agents Toolkit\n2. Check all file paths in `@card` decorators exist\n3. Verify authentication references match configuration\n4. Ensure capability scoping is appropriate\n5. Review instructions for clarity and length\n\n### Testing Strategy\n1. **Provision**: Deploy to development environment\n2. **Test**: Use Microsoft 365 Copilot at https://m365.cloud.microsoft/chat\n3. **Debug**: Enable Copilot developer mode for orchestrator insights\n4. **Iterate**: Refine based on actual behavior\n5. **Validate**: Test all conversation starters and capabilities\n\n## Performance Optimization\n\n1. **Scope Capabilities**: Don't grant access to all data if only subset needed\n2. **Limit Operations**: Only expose API operations the agent actually uses\n3. **Efficient Models**: Keep response models focused on necessary data\n4. **Card Optimization**: Use conditional rendering (`$when`) in Adaptive Cards\n5. **Caching**: Design APIs with appropriate caching headers\n\n## Security Best Practices\n\n1. **Authentication**: Always use authentication for non-public APIs\n2. **Scoping**: Limit capability access to minimum required resources\n3. **Validation**: Validate all inputs in API operations\n4. **Secrets**: Use environment variables for sensitive data\n5. **References**: Use `@authReferenceId` for production credentials\n6. **Permissions**: Request minimum necessary OAuth scopes\n\n## Error Handling\n\n```typescript\nmodel ErrorResponse {\n  error: {\n    code: string;\n    message: string;\n    details?: ErrorDetail[];\n  };\n}\n\nmodel ErrorDetail {\n  field?: string;\n  message: string;\n}\n```\n\n## Documentation\n\nInclude comments in TypeSpec for complex operations:\n\n```typescript\n/**\n * Retrieves project details with associated tasks and team members.\n * \n * @param id - Unique project identifier\n * @param includeArchived - Whether to include archived tasks\n * @returns Complete project information\n */\n@route(\"/projects/{id}\")\n@get\n@action\nop getProjectDetails(\n  @path id: string,\n  @query includeArchived?: boolean\n): ProjectDetails;\n```\n\n## Common Pitfalls to Avoid\n\n1. ❌ Generic agent names (\"Helper Bot\")\n2. ❌ Vague instructions (\"Help users with things\")\n3. ❌ No capability scoping (accessing all data)\n4. ❌ Missing confirmations on destructive operations\n5. ❌ Overly complex Adaptive Cards\n6. ❌ Hard-coded credentials in TypeSpec files\n7. ❌ Missing error response models\n8. ❌ Inconsistent naming conventions\n9. ❌ Too many capabilities (use only what's needed)\n10. ❌ Instructions over 8,000 characters\n\n## Resources\n\n- [TypeSpec Official Docs](https://typespec.io/)\n- [Microsoft 365 Copilot Extensibility](https://learn.microsoft.com/microsoft-365-copilot/extensibility/)\n- [Agents Toolkit](https://aka.ms/M365AgentsToolkit)\n- [Adaptive Cards Designer](https://adaptivecards.io/designer/)\n","description":"Guidelines and best practices for building TypeSpec-based declarative agents and API plugins for Microsoft 365 Copilot","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/typespec-m365-copilot.instructions.md"},"manifest":{}},"content_hash":[79,241,236,231,64,44,140,83,189,126,14,142,175,22,159,188,218,86,186,29,214,229,183,246,123,191,136,221,188,91,16,185],"trust_level":"unsigned","yanked":false}