Tutorial práctico: Cómo editar agentes de Copilot Studio desde VS Code con un ejemplo real

¿Por qué usar VS Code para desarrollar agentes de Copilot Studio?

Si trabajas con agentes de IA en Copilot Studio, probablemente ya conoces la interfaz web. Funciona bien para tareas básicas, pero cuando tu agente crece (múltiples topics, acciones, triggers...), la cosa se complica. Ahí es donde entra la extensión oficial de VS Code.

La extensión te permite trabajar con tus agentes como si fueran código: archivos YAML que puedes editar, versionar con Git, y sincronizar con la nube. Y lo mejor: puedes combinarla con GitHub Copilot o Claude Code para que te ayuden a escribir las definiciones.

Lo que vas a aprender en este tutorial

• Instalar y configurar la extensión desde cero
• Entender el proceso de autenticación y permisos
• Clonar un agente existente a tu máquina local
• Explorar la estructura de archivos de un agente
• Editar un topic directamente en YAML con un ejemplo completo
• Crear un nuevo topic desde cero
• Sincronizar los cambios de vuelta a Copilot Studio
• Integrar el flujo con Git para control de versiones

Requisitos previos

Antes de empezar, asegúrate de tener:

• Visual Studio Code instalado (versión 1.80 o superior recomendada)
• Una cuenta de Microsoft 365 con acceso a Copilot Studio
• Al menos un agente creado en Copilot Studio (aunque sea uno de prueba)
• Opcionalmente: Git instalado para control de versiones
• Opcionalmente: GitHub Copilot para asistencia con IA

 

Paso 1: Instalar la extensión

Abre VS Code, ve a la pestaña de Extensiones (Ctrl+Shift+X en Windows/Linux, Cmd+Shift+X en Mac) y busca "Copilot Studio". Asegúrate de instalar la extensión oficial de Microsoft (verás el logo verificado).

Una vez instalada, verás un nuevo icono en la barra lateral izquierda con el logo de Copilot Studio. Si no lo ves inmediatamente, puede que necesites reiniciar VS Code.

Configuración inicial y autenticación

Al hacer clic en el icono de Copilot Studio por primera vez, la extensión te pedirá permiso para iniciar sesión. Haz clic en "Sign In" y después en "Allow".

Se abrirá tu navegador con la página de autenticación de Microsoft. Introduce las credenciales de tu cuenta de Microsoft 365 (la misma que usas para acceder a Copilot Studio en la web). Si tienes autenticación multifactor habilitada, completa el proceso.

La extensión solicitará los siguientes permisos:

• Leer y escribir agentes en tu entorno
• Acceder a la información del entorno
• Sincronizar archivos con la nube

Acepta los permisos para continuar. Una vez autenticado, volverás a VS Code y verás la lista de entornos disponibles.

Paso 2: Clonar tu agente

Hay dos formas de clonar un agente existente:

Opción A: Desde el portapapeles (más rápido)

1. Abre tu agente en Copilot Studio desde el navegador
2. Copia la URL completa de la barra de direcciones
3. En VS Code, haz clic en "Clone agent"
4. Verás tu agente marcado como "from clipboard" - selecciónalo

Opción B: Navegando por entornos

1. Haz clic en "Clone agent"
2. Selecciona el entorno donde está tu agente
3. Navega por la lista y selecciona el agente

En ambos casos, la extensión te pedirá que elijas una carpeta local para guardar los archivos del agente. Recomendación: crea una carpeta dedicada para cada agente, similar a cómo organizarías repositorios de código.

El proceso de clonación descarga toda la definición del agente: topics, actions, triggers, knowledge sources y configuración. Dependiendo del tamaño del agente, esto puede tardar unos segundos.

Paso 3: Explorar la estructura del agente

Una vez clonado, abre el explorador de archivos de VS Code. Verás una estructura similar a esta:

mi-agente/
├── topics/
│   ├── greeting.yaml
│   ├── fallback.yaml
│   └── custom-topic.yaml
├── actions/
│   └── get-weather.yaml
├── triggers/
│   └── on-conversation-start.yaml
├── knowledge/
│   └── faq-source.yaml
├── settings.yaml
└── agent.yaml

Cada carpeta tiene un propósito específico:

• topics/ - Los flujos conversacionales. Cada archivo define un topic completo con sus nodos, condiciones y respuestas.
• actions/ - Acciones que el agente puede ejecutar, como llamadas a APIs o conectores de Power Platform.
• triggers/ - Desencadenadores que inician conversaciones o reaccionan a eventos.
• knowledge/ - Referencias a fuentes de conocimiento (documentos, sitios web, etc.).
• settings.yaml - Configuración general del agente: nombre, idioma, comportamiento por defecto.
• agent.yaml - Metadatos del agente y referencias a los componentes.

