Saltar a contenido

Abrir el Taller

Selecciona tu experiencia del taller:

Asistentes a Eventos de Microsoft

Las instrucciones en esta página asumen que estás asistiendo a un evento y tienes acceso a un entorno de laboratorio preconfigurado. Este entorno proporciona una suscripción de Azure con todas las herramientas y recursos necesarios para completar el taller.

Introducción

Este taller está diseñado para enseñarte sobre el Servicio de Agentes de Azure AI y el SDK asociado. Consiste en múltiples laboratorios, cada uno destacando una característica específica del Servicio de Agentes de Azure AI. Los laboratorios están destinados a completarse en orden, ya que cada uno se basa en el conocimiento y trabajo del laboratorio anterior.

Recursos de Nube del Taller

Los siguientes recursos están pre-provisionados en tu suscripción de Azure del laboratorio:

  • Un grupo de recursos llamado rg-zava-agent-wks-nnnnnnnn
  • Un hub de Azure AI Foundry llamado fdy-zava-agent-wks-nnnnnnnn
  • Un proyecto de Azure AI Foundry llamado prj-zava-agent-wks-nnnnnnnn
  • Dos modelos están desplegados: gpt-4o-mini y text-embedding-3-small. Ver precios.
  • Base de datos de Azure Database for PostgreSQL Flexible Server (B1ms Burstable 32GB) llamada pg-zava-agent-wks-nnnnnnnn. Ver precios
  • Recurso Application Insights llamado appi-zava-agent-wks-nnnnnnnn. Ver precios

Seleccionar Lenguaje de Programación del Taller

El taller está disponible tanto en Python como en C#. Por favor asegúrate de seleccionar el lenguaje que se ajuste a la sala del laboratorio o preferencia usando las pestañas de selector de lenguaje. Nota, no cambies de lenguaje a mitad del taller.

Selecciona la pestaña de lenguaje que coincida con tu sala de laboratorio:

El lenguaje por defecto para el taller está establecido a Python.

El lenguaje por defecto para el taller está establecido a C#.

La versión C#/.NET de este taller está en beta y tiene problemas de estabilidad conocidos.

Asegúrate de leer la sección de guía de solución de problemas ANTES de comenzar el taller. De lo contrario, selecciona la versión de Python del taller.

Autenticarse con Azure

Necesitas autenticarte con Azure para que la aplicación del agente pueda acceder al Servicio de Agentes de Azure AI y a los modelos. Sigue estos pasos:

  1. Abre una ventana de terminal. La aplicación de terminal está fijada a la barra de tareas de Windows 11.

    Abrir la ventana de terminal

  2. Ejecuta el siguiente comando para autenticarte con Azure:

    az login

    Note

    Se te pedirá que abras un enlace del navegador e inicies sesión en tu cuenta de Azure.

    1. Una ventana del navegador se abrirá automáticamente, selecciona Work or school account y luego selecciona Continue.
    2. Usa el Username y TAP (Temporary Access Pass) que se encuentran en la sección superior de la pestaña Resources en el entorno del laboratorio.
    3. Selecciona Yes, all apps
    4. Selecciona Done

  3. Luego selecciona la suscripción Default desde la línea de comandos, seleccionando Enter.

  4. Deja la ventana de terminal abierta para los siguientes pasos.

Autenticarse con el Servicio DevTunnel

DevTunnel permite al Servicio de Agentes de Azure AI acceder a tu Servidor MCP local durante el taller.

devtunnel login

Note

Se te pedirá usar la cuenta que usaste para az login. Selecciona la cuenta y continúa.

Deja la ventana de terminal abierta para los siguientes pasos.

Abrir el Taller

Sigue estos pasos para abrir el taller en Visual Studio Code:

El siguiente bloque de comandos actualiza el repositorio del taller, activa el entorno virtual de Python y abre el proyecto en VS Code.

Copia y pega el siguiente bloque de comandos al terminal y presiona Enter.

; cd $HOME\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol `
; git pull `
; .\src\python\workshop\.venv\Scripts\activate `
; code .vscode\python-workspace.code-workspace

Cuando el proyecto se abre en VS Code, aparecen dos notificaciones en la esquina inferior derecha. Haz clic en ✖ para cerrar ambas notificaciones.

  1. Abre el taller en Visual Studio Code. Desde la ventana de terminal, ejecuta el siguiente comando:

    ; cd $HOME\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol `
