Typespec Create Api Plugin

1---2name: typespec-create-api-plugin3description: 'Generate a TypeSpec API plugin with REST operations, authentication, and Adaptive Cards for Microsoft 365 Copilot'4---5 6# Create TypeSpec API Plugin7 8Create a complete TypeSpec API plugin for Microsoft 365 Copilot that integrates with external REST APIs.9 10## Requirements11 12Generate TypeSpec files with:13 14### main.tsp - Agent Definition15```typescript16import "@typespec/http";17import "@typespec/openapi3";18import "@microsoft/typespec-m365-copilot";19import "./actions.tsp";20 21using TypeSpec.Http;22using TypeSpec.M365.Copilot.Agents;23using TypeSpec.M365.Copilot.Actions;24 25@agent({26  name: "[Agent Name]",27  description: "[Description]"28})29@instructions("""30  [Instructions for using the API operations]31""")32namespace [AgentName] {33  // Reference operations from actions.tsp34  op operation1 is [APINamespace].operationName;35}36```37 38### actions.tsp - API Operations39```typescript40import "@typespec/http";41import "@microsoft/typespec-m365-copilot";42 43using TypeSpec.Http;44using TypeSpec.M365.Copilot.Actions;45 46@service47@actions(#{48    nameForHuman: "[API Display Name]",49    descriptionForModel: "[Model description]",50    descriptionForHuman: "[User description]"51})52@server("[API_BASE_URL]", "[API Name]")53@useAuth([AuthType]) // Optional54namespace [APINamespace] {55  56  @route("[/path]")57  @get58  @action59  op operationName(60    @path param1: string,61    @query param2?: string62  ): ResponseModel;63 64  model ResponseModel {65    // Response structure66  }67}68```69 70## Authentication Options71 72Choose based on API requirements:73 741. **No Authentication** (Public APIs)75   ```typescript76   // No @useAuth decorator needed77   ```78 792. **API Key**80   ```typescript81   @useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">)82   ```83 843. **OAuth2**85   ```typescript86   @useAuth(OAuth2Auth<[{87     type: OAuth2FlowType.authorizationCode;88     authorizationUrl: "https://oauth.example.com/authorize";89     tokenUrl: "https://oauth.example.com/token";90     refreshUrl: "https://oauth.example.com/token";91     scopes: ["read", "write"];92   }]>)93   ```94 954. **Registered Auth Reference**96   ```typescript97   @useAuth(Auth)98   99   @authReferenceId("registration-id-here")100   model Auth is ApiKeyAuth<ApiKeyLocation.header, "X-API-Key">101   ```102 103## Function Capabilities104 105### Confirmation Dialog106```typescript107@capabilities(#{108  confirmation: #{109    type: "AdaptiveCard",110    title: "Confirm Action",111    body: """112    Are you sure you want to perform this action?113      * **Parameter**: {{ function.parameters.paramName }}114    """115  }116})117```118 119### Adaptive Card Response120```typescript121@card(#{122  dataPath: "$.items",123  title: "$.title",124  url: "$.link",125  file: "cards/card.json"126})127```128 129### Reasoning & Response Instructions130```typescript131@reasoning("""132  Consider user's context when calling this operation.133  Prioritize recent items over older ones.134""")135@responding("""136  Present results in a clear table format with columns: ID, Title, Status.137  Include a summary count at the end.138""")139```140 141## Best Practices142 1431. **Operation Names**: Use clear, action-oriented names (listProjects, createTicket)1442. **Models**: Define TypeScript-like models for requests and responses1453. **HTTP Methods**: Use appropriate verbs (@get, @post, @patch, @delete)1464. **Paths**: Use RESTful path conventions with @route1475. **Parameters**: Use @path, @query, @header, @body appropriately1486. **Descriptions**: Provide clear descriptions for model understanding1497. **Confirmations**: Add for destructive operations (delete, update critical data)1508. **Cards**: Use for rich visual responses with multiple data items151 152## Workflow153 154Ask the user:1551. What is the API base URL and purpose?1562. What operations are needed (CRUD operations)?1573. What authentication method does the API use?1584. Should confirmations be required for any operations?1595. Do responses need Adaptive Cards?160 161Then generate:162- Complete `main.tsp` with agent definition163- Complete `actions.tsp` with API operations and models164- Optional `cards/card.json` if Adaptive Cards are needed