Decoradores para TypeSpec para Microsoft 365 Copilot

Esta referência abrange os decoradores incorporados disponíveis no TypeSpec para Microsoft 365 Copilot, organizados pelo seu caso de utilização principal.

Decoradores de agentes declarativos

Estes decoradores são utilizados ao criar agentes declarativos para definir o comportamento do agente, o fluxo de conversação e a experiência do utilizador.

@agent

Indica que um espaço de nomes representa um agente.

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

Target

Namespace

Parâmetros

Exemplos

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

Definir definições que modificam o comportamento da orquestração do agente.

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Target

Namespace

Parâmetros

Modelos

BehaviorOverrides

Definir definições que modificam o comportamento da orquestração do agente

Exemplos

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

Indica que um espaço de nomes contém um iniciador de conversação.

@conversationStarter(conversationStarter: valueof ConversationStarter)

Target

Namespace

Parâmetros

Modelos

ConversationStarter

Objeto de configuração que define um iniciador de conversação para os utilizadores.

Exemplos

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

Indica que um espaço de nomes contém uma extensão personalizada com um par chave-valor para extensibilidade.

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

Target

Namespace

Parâmetros

Exemplos

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

Um objeto opcional que contém uma mensagem de exclusão de responsabilidade que, se for fornecida, é apresentado aos utilizadores no início de uma conversação para satisfazer os requisitos legais ou de conformidade.

@disclaimer(disclaimer: valueof Disclaimer)

Target

Namespace

Parâmetros

Modelos

Aviso de isenção

As informações de exclusão de responsabilidade que são apresentadas aos utilizadores.

Exemplos

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

Define as instruções que definem o comportamento de um agente.

@instructions(instructions: valueof string)

Target

Namespace

Parâmetros

Exemplos

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

Decoradores de plug-ins de API

Estes decoradores são utilizados ao criar plug-ins de API para definir operações de API, autenticação e processamento de respostas.

@actions

Define a ação que pode ser definida num objeto de informações numa especificação OpenAPI.

@actions(data: valueof ActionMetadata)

Target

Namespace

Parâmetros

Modelos

ActionMetadata

Os metadados de ação, incluindo nomes legíveis por humanos, descrições e URLs.

Exemplos

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

Define o ID de referência de autenticação para o tipo de autenticação.

@authReferenceId(value: valueof string)

Target

Model

Parâmetros

Exemplos

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

Suporte o objeto de capacidades de uma função de ação, conforme definido no objeto de manifesto do plug-in da API . Pode utilizar este decorador para definir cartões adaptáveis simples com pequenas definições como confirmation. Para cartões ajustáveis mais complexos, pode utilizar o @card decorador.

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Target

Operation

Parâmetros

Modelos

FunctionCapabilitiesMetadata

Contém uma coleção de dados utilizados para configurar capacidades opcionais do orquestrador ao invocar a função.

Confirmação

Descreve como o orquestrador pede ao utilizador para confirmar antes de chamar uma função.

ResponseSemantics

Contém informações para identificar a semântica do payload de resposta e ativar a composição dessa informação numa experiência visual avançada com Cartões Ajustáveis.

ResponseSemanticsProperties

Permite o mapeamento de consultas JSONPath para elementos de dados conhecidos. Cada consulta JSONPath é relativa a um valor de resultado.

SecurityInfo

Contém informações utilizadas para determinar o risco relativo de invocar a função.

Exemplos

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

Define a referência de card adaptável para uma função.

@card(cardPath: valueof CardMetadata)

Target

Operation

Parâmetros

Modelos

CardMetadata

Resposta simplificadaSemantics focada na card adaptável.

CardResponseSemanticProperties

Permite o mapeamento de consultas JSONPath para elementos de dados conhecidos para composição de card. Cada consulta JSONPath é relativa a um valor de resultado.

Exemplos

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

Define as instruções de raciocínio de uma função numa ação.

@reasoning(value: valueof string)

Target

Operation

Parâmetros

Exemplos

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

Define as instruções de resposta de uma função numa ação.

@responding(value: valueof string)

Target

Operation

Parâmetros

Exemplos

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