; git pull `
;code .vscode\csharp-workspace.code-workspace

Cuando el proyecto se abre en VS Code, aparecerá una notificación en la esquina inferior derecha para instalar la extensión de C#. Haz clic en Install para instalar la extensión de C#, ya que esto proporcionará las características necesarias para el desarrollo en C#.

  1. Abre el taller en Visual Studio 2022. Desde la ventana de terminal, ejecuta el siguiente comando:

    ; git pull `
;cd $HOME; start .\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol\src\csharp\McpAgentWorkshop.slnx

    Es posible que se te pregunte con qué programa abrir la solución. Selecciona Visual Studio 2022.

Estructura del Proyecto

Familiarízate con las carpetas y archivos clave en el espacio de trabajo con los que trabajarás durante todo el taller.

La carpeta "workshop"

  • El archivo app.py: El punto de entrada para la aplicación, conteniendo su lógica principal.

    Nota la variable INSTRUCTIONS_FILE—establece qué archivo de instrucciones usa el agente. Actualizarás esta variable en un laboratorio posterior.

  • El archivo resources.txt: Contiene los recursos utilizados por la aplicación del agente.

  • El archivo .env: Contiene las variables de entorno utilizadas por la aplicación del agente.

La carpeta "mcp_server"

  • El archivo sales_analysis.py: El Servidor MCP con herramientas para análisis de ventas.

La carpeta "shared/instructions"

  • La carpeta instructions: Contiene las instrucciones pasadas al LLM.

Estructura de carpetas del laboratorio

Estructura del Proyecto

El proyecto usa Aspire para simplificar la construcción de la aplicación del agente, gestionar el servidor MCP y orquestar todas las dependencias externas. La solución está compuesta por cuatro proyectos, todos con el prefijo McpAgentWorkshop:

  • AppHost: El orquestador de Aspire, y proyecto de lanzamiento para el taller.
  • McpServer: El proyecto del servidor MCP.
  • ServiceDefaults: Configuración predeterminada para servicios, como registro y telemetría.
  • WorkshopApi: La API del Agente para el taller. La lógica principal de la aplicación está en la clase AgentService.

Además de los proyectos .NET en la solución, hay una carpeta shared (visible como una Carpeta de Solución, y a través del explorador de archivos), que contiene:

  • instructions: Las instrucciones pasadas al LLM.
  • scripts: Scripts shell auxiliares para varias tareas, se hará referencia a estos cuando sea necesario.
  • webapp: La aplicación cliente front-end. Nota: Esta es una aplicación Python, cuyo ciclo de vida será gestionado por Aspire.

Estructura de carpetas del laboratorio

Traducido usando GitHub Copilot.

Estudiantes Autoguiados

Estas instrucciones son para estudiantes autoguiados que no tienen acceso a un entorno de laboratorio preconfigurado. Sigue estos pasos para configurar tu entorno y comenzar el taller.

Introducción

Este taller está diseñado para enseñarte sobre el Servicio de Agentes de Azure AI y el SDK asociado. Consiste en múltiples laboratorios, cada uno destacando una característica específica del Servicio de Agentes de Azure AI. Los laboratorios están destinados a completarse en orden, ya que cada uno se basa en el conocimiento y trabajo del laboratorio anterior.

Prerrequisitos

  1. Acceso a una suscripción de Azure. Si no tienes una suscripción de Azure, crea una cuenta gratuita antes de comenzar.
  2. Necesitas una cuenta de GitHub. Si no tienes una, créala en GitHub.

Seleccionar Lenguaje de Programación del Taller

El taller está disponible tanto en Python como en C#. Usa las pestañas de selector de lenguaje para elegir tu lenguaje preferido. Nota, no cambies de lenguaje a mitad del taller.

Selecciona la pestaña para tu lenguaje preferido:

El lenguaje por defecto para el taller está establecido a Python.

El lenguaje por defecto para el taller está establecido a C#.

La versión C#/.NET de este taller está en beta y tiene problemas de estabilidad conocidos.

Asegúrate de leer la sección de guía de solución de problemas ANTES de comenzar el taller. De lo contrario, selecciona la versión de Python del taller.

Abrir el Taller

Preferido: GitHub Codespaces, que proporciona un entorno preconfigurado con todas las herramientas requeridas. Alternativamente, ejecuta localmente con un Dev Container de Visual Studio Code y Docker. Usa las pestañas a continuación para elegir.

Tip

Las compilaciones de Codespaces o Dev Container toman aproximadamente 5 minutos. Inicia la compilación, luego continúa leyendo mientras se completa.

