Decoradores para TypeSpec para Microsoft 365 Copilot

Esta referencia trata los decoradores integrados disponibles en TypeSpec para Microsoft 365 Copilot, organizados por su caso de uso principal.

Decoradores de agente declarativo

Estos decoradores se usan al compilar agentes declarativos para definir el comportamiento del agente, el flujo de conversación y la experiencia del usuario.

@agent

Indica que un espacio de nombres representa un agente.

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

Target

Namespace

Parameters

Ejemplos

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

Defina la configuración que modifique el comportamiento de la orquestación del agente.

@behaviorOverrides(behaviorOverrides: valueof BehaviorOverrides)

Target

Namespace

Parameters

Modelos

BehaviorOverrides

Definición de la configuración que modifica el comportamiento de la orquestación del agente

Ejemplos

// 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 un espacio de nombres contiene un inicio de conversación.

@conversationStarter(conversationStarter: valueof ConversationStarter)

Target

Namespace

Parameters

Modelos

ConversationStarter

Objeto de configuración que define un inicio de conversación para los usuarios.

Ejemplos

// 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 un espacio de nombres contiene una extensión personalizada con un par clave-valor para extensibilidad.

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

Target

Namespace

Parameters

Ejemplos

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

Objeto opcional que contiene un mensaje de declinación de responsabilidades que, si se proporciona, se muestra a los usuarios al principio de una conversación para satisfacer los requisitos legales o de cumplimiento.

@disclaimer(disclaimer: valueof Disclaimer)

Target

Namespace

Parameters

Modelos

Aviso de declinación de responsabilidades

Información de declinación de responsabilidades que se muestra a los usuarios.

Ejemplos

// 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 las instrucciones que definen el comportamiento de un agente.

@instructions(instructions: valueof string)

Target

Namespace

Parameters

Ejemplos

// 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 complementos de API

Estos decoradores se usan al compilar complementos de API para definir operaciones de API, autenticación y control de respuestas.

@actions

Define la acción que se puede definir en un objeto info en una especificación de OpenAPI.

@actions(data: valueof ActionMetadata)

Target

Namespace

Parameters

Modelos

ActionMetadata

Metadatos de acción, incluidos nombres legibles, descripciones y direcciones URL.

Ejemplos

// 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 el identificador de referencia de autenticación para el tipo de autenticación.

@authReferenceId(value: valueof string)

Target

Model

Parameters

Ejemplos

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

Admite el objeto de funcionalidades de una función de acción tal como se define en el objeto de manifiesto del complemento de API . Puede usar este decorador para definir tarjetas adaptables sencillas con definiciones pequeñas como confirmation. Para tarjetas adaptables más complejas, puede usar el @card decorador.

@capabilities(capabilities: valueof FunctionCapabilitiesMetadata)

Target

Operation

Parameters

Modelos

Funcionalidades de funciónMetadata

Contiene una colección de datos que se usan para configurar funcionalidades opcionales del orquestador al invocar la función.

Confirmación

Describe cómo el orquestador pide al usuario que confirme antes de llamar a una función.

ResponseSemantics

Contiene información para identificar la semántica de la carga de respuesta y habilitar la representación de esa información en una experiencia visual enriquecida mediante tarjetas adaptables.

ResponseSemanticsProperties

Permite la asignación de consultas JSONPath a elementos de datos conocidos. Cada consulta JSONPath es relativa a un valor de resultado.

SecurityInfo

Contiene información que se usa para determinar el riesgo relativo de invocar la función.

Ejemplos

// 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 la referencia de tarjeta adaptable para una función.

@card(cardPath: valueof CardMetadata)

Target

Operation

Parameters

Modelos

CardMetadata

Respuesta simplificadaSemantics centrados en la tarjeta adaptable.

CardResponseSemanticProperties

Permite la asignación de consultas JSONPath a elementos de datos conocidos para la representación de tarjetas. Cada consulta JSONPath es relativa a un valor de resultado.

Ejemplos

// 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 las instrucciones de razonamiento de una función dentro de una acción.

@reasoning(value: valueof string)

Target

Operation

Parameters

Ejemplos

// 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 las instrucciones de respuesta de una función dentro de una acción.

@responding(value: valueof string)

Target

Operation

Parameters

Ejemplos

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