Typespec Create API Plugin

TypeSpec API plugin creation

Create a complete Microsoft 365 Copilot API plugin from API requirements by producing main.tsp, actions.tsp, optional cards/card.json, and implementation notes for operations, authentication, confirmations, and response shaping.

When to invoke

• "Create a TypeSpec API plugin for this REST API."
• "Generate main.tsp and actions.tsp for a Microsoft 365 Copilot agent."
• "Add API key or OAuth2 auth to a TypeSpec action plugin."
• "Return API results with an Adaptive Card."
• "Model these CRUD operations as Copilot plugin actions."

Inputs

Use the user's API description as the source of truth. Capture API base URL, purpose, operations, request and response schema, authentication method, destructive operations that need confirmation, and whether responses need Adaptive Cards.

TypeSpec file map

Use these skeletons as the minimum shape:

// main.tsp
import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent({ name: "[Agent Name]", description: "[Description]" })
@instructions("""
  [Instructions for using the API operations]
""")
namespace [AgentName] {
  op operation1 is [APINamespace].operationName;
}

// actions.tsp
import "@typespec/http";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Actions;

@service
@actions(#{
  nameForHuman: "[API Display Name]",
  descriptionForModel: "[Model description]",
  descriptionForHuman: "[User description]"
})
@server("[API_BASE_URL]", "[API Name]")
@useAuth([AuthType])
namespace [APINamespace] {
  @route("[/path]")
  @get
  @action
  op operationName(@path param1: string, @query param2?: string): ResponseModel;

  model ResponseModel {
    // Response structure
  }
}

Authentication patterns

Operation design rules

Capability decorators

@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Confirm Action",
    body: """
    Are you sure you want to perform this action?
      * **Parameter**: {{ function.parameters.paramName }}
    """
  }
})

@card(#{
  dataPath: "$.items",
  title: "$.title",
  url: "$.link",
  file: "cards/card.json"
})

@reasoning("""
  Consider user's context when calling this operation.
  Prioritize recent items over older ones.
""")
@responding("""
  Present results in a clear table format with columns: ID, Title, Status.
  Include a summary count at the end.
""")

Procedure

1. Ask or infer the API base URL, API purpose, required CRUD operations, authentication method, confirmation needs, and Adaptive Card needs.
2. Generate main.tsp with the agent definition and operation references.
3. Generate actions.tsp with service metadata, server, auth, routes, parameters, and request/response models.
4. Add cards/card.json only when the response design uses @card.
5. Review the generated TypeSpec for concrete names, no unresolved placeholders except user-approved placeholders, and correct auth decorators.

Gotchas

• Do not leave [API_BASE_URL] unresolved in final code unless the user explicitly asks for a template.
• Do not add @useAuth for public APIs; placeholder auth breaks plugin setup.
• Do not skip confirmations on destructive operations; deletion and critical updates need @capabilities confirmation.
• Do not model response bodies as untyped object when fields are known; TypeSpec models improve action planning and OpenAPI output.

Output template

## TypeSpec API plugin

**Status:** complete | needs input | blocked
**Agent:** <agent name>
**API base URL:** <base URL or unresolved placeholder>

### Files
- `main.tsp`: <summary>
- `actions.tsp`: <summary>
- `cards/card.json`: <created | not needed>

### Operations
| Operation | Method | Route | Auth | Confirmation | Response |
| --- | --- | --- | --- | --- | --- |
| `<operationName>` | `<GET|POST|PATCH|DELETE>` | `<route>` | `<auth>` | `<yes|no>` | `<model/card>` |

### Validation
- Placeholder review: <pass|fail and evidence>
- Auth mapping: <pass|fail and evidence>
- Adaptive Card mapping: <pass|not applicable and evidence>

Quality gate

• main.tsp imports required TypeSpec and Microsoft 365 Copilot libraries and references operations from actions.tsp.
• actions.tsp defines @service, @actions, @server, operations, models, and only the needed @useAuth pattern.
• Every operation has an HTTP verb, @route, parameter decorators, and a typed response model.
• Destructive operations include an Adaptive Card confirmation.
• @card, @reasoning, and @responding are used only when they add concrete behavior.
• Any remaining placeholder such as [AgentName] or [API_BASE_URL] is intentional and reported.