Edita tu agente Microsoft Copilot Studio en Microsoft Visual Studio Code

Cuando clonas el agente Microsoft Copilot Studio en tu máquina local, puedes editar sus componentes usando las funciones de edición de texto de Microsoft Visual Studio Code. La extensión Copilot Studio ofrece soporte para IntelliSense, validación y lenguaje YAML para hacer la edición eficiente y libre de 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 los problemas con archivos en el panel de Problemas 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. Selecciona cualquier problema para saltar a la ubicación.

Trabajando con los cambios

Cuando se realiza y guarda un cambio, aparece en un color diferente en Visual Studio para que puedas 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.

Puedes usar GitHub Copilot u otros agentes para ayudar a crear nuevos componentes o, si quieres, escribir tus 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 PowerFX:

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

Tools

Las herramientas definen las acciones que tu agente puede realizar. Puedes verlas en el área de Herramientas de la interfaz de agentes de Copilot Studio.

Las herramientas pueden incluir:

• Mensajes
• Flujos de trabajo (flujos de Power Automate)
• Herramientas ACUA
• 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 disparadores suelen hacer referencia a un flujo de trabajo.

kind: ExternalTriggerConfiguration
externalTriggerSource:
  kind: WorkflowExternalTrigger

Gestionar archivos de conocimiento remotos

Si subes documentos usando la función de subida en Copilot Studio, estos documentos están disponibles para descargar haciendo clic en el nombre en la ventana de Archivos de Conocimiento Remoto . 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:

• Usa funda para kebab: 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.