Décorateurs pour TypeSpec pour Microsoft 365 Copilot

Cette référence couvre les éléments décoratifs intégrés disponibles dans TypeSpec pour Microsoft 365 Copilot, organisés selon leur cas d’usage principal.

Décorateurs d’agents déclaratifs

Ces éléments décoratifs sont utilisés lors de la création d’agents déclaratifs pour définir le comportement de l’agent, le flux de conversation et l’expérience utilisateur.

@agent

Indique qu’un espace de noms représente un agent.

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

Target

Namespace

Paramètres

Exemples

// 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

Définissez les paramètres qui modifient le comportement de l’orchestration de l’agent.

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Target

Namespace

Paramètres

Modèles

BehaviorOverrides

Définir des paramètres qui modifient le comportement de l’orchestration de l’agent

Exemples

// 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

Indique qu’un espace de noms contient un démarreur de conversation.

@conversationStarter(conversationStarter: valueof ConversationStarter)

Target

Namespace

Paramètres

Modèles

ConversationStarter

Objet de configuration qui définit un démarrage de conversation pour les utilisateurs.

Exemples

// 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

Indique qu’un espace de noms contient une extension personnalisée avec une paire clé-valeur pour l’extensibilité.

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

Target

Namespace

Paramètres

Exemples

// 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

Objet facultatif contenant un message d’exclusion de responsabilité qui, s’il est fourni, est affiché aux utilisateurs au début d’une conversation pour répondre aux exigences légales ou de conformité.

@disclaimer(disclaimer: valueof Disclaimer)

Target

Namespace

Paramètres

Modèles

Clause d’exclusion de responsabilité

Informations d’exclusion de responsabilité affichées aux utilisateurs.

Exemples

// 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

Définit les instructions qui définissent le comportement d’un agent.

@instructions(instructions: valueof string)

Target

Namespace

Paramètres

Exemples

// 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.
""")

Décorateurs de plug-in d’API

Ces éléments décoratifs sont utilisés lors de la création de plug-ins d’API pour définir les opérations d’API, l’authentification et la gestion des réponses.

@actions

Définit l’action qui peut être définie sur un objet d’informations dans une spécification OpenAPI.

@actions(data: valueof ActionMetadata)

Target

Namespace

Paramètres

Modèles

ActionMetadata

Métadonnées d’action, y compris les noms, les descriptions et les URL lisibles par l’utilisateur.

Exemples

// 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

Définit l’ID de référence d’authentification pour le type d’authentification.

@authReferenceId(value: valueof string)

Target

Model

Paramètres

Exemples

// 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

Prend en charge l’objet de fonctionnalités d’une fonction d’action tel que défini dans l’objet manifeste du plug-in d’API . Vous pouvez utiliser cet élément décoratif pour définir des cartes adaptatives simples avec de petites définitions comme confirmation. Pour les cartes adaptatives plus complexes, vous pouvez utiliser l’élément @card décoratif.

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Target

Operation

Paramètres

Modèles

FunctionCapabilitiesMetadata

Contient une collection de données utilisée pour configurer les fonctionnalités facultatives de l’orchestrateur lors de l’appel de la fonction .

Confirmation

Décrit comment l’orchestrateur demande à l’utilisateur de confirmer avant d’appeler une fonction.

ResponseSemantics

Contient des informations permettant d’identifier la sémantique de la charge utile de réponse et d’activer le rendu de ces informations dans une expérience visuelle enrichie à l’aide de cartes adaptatives.

ResponseSemanticsProperties

Autorise le mappage des requêtes JSONPath à des éléments de données connus. Chaque requête JSONPath est relative à une valeur de résultat.

SecurityInfo

Contient des informations utilisées pour déterminer le risque relatif d’appel de la fonction.

Exemples

// 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

Définit la référence carte adaptative pour une fonction.

@card(cardPath: valueof CardMetadata)

Target

Operation

Paramètres

Modèles

CardMetadata

ResponseSemantics simplifiés axés sur la carte adaptative.

CardResponseSemanticProperties

Permet de mapper des requêtes JSONPath à des éléments de données connus pour le rendu carte. Chaque requête JSONPath est relative à une valeur de résultat.

Exemples

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

// Card with property mappings for citations and metadata
@card(#{
  dataPath: "$.projects",
  file: "cards/project.json",
  properties: #{
    title: "$.name",
    url: "$.projectUrl",
    subTitle: "$.description",
    thumbnailUrl: "$.teamLogo"
  }
})

@reasoning

Définit les instructions de raisonnement d’une fonction dans une action.

@reasoning(value: valueof string)

Target

Operation

Paramètres

Exemples

// 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

Définit les instructions de réponse d’une fonction dans une action.

@responding(value: valueof string)

Target

Operation

Paramètres

Exemples

// 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.
""")