Selecciona Abrir en GitHub Codespaces para abrir el proyecto en GitHub Codespaces.

Abrir en GitHub Codespaces

  1. Asegúrate de tener lo siguiente instalado en tu máquina local:

  2. Clona el repositorio en tu máquina local:

    git clone https://github.com/microsoft/aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol.git

  3. Abre el repositorio clonado en Visual Studio Code.

  4. Cuando se te solicite, selecciona Reabrir en Contenedor para abrir el proyecto en un Dev Container.

Autenticar Servicios de Azure

Danger

Antes de proceder, asegúrate de que tu Codespace o Dev Container esté completamente construido y listo.

Autenticarse con DevTunnel

DevTunnel proporciona un servicio de reenvío de puertos que se usará en el taller para permitir al Servicio de Agentes de Azure AI acceder al Servidor MCP que ejecutarás en tu entorno de desarrollo local. Sigue estos pasos para autenticarte:

  1. Desde VS Code, presiona Ctrl + Shift + ` para abrir una nueva ventana de terminal. Luego ejecuta el siguiente comando:
  2. Ejecuta el siguiente comando para autenticarte con DevTunnel:
devtunnel login

  1. Sigue estos pasos para autenticarte:

  2. Copia el Código de Autenticación al portapapeles.

  3. Mantén presionada la tecla ctrl o cmd.
  4. Selecciona la URL de autenticación para abrirla en tu navegador.
  5. Pega el código y haz clic en Siguiente.
  6. Elige una cuenta e inicia sesión.
  7. Selecciona Continuar

  8. Regresa a la ventana de terminal en VS Code.

  9. Deja la ventana de terminal abierta para los siguientes pasos.

Autenticarse con Azure

Auténticate con Azure para permitir que la aplicación del agente acceda al Servicio de Agentes de Azure AI y a los modelos. Sigue estos pasos:

  1. Luego ejecuta el siguiente comando:

    az login --use-device-code

    Warning

    Si tienes múltiples inquilinos de Azure, especifica el correcto usando:

    az login --use-device-code --tenant <tenant_id>

  2. Sigue estos pasos para autenticarte:

    1. Copia el Código de Autenticación al portapapeles.
    2. Mantén presionada la tecla ctrl o cmd.
    3. Selecciona la URL de autenticación para abrirla en tu navegador.
    4. Pega el código y haz clic en Siguiente.
    5. Elige una cuenta e inicia sesión.
    6. Selecciona Continuar
    7. Regresa a la ventana de terminal en VS Code.
    8. Si se te solicita, selecciona una suscripción.

  3. Deja la ventana de terminal abierta para los siguientes pasos.

Desplegar los Recursos de Azure

Este despliegue crea los siguientes recursos en tu suscripción de Azure.

  • Un grupo de recursos llamado rg-zava-agent-wks-nnnnnnnn
  • Un hub de Azure AI Foundry llamado fdy-zava-agent-wks-nnnnnnnn
  • Un proyecto de Azure AI Foundry llamado prj-zava-agent-wks-nnnnnnnn
  • Dos modelos están desplegados: gpt-4o-mini y text-embedding-3-small. Ver precios.
  • Recurso Application Insights llamado appi-zava-agent-wks-nnnnnnnn. Ver precios
  • Para mantener bajos los costos del taller, PostgreSQL se ejecuta en un contenedor local dentro de tu Codespace o Dev Container en lugar de como un servicio en la nube. Ve Azure Database for PostgreSQL Flexible Server para aprender sobre las opciones para un servicio PostgreSQL administrado.

Asegúrate de tener al menos las siguientes cuotas de modelo" - Cuota de 120K TPM para el SKU Global Standard de gpt-4o-mini, ya que el agente hace llamadas frecuentes al modelo. - 50K TPM para el modelo text-embedding-3-small SKU Global Standard. - Verifica tu cuota en el Centro de Gestión de AI Foundry.

Despliegue Automatizado

Ejecuta el siguiente script bash para automatizar el despliegue de los recursos requeridos para el taller. El script deploy.sh despliega recursos en la región westus por defecto. Para ejecutar el script:

cd infra && ./deploy.sh

Configuración del Taller

Configuración de Recursos de Azure

El script de despliegue genera el archivo .env, que contiene los endpoints del proyecto y modelo, nombres de despliegue del modelo, y cadena de conexión de Application Insights. El archivo .env se guardará automáticamente en la carpeta src/python/workshop.

Tu archivo .env se verá similar al siguiente, actualizado con tus valores:

PROJECT_ENDPOINT="<tu_endpoint_del_proyecto>"
GPT_MODEL_DEPLOYMENT_NAME="<tu_nombre_despliegue_modelo>"
EMBEDDING_MODEL_DEPLOYMENT_NAME="<tu_nombre_despliegue_modelo_embedding>"
APPLICATIONINSIGHTS_CONNECTION_STRING="<tu_cadena_conexion_application_insights>"
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED="true"
AZURE_OPENAI_ENDPOINT="<tu_endpoint_azure_openai>"

Nombres de Recursos de Azure

También encontrarás un archivo llamado resources.txt en la carpeta workshop. Este archivo contiene los nombres de los recursos de Azure creados durante el despliegue.

Se verá similar al siguiente:

Recursos de Azure AI Foundry:
- Nombre del Grupo de Recursos: rg-zava-agent-wks-nnnnnnnn
- Nombre del Proyecto AI: prj-zava-agent-wks-nnnnnnnn
- Nombre del Recurso Foundry: fdy-zava-agent-wks-nnnnnnnn
- Nombre de Application Insights: appi-zava-agent-wks-nnnnnnnn

El script almacena de forma segura las variables del proyecto usando el Secret Manager para secretos de desarrollo de ASP.NET Core.

Puedes ver los secretos ejecutando el siguiente comando después de haber abierto el espacio de trabajo de C# en VS Code:

dotnet user-secrets list

Abrir el Espacio de Trabajo de VS Code

Hay dos espacios de trabajo de VS Code en el taller, uno para Python y uno para C#. El espacio de trabajo contiene el código fuente y todos los archivos necesarios para completar los laboratorios para cada lenguaje. Elige el espacio de trabajo que coincida con el lenguaje con el que quieres trabajar.

  1. Copia la siguiente ruta al portapapeles:

    /workspace/.vscode/python-workspace.code-workspace

  2. Desde el menú de VS Code, selecciona Archivo luego Abrir Espacio de Trabajo desde Archivo.

  3. Reemplaza y pega el nombre de ruta copiado y selecciona OK.

Estructura del Proyecto

Familiarízate con las carpetas y archivos clave en el espacio de trabajo con los que trabajarás durante todo el taller.

La carpeta "workshop"

  • El archivo app.py: El punto de entrada para la aplicación, conteniendo su lógica principal.

    Nota la variable INSTRUCTIONS_FILE—establece qué archivo de instrucciones usa el agente. Actualizarás esta variable en un laboratorio posterior.

  • El archivo resources.txt: Contiene los recursos utilizados por la aplicación del agente.

  • El archivo .env: Contiene las variables de entorno utilizadas por la aplicación del agente.

La carpeta "mcp_server"

  • El archivo sales_analysis.py: El Servidor MCP con herramientas para análisis de ventas.

La carpeta "shared/instructions"

  • La carpeta instructions: Contiene las instrucciones pasadas al LLM.

Estructura de carpetas del laboratorio

  1. En Visual Studio Code, ve a Archivo > Abrir Espacio de Trabajo desde Archivo.

  2. Reemplaza la ruta por defecto con la siguiente:

    /workspace/.vscode/csharp-workspace.code-workspace

  3. Selecciona OK para abrir el espacio de trabajo.

Estructura del Proyecto

El proyecto usa Aspire para simplificar la construcción de la aplicación del agente, gestionar el servidor MCP y orquestar todas las dependencias externas. La solución está compuesta por cuatro proyectos, todos con el prefijo McpAgentWorkshop:

  • AppHost: El orquestador de Aspire, y proyecto de lanzamiento para el taller.
  • McpServer: El proyecto del servidor MCP.
  • ServiceDefaults: Configuración predeterminada para servicios, como registro y telemetría.
  • WorkshopApi: La API del Agente para el taller. La lógica principal de la aplicación está en la clase AgentService.

Además de los proyectos .NET en la solución, hay una carpeta shared (visible como una Carpeta de Solución, y a través del explorador de archivos), que contiene:

  • instructions: Las instrucciones pasadas al LLM.
  • scripts: Scripts shell auxiliares para varias tareas, se hará referencia a estos cuando sea necesario.
  • webapp: La aplicación cliente front-end. Nota: Esta es una aplicación Python, cuyo ciclo de vida será gestionado por Aspire.

Estructura de carpetas del laboratorio

Traducido usando GitHub Copilot.

Traducido usando GitHub Copilot.