Microsoft 365 Copilotの TypeSpec のデコレーター

このリファレンスでは、TypeSpec for Microsoft 365 Copilotで使用できる組み込みのデコレーターについて、主なユース ケース別に整理されています。

宣言型エージェント デコレーター

これらのデコレーターは、エージェントの動作、会話フロー、およびユーザー エクスペリエンスを定義するために宣言型エージェントを構築するときに使用されます。

@agent

名前空間がエージェントを表していることを示します。

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

Target

Namespace

パラメーター

例

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

エージェント オーケストレーションの動作を変更する設定を定義します。

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Target

Namespace

パラメーター

モデル

BehaviorOverrides

エージェント オーケストレーションの動作を変更する設定を定義する

例

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

名前空間に会話スターターが含まれていることを示します。

@conversationStarter(conversationStarter: valueof ConversationStarter)

Target

Namespace

パラメーター

モデル

ConversationStarter

ユーザーの会話スターターを定義する構成オブジェクト。

例

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

拡張のキーと値のペアを持つカスタム拡張機能が名前空間に含まれていることを示します。

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

Target

Namespace

パラメーター

例

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

指定された場合は、法的またはコンプライアンスの要件を満たすために、会話の開始時にユーザーに表示される免責事項メッセージを含む省略可能なオブジェクト。

@disclaimer(disclaimer: valueof Disclaimer)

Target

Namespace

パラメーター

モデル

免責事項

ユーザーに表示される免責事項情報。

例

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

エージェントの動作を定義する命令を定義します。

@instructions(instructions: valueof string)

Target

Namespace

パラメーター

例

// 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 プラグイン デコレーター

これらのデコレーターは、API プラグインをビルドして API 操作、認証、応答処理を定義するときに使用されます。

@actions

OpenAPI 仕様の info オブジェクトに対して定義できるアクションを定義します。

@actions(data: valueof ActionMetadata)

Target

Namespace

パラメーター

モデル

ActionMetadata

人間が読み取り可能な名前、説明、URL を含むアクション メタデータ。

例

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

認証の種類の認証参照 ID を定義します。

@authReferenceId(value: valueof string)

Target

Model

パラメーター

例

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

API プラグイン マニフェスト オブジェクトで定義されているアクション関数の capabilities オブジェクトをサポートします。 このデコレーターを使用すると、 confirmationのような小さな定義を持つ単純なアダプティブ カードを定義できます。 より複雑なアダプティブ カードの場合は、 @card デコレーターを使用できます。

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Target

Operation

パラメーター

モデル

FunctionCapabilitiesMetadata

関数の呼び出し中にオーケストレーターのオプション機能を構成するために使用されるデータのコレクションが含まれます。

確認

オーケストレーターが、関数を呼び出す前にユーザーに確認を求める方法について説明します。

ResponseSemantics

応答ペイロードのセマンティクスを識別し、アダプティブ カードを使用したリッチ ビジュアル エクスペリエンスでその情報のレンダリングを可能にする情報が含まれています。

ResponseSemanticsProperties

既知のデータ要素への JSONPath クエリのマッピングを許可します。 各 JSONPath クエリは、結果の値に対して相対的です。

SecurityInfo

関数を呼び出す相対的なリスクを判断するために使用する情報が含まれています。

例

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

関数のアダプティブ カード参照を定義します。

@card(cardPath: valueof CardMetadata)

Target

Operation

パラメーター

モデル

CardMetadata

アダプティブ カードに焦点を当てた簡略化された応答Semantics。

CardResponseSemanticProperties

カードレンダリングのために、JSONPath クエリを既知のデータ要素にマッピングできます。 各 JSONPath クエリは、結果の値に対して相対的です。

例

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

アクション内の関数の推論命令を定義します。

@reasoning(value: valueof string)

Target

Operation

パラメーター

例

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

アクション内の関数の応答命令を定義します。

@responding(value: valueof string)

Target

Operation

パラメーター

例

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