Decorators for TypeSpec for Microsoft 365 Copilot

This reference covers the built-in decorators available in TypeSpec for Microsoft 365 Copilot, organized by their primary use case.

Declarative agent decorators

These decorators are used when building declarative agents to define agent behavior, conversation flow, and user experience.

@agent

Indicates that a namespace represents an agent.

@agent(name: valueof string, description: valueof string, id?: valueof string)

Target

Namespace

Parameters

Examples

// Basic agent definition with simple name and description
@agent("IT Support Assistant", "An AI agent that helps with technical support and troubleshooting")

// Project management agent with more detailed description
@agent("Project Manager", "A helpful assistant for project management tasks and coordination")

// Agent with explicit ID for tracking and versioning
@agent("Data Analytics Helper", "An agent specialized in data analysis and reporting tasks", "data-analytics-v1")

@behaviorOverrides

Define settings that modify the behavior of the agent orchestration.

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Target

Namespace

Parameters

Models

BehaviorOverrides

Define settings that modify the behavior of the agent orchestration

Examples

// Conservative settings: discourage model knowledge but allow suggestions
@behaviorOverrides(#{
  discourageModelKnowledge: true,
  disableSuggestions: false
})

// Minimal interaction: disable suggestions to reduce prompting
@behaviorOverrides(#{
  disableSuggestions: true
})

// Default behavior: allow both model knowledge and suggestions
@behaviorOverrides(#{
  discourageModelKnowledge: false,
  disableSuggestions: false
})

@conversationStarter

Indicates that a namespace contains a conversation starter.

@conversationStarter(conversationStarter: valueof ConversationStarter)

Target

Namespace

Parameters

Models

ConversationStarter

Configuration object that defines a conversation starter for users.

Examples

// Generic welcome prompt for new users
@conversationStarter(#{
  title: "Get Started",
  text: "How can I help you today?"
})

// Status check prompt for tracking ongoing work
@conversationStarter(#{
  title: "Check Status",
  text: "What's the status of my recent requests?"
})

// Issue reporting prompt for technical support scenarios
@conversationStarter(#{
  text: "I need to report a technical problem"
})

@customExtension

Indicates that a namespace contains a custom extension with a key-value pair for extensibility.

@customExtension(key: valueof string, value: valueof unknown)

Target

Namespace

Parameters

Examples

// Adding a custom feature flag to an agent
@customExtension("featureFlag", "experimentalMode")

// Adding custom metadata with a structured value
@customExtension("metadata", #{
  version: "1.0",
  environment: "production"
})

// Adding a custom configuration setting
@customExtension("customConfig", #{
  maxRetries: 3,
  timeout: 30000
})

@disclaimer

An optional object containing a disclaimer message that, if provided, is displayed to users at the start of a conversation to satisfy legal or compliance requirements.

@disclaimer(disclaimer: valueof Disclaimer)

Target

Namespace

Parameters

Models

Disclaimer

The disclaimer information that is shown to users.

Examples

// General disclaimer for informational agents
@disclaimer(#{
  text: "This agent provides general information only and should not be considered professional advice."
})

// Financial advice disclaimer with professional consultation reminder
@disclaimer(#{
  text: "All financial information provided is for educational purposes. Please consult with a qualified financial advisor before making investment decisions."
})

// Technical support disclaimer for critical systems
@disclaimer(#{
  text: "This technical support agent provides general guidance. For critical systems, please contact your IT department directly."
})

@instructions

Defines the instructions that define the behavior of an agent.

@instructions(instructions: valueof string)

Target

Namespace

Parameters

Examples

// Simple, concise instructions for positive interaction
@instructions("Always respond with a positive energy.")

// Detailed instructions for technical support with specific behaviors
@instructions("""
  You are a customer support agent specializing in technical troubleshooting.
  Always provide step-by-step solutions and ask clarifying questions when needed.
""")

// Comprehensive instructions with disclaimers and behavioral constraints
@instructions("""
  You are a financial advisor assistant. Provide general financial information
  but always remind users to consult with qualified professionals for specific advice.
  Never provide specific investment recommendations.
""")

API plugin decorators

These decorators are used when building API plugins to define API operations, authentication, and response handling.

@actions

Defines the action that can be defined on an info object in an OpenAPI specification.

@actions(data: valueof ActionMetadata)

Target

Namespace

Parameters

Models

ActionMetadata

The action metadata including human-readable names, descriptions, and URLs.

Examples

// Complete action metadata with all contact and legal information
@actions(#{
  nameForHuman: "Customer Support API",
  descriptionForModel: "Provides customer support ticket management",
  descriptionForHuman: "Manage and track customer support requests",
  privacyPolicyUrl: "https://company.com/privacy",
  legalInfoUrl: "https://company.com/legal",
  contactEmail: "support@company.com"
})