La extensión activa automáticamente IntelliSense y validación de esquema para estos archivos YAML, lo que te ayuda a evitar errores de sintaxis.

 

Ejemplo práctico 1: Modificar un topic de saludo

Vamos con el primer ejemplo. Supongamos que quieres que tu agente responda con un mensaje más personalizado cuando el usuario dice "hola".

Paso 1: Localizar el archivo

Abre la carpeta topics/ y busca el archivo del topic de saludo. Puede llamarse greeting.yaml, saludo.yaml o similar dependiendo de cómo lo creaste originalmente.

Paso 2: Entender la estructura

Un topic típico tiene esta estructura:

kind: AdaptiveDialog
modelDescription: Topic para saludar al usuario
beginDialog:
  kind: OnConversationStart
  actions:
    - kind: SendActivity
      activity:
        text:
          - "¡Hola! ¿En qué puedo ayudarte hoy?"
triggers:
  - kind: OnRecognizedIntent
    intent: Greeting
    actions:
      - kind: BeginDialog

Los elementos clave son:

• kind: El tipo de componente (AdaptiveDialog para topics)
• modelDescription: Descripción para el modelo de IA
• beginDialog: Las acciones que se ejecutan cuando se activa el topic
• triggers: Las condiciones que activan este topic

Paso 3: Modificar el mensaje

Ahora, edita el archivo para añadir una respuesta más dinámica y profesional:

kind: AdaptiveDialog
modelDescription: Topic de bienvenida personalizado para nuevos usuarios
beginDialog:
  kind: OnConversationStart
  actions:
    - kind: SendActivity
      activity:
        text:
          - "¡Bienvenido! 👋 Soy tu asistente virtual."
          - "Puedo ayudarte con:"
          - "• Consultas sobre productos"
          - "• Soporte técnico"
          - "• Información general"
          - "¿Por dónde te gustaría empezar?"
triggers:
  - kind: OnRecognizedIntent
    intent: Greeting
    actions:
      - kind: BeginDialog

Observa que el campo text acepta un array de strings. Cada elemento se mostrará como una línea separada en el chat, lo que mejora la legibilidad.

Paso 4: Guardar

Guarda el archivo (Ctrl+S). Los cambios quedan en local hasta que decidas sincronizarlos con la nube.

 

Ejemplo práctico 2: Crear un nuevo topic desde cero

Vamos a crear un topic completamente nuevo para manejar preguntas sobre horarios de atención.

Paso 1: Crear el archivo

En la carpeta topics/, crea un nuevo archivo llamado horarios.yaml.

Paso 2: Definir la estructura completa

Copia y pega el siguiente contenido:

kind: AdaptiveDialog
modelDescription: Responde preguntas sobre horarios de atención al cliente
beginDialog:
  kind: OnBeginDialog
  actions:
    - kind: Question
      questionKind: ChoiceQuestion
      prompt: "¿Sobre qué horario te gustaría saber?"
      variable: init.tipoHorario
      entities:
        - kind: ChoiceEntity
          choices:
            - "Atención telefónica"
            - "Chat en línea"
            - "Tienda física"
    - kind: ConditionGroup
      conditions:
        - condition: =init.tipoHorario = "Atención telefónica"
          actions:
            - kind: SendActivity
              activity:
                text:
                  - "📞 **Atención telefónica**"
                  - "Lunes a Viernes: 9:00 - 18:00"
                  - "Sábados: 10:00 - 14:00"
                  - "Domingos y festivos: Cerrado"
        - condition: =init.tipoHorario = "Chat en línea"
          actions:
            - kind: SendActivity
              activity:
                text:
                  - "💬 **Chat en línea**"
                  - "Disponible 24/7"
                  - "Tiempo de respuesta promedio: 5 minutos"
        - condition: =init.tipoHorario = "Tienda física"
          actions:
            - kind: SendActivity
              activity:
                text:
                  - "🏪 **Tienda física**"
                  - "Lunes a Sábado: 10:00 - 21:00"
                  - "Domingos: 11:00 - 20:00"
triggers:
  - kind: OnRecognizedIntent
    intent: PreguntaHorario
    actions:
      - kind: BeginDialog

Este topic es más avanzado porque incluye:

• Question: Hace una pregunta al usuario con opciones
• Variable: Guarda la respuesta en una variable
• ConditionGroup: Ejecuta diferentes acciones según la respuesta
• Formato enriquecido: Usa emojis y markdown para mejorar la presentación

Paso 3: Registrar el intent

Para que el agente reconozca cuándo activar este topic, necesitas definir frases de ejemplo. Esto se hace en el sistema de intents de Copilot Studio, que normalmente se gestiona desde la interfaz web. Sin embargo, puedes añadir descripciones en modelDescription para guiar al modelo.

Paso 4: Sincronizar con Copilot Studio

