Decorators für TypeSpec für Microsoft 365 Copilot

In dieser Referenz werden die integrierten Decorators behandelt, die in TypeSpec für Microsoft 365 Copilot verfügbar sind, geordnet nach ihrem primären Anwendungsfall.

Deklarative Agent-Decorators

Diese Decorators werden beim Erstellen deklarativer Agents verwendet, um das Verhalten des Agents, den Konversationsfluss und die Benutzererfahrung zu definieren.

@agent

Gibt an, dass ein Namespace einen Agent darstellt.

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

Ziel

Namespace

Parameter

Beispiele

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

Definieren Sie Einstellungen, die das Verhalten der Agentorchestrierung ändern.

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Ziel

Namespace

Parameter

Modelle

BehaviorOverrides

Definieren von Einstellungen, die das Verhalten der Agentorchestrierung ändern

Beispiele

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

Gibt an, dass ein Namespace einen Konversationsstarter enthält.

@conversationStarter(conversationStarter: valueof ConversationStarter)

Ziel

Namespace

Parameter

Modelle

ConversationStarter

Konfigurationsobjekt, das einen Unterhaltungsstarter für Benutzer definiert.

Beispiele

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

Gibt an, dass ein Namespace eine benutzerdefinierte Erweiterung mit einem Schlüssel-Wert-Paar zur Erweiterbarkeit enthält.

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

Ziel

Namespace

Parameter

Beispiele

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

Ein optionales Objekt, das eine Haftungsausschlussmeldung enthält, die Benutzern zu Beginn einer Unterhaltung angezeigt wird, um gesetzliche oder Complianceanforderungen zu erfüllen.

@disclaimer(disclaimer: valueof Disclaimer)

Ziel

Namespace

Parameter

Modelle

Haftungsausschluss

Die Haftungsausschlussinformationen, die Benutzern angezeigt werden.

Beispiele

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

Definiert die Anweisungen, die das Verhalten eines Agents definieren.

@instructions(instructions: valueof string)

Ziel

Namespace

Parameter

Beispiele

// 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-Plug-In-Decorators

Diese Decorators werden beim Erstellen von API-Plug-Ins verwendet, um API-Vorgänge, Authentifizierung und Antwortverarbeitung zu definieren.

@actions

Definiert die Aktion, die für ein Infoobjekt in einer OpenAPI-Spezifikation definiert werden kann.

@actions(data: valueof ActionMetadata)

Ziel

Namespace

Parameter

Modelle

ActionMetadata

Die Aktionsmetadaten, einschließlich lesbarer Namen, Beschreibungen und URLs.

Beispiele

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

Definiert die Authentifizierungsverweis-ID für den Authentifizierungstyp.

@authReferenceId(value: valueof string)

Ziel

Model

Parameter

Beispiele

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

Unterstützung des Funktionsobjekts einer Aktionsfunktion, wie im Manifestobjekt des API-Plug-Ins definiert. Sie können diesen Decorator verwenden, um einfache adaptive Karten mit kleinen Definitionen wie zu confirmationdefinieren. Für komplexere adaptive Karten können Sie den @card Decorator verwenden.

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Ziel

Operation

Parameter

Modelle

FunctionCapabilitiesMetadata

Enthält eine Sammlung von Daten, die zum Konfigurieren optionaler Funktionen des Orchestrators beim Aufrufen der Funktion verwendet werden.

Bestätigung

Beschreibt, wie der Orchestrator den Benutzer vor dem Aufrufen einer Funktion zur Bestätigung auffordert.

ResponseSemantics

Enthält Informationen, um die Semantik der Antwortnutzlast zu identifizieren und das Rendern dieser Informationen in einer umfassenden visuellen Umgebung mithilfe adaptiver Karten zu ermöglichen.

ResponseSemanticsProperties

Ermöglicht die Zuordnung von JSONPath-Abfragen zu bekannten Datenelementen. Jede JSONPath-Abfrage ist relativ zu einem Ergebniswert.

SecurityInfo

Enthält Informationen, die verwendet werden, um das relative Risiko des Aufrufens der Funktion zu bestimmen.

Beispiele

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

Definiert den adaptiven Karte-Verweis für eine Funktion.

@card(cardPath: valueof CardMetadata)

Ziel

Operation

Parameter

Modelle

CardMetadata

Simplified responseSemantics konzentrierte sich auf die adaptive Karte.

CardResponseSemanticProperties

Ermöglicht die Zuordnung von JSONPath-Abfragen zu bekannten Datenelementen für Karte Rendering. Jede JSONPath-Abfrage ist relativ zu einem Ergebniswert.

Beispiele

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

Definiert die Argumentationsanweisungen einer Funktion innerhalb einer Aktion.

@reasoning(value: valueof string)

Ziel

Operation

Parameter

Beispiele

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

Definiert die Antwortanweisungen einer Funktion innerhalb einer Aktion.

@responding(value: valueof string)

Ziel

Operation

Parameter

Beispiele

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