// Enhanced action metadata with branding and comprehensive descriptions
@actions(#{
  nameForHuman: "Project Management Suite",
  descriptionForModel: "Comprehensive project management tools",
  privacyPolicyUrl: "https://company.com/privacy",
  legalInfoUrl: "https://company.com/terms",
  contactEmail: "pm-support@company.com",
  logoUrl: "https://company.com/logo.png",
  descriptionForHuman: "A complete project management solution for teams"
})

// Minimal action metadata focusing on analytics functionality
@actions(#{
  nameForHuman: "Analytics Dashboard",
  descriptionForHuman: "Real-time analytics and reporting platform",
  descriptionForModel: "Generate reports and analyze business data"
})

@authReferenceId

Defines the authentication reference ID for the authentication type.

@authReferenceId(value: valueof string)

Target

Model

Parameters

Examples

// Reference to the Developer Portal OAuth client registration ID (https://dev.teams.cloud.microsoft/oauth-configuration)
@authReferenceId("NzFmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IyM5NzQ5Njc3Yi04NDk2LTRlODYtOTdmZS1kNDUzODllZjUxYjM=")

// Reference to the Developer Portal API key registration ID (https://dev.teams.cloud.microsoft/api-key-registration)
@authReferenceId("5f701b3e-bf18-40fb-badd-9ad0b60b31c0")

@capabilities

Support an action function's capabilities object as defined in the API plugin manifest object. You can use this decorator to define simple adaptive cards with small definitions like confirmation. For more complex adaptive cards, you can use the @card decorator.

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Target

Operation

Parameters

Models

FunctionCapabilitiesMetadata

Contains a collection of data used to configure optional capabilities of the orchestrator while invoking the function.

Confirmation

Describes how the orchestrator asks the user to confirm before calling a function.

ResponseSemantics

Contains information to identify semantics of response payload and enable rendering that information in a rich visual experience using Adaptive Cards.

ResponseSemanticsProperties

Allows mapping of JSONPath queries to well-known data elements. Each JSONPath query is relative to a result value.

SecurityInfo

Contains information use to determine the relative risk of invoking the function.

Examples

// Simple confirmation dialog for destructive operations
@capabilities(#{
  confirmation: #{
    type: "AdaptiveCard",
    title: "Delete Ticket",
    body: "Are you sure you want to delete this support ticket? This action cannot be undone."
  }
})

// Comprehensive capabilities with confirmation and response formatting
@capabilities(#{
  confirmation: #{
    type: "modal",
    title: "Create Project",
    body: """
    Creating a new project with the following details:
      * **Title**: {{ function.parameters.name }}
      * **Description**: {{ function.parameters.description }}
      * **Team Lead**: {{ function.parameters.teamLead }}
    """
  },
  responseSemantics: #{
    dataPath: "$.projects",
    properties: #{
      title: "$.name",
      subTitle: "$.description",
      url: "$.projectUrl",
      thumbnailUrl: "$.teamLogo"
    },
    staticTemplate: #{file: "adaptiveCards/dish.json"}
  }
})

@card

Defines the adaptive card reference for a function.

@card(cardPath: valueof CardMetadata)

Target

Operation

Parameters

Models

CardMetadata

Simplified responseSemantics focused on the adaptive card.

Examples

// Basic card configuration with data binding and static title
@card(#{
  dataPath: "$.tickets",
  file: "cards/ticketCard.json",
  title: "Support Ticket Details"
})

// Dynamic card with URL binding and custom card file location
@card(#{
  dataPath: "$.projects",
  title: "$.name",
  url: "$.projectUrl",
  file: "cards/project.json"
})

@reasoning

Defines the reasoning instructions of a function within an action.

@reasoning(value: valueof string)

Target

Operation

Parameters

Examples

// Prioritization logic for ticket search operations
@reasoning("""
  When searching for tickets, prioritize by severity level and creation date.
  Always include ticket ID and status in the response.
""")

// Role-based access control reasoning for project operations
@reasoning("""
  For project queries, consider the user's role and project permissions.
  Filter results based on team membership and access levels.
""")

// Data validation reasoning for analytics requests
@reasoning("""
  When processing analytics requests, validate date ranges and ensure
  the requested metrics are available for the specified time period.
""")

@responding

Defines the responding instructions of a function within an action.

@responding(value: valueof string)

Target

Operation

Parameters

Examples

// Structured table format for support ticket responses
@responding("""
  Present support tickets in a clear table format with columns: ID, Title, Priority, Status, Created Date.
  Include summary statistics at the end showing total tickets by status.
""")

// Bullet point format for project information display
@responding("""
  Display project information using bullet points for easy reading.
  Always include project timeline and current phase information.
""")