Editar el agente de Microsoft Copilot Studio en Microsoft Visual Studio Code

Al clonar el agente de Microsoft Copilot Studio en el equipo local, puede editar sus componentes mediante las características de edición de texto de Microsoft Visual Studio Code. La extensión Copilot Studio proporciona compatibilidad con intelliSense, validación y lenguaje YAML para hacer que la edición sea eficaz y sin errores.

Estructura de archivos del agente

Comprender la estructura de los archivos es clave para una edición eficiente.

my-agent/
├── actions                   # Connectors
│   ├── DevOpsAction.mcs.yml  
│   └── GetItems.mcs.yml      
├── knowledge/files                # Knowledge sources
│   ├── source1.yaml
│   └── source2.yaml
├── topics/                   # Conversation topics
│   ├── greeting.mcs.yaml
│   ├── help.mcs.yaml
│   └── escalate.mcs.yaml
├── workflows/                    # Agent tools and actions
│   └── GetDevOpsItems
│       ├── metadata.yaml
│       └── workflow.json
│   └── GetMeetings
│       ├── metadata.yaml
│       └── workflow.json
├── trigger/                 # Event triggers
│   └── welcometrigger.mcs.yaml
├── agent.mcs.yaml                # Main agent definition
├── icon.png                      # Icon used for the agent, visible in test panel and in supported channels
├── settings.mcs.yml              # Configuration settings for the agent
└── connectioreferences.mcs.yml   # Connection References used by Connectors and other actions

Editar la configuración del agente principal

Características de IntelliSense

Mientras escribes, se muestran sugerencias y se resaltan los valores inválidos. Estas sugerencias cambian según el nivel de nodo en el que estés.

• Úsalo Ctrl+Space para obtener sugerencias según el nivel del nodo.
• Úsalo Ctrl+F para buscar nombres de variables y otra información en todo tu agente y actualizarlo rápidamente

Problemas de visualización

Puedes ver problemas con archivos en el panel Problems en Visual Studio Code. Además, cuando abres un archivo, puedes ver un subrayado rojo que identifica problemas.

Panel de problemas

1. Úsalo Ctrl+Shift+M para abrir el panel de Problemas (o ve a Ver>Problemas).

2. Consulta todos los errores y advertencias.

3. Seleccione cualquier problema para saltar a la ubicación.

Trabajando con los cambios

Cuando se realiza y guarda un cambio, se muestra en un color diferente en Visual Studio para que pueda identificarlo fácilmente.

Componentes del agente de edición

Temas

Los temas definen los flujos de conversación y los diálogos. Son un tipo de AdaptiveDialog.

Puede usar GitHub Copilot u otros agentes para ayudar a crear new componentes o, si lo desea, escribir sus propios temas.

Estructura del archivo temático

Aquí tienes un ejemplo de un tema sencillo de saludo:

# This is the name of the topic that will appear in the 'topics' list in Copilot Studio
kind: AdaptiveDialog
beginDialog:
  kind: OnConversationStart
  id: main
  actions:
    - kind: SendActivity
      id: sendMessage_M0LuhV
      activity:
        text:
          - Hello, I'm {System.Bot.Name}. How can I help?
        speak:
          - Hello and thank you for calling {System.Bot.Name}.

Características temáticas avanzadas

Puedes utilizar otros componentes en temas como:

• Entidades:

              - kind: Question
                id: question_1
                alwaysPrompt: true
                variable: init:Topic.Continue
                prompt: Can I help with anything else?
                entity: BooleanPrebuiltEntity
  

• Variables:

    actions:
      - kind: Question
        id: 41d42054-d4cb-4e90-b922-2b16b37fe379
        conversationOutcome: ResolvedImplied
        alwaysPrompt: true
        variable: init:Topic.SurveyResponse
        prompt: Did that answer your question?
        entity: BooleanPrebuiltEntity
  

• Condiciones usando Power Fx:

              - kind: ConditionGroup
                id: condition-1
                conditions:
                  - id: condition-1-item-0
                    condition: =Topic.Continue = true
                    actions:
                      - kind: SendActivity
                        id: sendMessage_4eOE6h
                        activity: Go ahead. I'm listening.
  

• Otros nodos, por ejemplo, nodos HTTP

• Tarjetas Adaptativas

Tools

Las herramientas definen las acciones que tu agente puede realizar. Puede verlos en el área Tools de la interfaz de usuario del agente de Copilot Studio.

Las herramientas pueden incluir:

• Mensajes
• Flujos de trabajo (flujos de Power Automate)
• Herramientas CUA
• Conectores personalizados
• API de REST
• Conectores MCP

Las herramientas aparecen dentro de la extensión bajo la carpeta de /actions un agente, pero también pueden aparecer en otras carpetas con metadatos adicionales. Por ejemplo, los flujos de trabajo y los disparadores tienen sus propias carpetas y JSON.

Disparadores de edición

Los desencadenantes definen cuándo se activan los temas o acciones. Puedes configurarlos como horarios, eventos o tipos condicionales. Los desencadenadores suelen hacer referencia a un flujo de trabajo.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gestionar archivos de conocimiento remotos

Si carga documentos mediante la característica de carga en Copilot Studio, estos documentos están disponibles para descargar haciendo clic en el nombre de la ventana Remote Knowledge Files. Los documentos no se descargan automáticamente y deben seleccionarse para descarga en la ventana. Ves una notificación cuando la descarga es exitosa.

Si quieres subir nuevos archivos, puedes ponerlos en la knowledge/files carpeta de la definición del agente. Cuando aplicas esos cambios, se suben a través de la función de subida de contenido del agente.

procedimientos recomendados

Convenciones de nomenclatura

Archivos:

• Usar kebab-case: create-ticket.tool.yaml
• Sé descriptivo: product-pricing-faq.yaml no faq.yaml
• Utiliza el sufijo tipo: .topic.yaml, .tool.yaml, .trigger.yaml

IDs y variables:

• Usa camelCase: userOrderNumber, productDetails
• Sé descriptivo: checkPaymentStatus no check1
• Evita las abreviaturas: customerEmail not custEmail

Comentarios

Para explicar la lógica compleja, añade comentarios:

nodes:
  # Check if user is within business hours and eligible for live support
  # Business hours: 9 AM - 5 PM EST, Monday-Friday
  # Eligibility: Premium tier customers only
  - id: check-live-support-availability
    type: condition

Pasos siguientes

Ahora que entiendes cómo es la edición:

• Aprende sobre la sincronización.