Una vez que hayas hecho tus cambios (modificaciones o nuevos archivos), es hora de subirlos a la nube.

En VS Code, busca el panel "Agent Changes" dentro de la vista de Copilot Studio. Verás tres botones principales:

Preview changes

Ver qué ha cambiado entre tu versión local y la del servidor. Es como un git diff: te muestra las diferencias sin modificar nada. Útil para revisar antes de aplicar.

Get changes

Descargar cambios que se hayan hecho desde la interfaz web de Copilot Studio. Si alguien más ha editado el agente desde la web mientras tú trabajabas en local, este botón trae esos cambios.

Apply changes

Subir tus cambios locales al agente en la nube. ¡Importante! Los cambios se aplican en vivo e inmediatamente. Tu agente se actualiza al instante.

Haz clic en Apply changes y espera unos segundos. Una vez completado, puedes abrir Copilot Studio en el navegador y probar los cambios en el chat de prueba.

 

Integración con Git: Control de versiones profesional

Una de las grandes ventajas de trabajar con archivos locales es poder usar Git para control de versiones. Aquí te explico cómo configurarlo:

Inicializar el repositorio

cd mi-agente
git init
git add .
git commit -m "Initial commit: Agent definition"

Crear un .gitignore

Crea un archivo .gitignore en la raíz:

# Archivos temporales de VS Code
.vscode/
*.log

# Archivos de sistema
.DS_Store
Thumbs.db

Flujo de trabajo recomendado

1. Crea una branch para cada cambio: git checkout -b feature/nuevo-topic-horarios
2. Haz commits atómicos con mensajes descriptivos
3. Abre un Pull Request para revisión de código
4. Mergea cuando esté aprobado
5. Apply changes desde la branch principal

Este flujo te permite tener un historial completo de cambios, revertir errores fácilmente, y colaborar con otros desarrolladores.

 

Bonus: Usar GitHub Copilot para escribir topics

Si tienes GitHub Copilot activo en VS Code, puedes aprovecharlo para generar YAML más rápido.

Técnica 1: Comentarios descriptivos

Escribe un comentario describiendo lo que quieres:

# Topic para manejar quejas de clientes
# Debe pedir el número de pedido, mostrar empatía,
# y ofrecer opciones de resolución: reembolso, reenvío o crédito

GitHub Copilot puede generar el YAML completo basándose en ese contexto.

Técnica 2: Copilot Chat

Abre Copilot Chat (Ctrl+Shift+I) y pide ayuda directamente:

"Genera un topic de Copilot Studio en YAML para manejar solicitudes de devolución de productos. Debe incluir validación del número de pedido y ofrecer tres opciones de resolución."

Copilot generará el código que puedes copiar y adaptar.

 

Ventajas del flujo de trabajo en VS Code

• Control de versiones completo: Usa Git para trackear cada cambio, crear branches experimentales, y revertir errores sin perder trabajo.
• Búsqueda potente: Encuentra cualquier texto en todo el agente con Ctrl+Shift+F. Ideal para refactorizar o buscar referencias.
• Colaboración real: Múltiples desarrolladores pueden trabajar en el mismo agente con flujos de revisión de código y pull requests.
• Automatización con CI/CD: Integra con Azure DevOps o GitHub Actions para despliegues automatizados a diferentes entornos.
• Productividad: Atajos de teclado, snippets, extensiones, y todas las herramientas de un IDE profesional.

Limitaciones a tener en cuenta

No todo es perfecto. Algunas consideraciones:

• Cambios en vivo: Cuando aplicas cambios, van directamente al entorno. En producción, usa entornos de desarrollo/staging para probar primero.
• No todo es editable: Algunas configuraciones avanzadas (como ciertos tipos de conectores o configuraciones de canal) siguen requiriendo la interfaz web.
• Conflictos de sincronización: Si editas desde la web y desde VS Code simultáneamente, pueden surgir conflictos. Establece un flujo claro con tu equipo.
• Curva de aprendizaje: El formato YAML de Copilot Studio tiene su propia sintaxis. Consulta la documentación oficial para casos avanzados.

Recursos adicionales

Para profundizar más en el desarrollo con la extensión de VS Code:

• Repositorio oficial en GitHub - Código fuente, issues y releases
• Blog oficial de Copilot Studio - Anuncios y novedades

Conclusión

La extensión de Copilot Studio para VS Code transforma la forma de desarrollar agentes de IA. Pasas de una experiencia puramente visual a un flujo de desarrollo profesional con control de versiones, colaboración en equipo, y todas las herramientas de un IDE moderno.

Si tu agente tiene más de unos pocos topics, o si trabajas en equipo, esta extensión es prácticamente imprescindible. El tiempo invertido en configurarla se recupera rápidamente en productividad y calidad del código.

¿Ya has probado la extensión? Cuéntanos tu experiencia en los comentarios.