Декораторы для TypeSpec для #REF!

В этом справочнике рассматриваются встроенные декораторы, доступные в TypeSpec для #REF!, упорядоченные по их основному варианту использования.

Декораторы декларативных агентов

Эти декораторы используются при создании декларативных агентов для определения поведения агента, потока общения и взаимодействия с пользователем.

@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

Определяет действие, которое может быть определено для объекта info в спецификации OpenAPI.

@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

Определяет идентификатор ссылки на проверку подлинности для типа проверки подлинности.

@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

Поддержка объекта возможностей функции действия, определенного в объекте манифеста подключаемого модуля . Этот декоратор можно использовать для определения простых адаптивных карточек с небольшими определениями, такими как 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

Упрощенные ответыСемантика ориентирована на адаптивный карта.

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