diff --git a/AUTHORING.md b/AUTHORING.md index fd226b81..50124d46 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -16,7 +16,7 @@ copilot-workshops/ │ ├── vscode/ ← VS Code lessons (0-prerequisites.md + numbered exercises) │ ├── cloud/ ← Cloud agent lessons (0-prerequisites.md + numbered exercises) │ ├── app/ ← GitHub Copilot app lessons (setup folded into Exercise 1) -│ ├── es-es/ ja-jp/ ... ← Translated locale trees (currently the app harness) +│ ├── es-es/ ja-jp/ ... ← Translated locale trees (app harness and selected VS Code content) │ └── _images/ ← Screenshots and diagrams (shared across locales) ├── website/ ← Optional Astro + Starlight publisher │ ├── astro.config.mjs ← Site URL, base path, locales, sidebar @@ -82,6 +82,7 @@ Every folder's landing page is a `README.md` so it renders directly when someone - `docs//README.md` → `slug: ` (e.g. `slug: app` → `/app/`). - `docs//README.md` → `slug: ` (e.g. `slug: es-es` → `/es-es/`). - `docs///README.md` → `slug: /` (e.g. `slug: es-es/app` → `/es-es/app/`). +- Nested lesson overviews follow the same rule: `docs/vscode/7-foundry-toolkit/README.md` → `slug: vscode/7-foundry-toolkit`; localized copies use `slug: /vscode/7-foundry-toolkit`. Numbered modules live beside the overview and retain nested routes. Links between lessons resolve from the published route, while image paths resolve from the Markdown source file. When you add a new harness or locale landing, name it `README.md` and set its `slug:` to match the folder path. Localized landings must use the locale-prefixed slug, never the English one. diff --git a/README.md b/README.md index f86ad396..9747d7e7 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ For PR/CI rules, see **[CONTRIBUTING.md](./CONTRIBUTING.md)**. - **`docs/`** — **Lesson source (plain Markdown). Edit here.** Browsable directly on github.com, no build required. - `README.md` — Workshop landing page (also the published site's home via `slug: index`). - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / cloud agent / GitHub Copilot app). Each codespace-based harness opens with its own `0-prerequisites.md` setup lesson, and a folder `README.md` (routed via a `slug:` matching the folder) is its landing page. - - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Translated locale trees (currently the app harness). + - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Translated locale trees (app harness and selected VS Code content). - `_images/` — Screenshots and diagrams (shared across all locales). - **`website/`** — Optional Astro + Starlight site that publishes `docs/` to GitHub Pages. Only needed to self-host or preview the rendered site. - `astro.config.mjs` — Site URL, base path, `locales` block, sidebar. diff --git a/docs/es-es/vscode/6-iterating.md b/docs/es-es/vscode/6-iterating.md new file mode 100644 index 00000000..b609bd0a --- /dev/null +++ b/docs/es-es/vscode/6-iterating.md @@ -0,0 +1,96 @@ +--- +title: "Ejercicio 6 - Iterar sobre el trabajo de GitHub Copilot" +authors: + - geektrainer +lastUpdated: 2026-06-30 +next: false +--- + +| [← Lección anterior: Supervisar y gestionar agentes][previous-lesson] | +| :-- | + +## Revisar el trabajo + +A lo largo de esta práctica has trabajado con GitHub Copilot en varias tareas centradas en mejorar la experiencia de usuario. Has utilizado el modo agente para añadir filtros en el cliente y el servidor, el servidor MCP de Playwright para probar manualmente ese trabajo en un navegador y, después, un agente personalizado para implementar funciones de accesibilidad —controles de alto contraste y modo claro—, y has dirigido la sesión sobre la marcha para ampliar el trabajo. Ahora toca publicar ese trabajo local y revisarlo como lo haría tu equipo. + +### Escenario + +Los fundamentos del diseño de software y DevOps no cambian con la incorporación de la IA generativa. Sigue siendo necesario un ciclo de revisión real de todo lo que produce Copilot. Teniendo esto en cuenta, vamos a enviar los cambios de accesibilidad desde el codespace, abrir una solicitud de incorporación de cambios y examinar las diferencias antes de involucrar al resto del equipo. +## Publicar las funciones de accesibilidad + +Los controles de alto contraste y modo claro que has implementado con el agente personalizado de accesibilidad en el [ejercicio 4][exercise-4] y el [ejercicio 5][exercise-5] están en el codespace como cambios confirmados mediante commits. Vamos a enviarlos a una rama y a abrir una solicitud de incorporación de cambios para que el resto del equipo pueda revisarlos. + +1. Vuelve al codespace. +2. Abre la vista **Source Control** en VS Code. +3. Confirma que los cambios de accesibilidad están confirmados mediante commits. Si tienes cambios sin confirmar del ejercicio 5, añádelos al área de preparación y crea un commit ahora con un mensaje descriptivo como `Add high-contrast and light-mode toggles`. +4. Publica la rama seleccionando **Publish Branch** (o utiliza el menú **...** → **Push**). +5. VS Code te ofrecerá abrir la nueva rama en github.com. Acepta la propuesta o ve a tu repositorio manualmente y selecciona **Compare & pull request** en el aviso de la rama. +6. Establece un título claro (por ejemplo, `Add high-contrast and light-mode toggles`) y una descripción breve que resuma qué se ha hecho y por qué. +7. Selecciona **Create pull request**. +8. Una vez abierta la PR, selecciona la pestaña **Files changed** para revisar todo el trabajo. Presta especial atención a: + - Los componentes de la interfaz que permiten alternar entre modos. + - El uso del almacenamiento local para conservar las preferencias del usuario. + - Los cambios de CSS o de estilos para los modos de alto contraste y claro. + - Los atributos de accesibilidad (etiquetas ARIA, navegación por teclado, etc.). + - Cualquier código JavaScript/TypeScript que gestione el cambio de modo. + +9. Vuelve a la pestaña **Conversation**. +10. Si hay flujos de trabajo pendientes de aprobación, selecciona **Approve and run workflows**. + + ![Aprobar y ejecutar flujos de trabajo con Approve and run workflows](../../_images/shared-approve-workflows.png) +11. Espera a que terminen los flujos de trabajo. Si todo va bien, deberían completarse correctamente. + +> [!TIP] +> ¿Quieres una segunda opinión sobre el trabajo de accesibilidad? Menciona a `@copilot` en un comentario de la PR con una petición como «revisa esta PR para detectar otros problemas de WCAG» o «sugiere mejoras en la navegación por teclado». Copilot iniciará una nueva sesión para atender el comentario. + +## Ejercicio opcional: seguir explorando localmente + +Trabajar de forma iterativa con un agente en el IDE es una habilidad, y la única forma de desarrollarla es repetir. Algunas ideas para próximas sesiones que puedes realizar desde VS Code: + +- Añadir un formulario de interés para patrocinadores en la página de detalles del juego. +- Implementar la paginación en la página de la lista de juegos. +- Añadir validación de entradas y gestión de errores a las funciones auxiliares de acceso a datos en `src/lib/`. +- Ampliar el alcance del agente de accesibilidad; por ejemplo, auditar el orden del foco del teclado en todo el sitio. + +## Resumen + +¡Enhorabuena! Has completado el itinerario de VS Code. A lo largo de esta práctica: + +- **Has utilizado Playwright MCP para probar manualmente la funcionalidad.** Has añadido el servidor MCP de Playwright y dejado que Copilot maneje un navegador para verificar la funcionalidad de filtrado antes de abrir una solicitud de incorporación de cambios. +- **Has dirigido el modo agente en cambios coordinados en todas las capas.** Has añadido una funcionalidad de filtrado que ha afectado al cliente, al servidor y a las pruebas en una sola sesión. +- **Has utilizado un agente personalizado.** Has seleccionado el agente personalizado centrado en la accesibilidad en el selector de agentes y observado cómo implementaba el modo de alto contraste en el repositorio. +- **Has gestionado y dirigido una sesión de agente.** Has revisado los cambios propuestos en el propio editor, aceptado los que querías y ampliado la sesión con una petición posterior para el modo claro. +- **Has cerrado el ciclo con una solicitud de incorporación de cambios.** Has publicado el trabajo local y lo has revisado de principio a fin como lo haría tu equipo. + +## Revisión y siguientes pasos + +Aquí termina el itinerario obligatorio de VS Code. Puedes parar aquí con el taller completo. + +Si quieres ampliar tu perspectiva sobre las capacidades de los agentes de Copilot, los otros itinerarios cubren escenarios relacionados a través de distintas interfaces: + +- 💻 **[Itinerario de CLI](../../cli/)**: realiza flujos similares desde el terminal con Copilot CLI: modo plan, habilidades de agente, agentes personalizados y comandos de barra como `/share`, `/context` y `/delegate`. +- ☁️ **[Itinerario del agente en la nube](../../cloud/)**: céntrate en asignar incidencias al agente en la nube, supervisar sesiones a través de la página de agentes e iterar de forma asíncrona sobre solicitudes de incorporación de cambios. + +También puedes seguir ampliando lo que has empezado aquí. [awesome-copilot][awesome-copilot] es una gran fuente de archivos de instrucciones, agentes personalizados y habilidades que puedes adaptar a tus propios proyectos. + +Como ampliación opcional, [Opcional: Incorporar Foundry][exercise-7] utiliza VS Code y Microsoft Foundry Toolkit para preparar un modelo, implementar un Backer Concierge y conectarlo al sitio. + +## Recursos + +- [GitHub Copilot][github-copilot] +- [Copilot Chat en VS Code][copilot-chat-vscode] +- [Uso del modo agente][agent-mode] + +--- + +| [← Lección anterior: Gestionar agentes][previous-lesson] | +|:--| + +[previous-lesson]: ../5-managing-agents/ +[exercise-4]: ../4-custom-agents/ +[exercise-5]: ../5-managing-agents/ +[exercise-7]: ../7-foundry-toolkit/ +[github-copilot]: https://github.com/features/copilot +[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/chat/copilot-chat +[agent-mode]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/es-es/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/es-es/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..0be9b826 --- /dev/null +++ b/docs/es-es/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "Preparar un proyecto y un modelo" +description: "Exporta el catálogo de Tailspin y prueba un modelo implementado frente a los criterios de aceptación de Backer Concierge." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Opcional: Incorporar Foundry][overview] | +|:--| + +Este primer módulo prepara los datos y el modelo de Backer Concierge con VS Code y Microsoft Foundry Toolkit. Trabaja en tu propio repositorio de Tailspin Toys del taller obligatorio. + +## Objetivos + +- Exportar el catálogo e identificar los límites de su información. +- Preparar un proyecto de Foundry y seleccionar un modelo según los criterios de aceptación y la cuota. +- Verificar en Model Playground que las respuestas se fundamentan en los datos antes de escribir el código del agente. + +## Escenario + +Los patrocinadores de Tailspin quieren recomendaciones en las que puedan confiar. Un aficionado a los puzles espera títulos reales y valoraciones precisas, no cifras de financiación inventadas. El asistente necesita unos límites claros del catálogo y la costumbre de hacer una pregunta útil en lugar de adivinar lo que quiere un patrocinador. + +## Preparar el área de trabajo + +El kit de herramientas integra en VS Code la exploración de modelos, la implementación, la ingeniería de prompts, la evaluación y la implementación de agentes. El acceso a Azure y una rama de funcionalidad sin cambios pendientes preparan el trabajo que viene a continuación. + +> [!IMPORTANT] +> Foundry Toolkit y los agentes hospedados están en versión preliminar pública. Este módulo crea recursos de Azure facturables. Confirma los permisos de la suscripción, la región, la cuota y el coste estimado antes de aprobar su creación. Puedes [eliminar los recursos][cleanup] aunque pares antes de crear un agente. + +1. Confirma que tienes acceso a una suscripción de Azure. Las [cuentas gratuitas de Azure con 200 dólares de crédito][azure-free] y [Azure for Students con 100 dólares de crédito][azure-students] son opciones sujetas a sus requisitos de acceso y límites de servicio. +2. En VS Code, selecciona **Extensions** en la barra de actividades, busca **Foundry Toolkit** y selecciona **Install**. Su icono aparece en la barra de actividades. +3. Selecciona el icono **Azure**, selecciona **Sign in to Azure…** y elige la suscripción para el proyecto de Foundry. Una vez autenticado el kit de herramientas, Copilot puede utilizar la [habilidad de Microsoft Foundry][foundry-skill] para preparar recursos mediante una conversación. +4. En el área de trabajo de Tailspin Toys, abre **Terminal** > **New Terminal**, o pulsa Control+\` (Mac) o Ctrl+\` (Windows/Linux). Confirma que el trabajo anterior está confirmado mediante commits y enviado al repositorio remoto y, a continuación, crea la rama de funcionalidad: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. Abre un nuevo chat de Copilot en modo **Agent** y pide: + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. Confirma que Copilot muestra **Add a Backer Concierge assistant for catalog questions**. Los criterios de aceptación exigen respuestas fundamentadas en los datos, ausencia de cifras de financiación inventadas, una pregunta aclaratoria y una interfaz accesible con cobertura de pruebas de extremo a extremo. + +## Generar la exportación del catálogo + +El script de exportación del catálogo proporciona la fuente de datos en la que se fundamenta el agente. + +1. En el terminal del repositorio de Tailspin Toys, ejecuta la migración, carga los datos iniciales y escribe `db/catalog.json`: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. Abre `db/catalog.json` y confirma que contiene veintiún juegos, cada uno con un título, una descripción, una categoría, una editorial y una valoración por estrellas, además de un campo `note` que describe la información que falta. No hay totales de financiación, recuentos de patrocinadores, niveles de aportación ni fechas de lanzamiento; el agente debe respetar ese límite. + +## Configurar un proyecto de Foundry + +El proyecto contiene el modelo y, más adelante, el agente hospedado. Al retomar este módulo, se utiliza el mismo proyecto en lugar de crear otro. + +1. Selecciona **Foundry Toolkit** en la barra de actividades, expande **Help and Feedback** y selecciona **Ask Copilot**. Confirma el modelo que prefieras en la lista desplegable y envía el prompt `/foundrytk-quick-start` generado. + + ![Captura de pantalla que muestra la secuencia de inicio rápido de Foundry Toolkit.](../../../_images/vscode-foundry-setup.png) + +2. En el flujo interactivo, responde a **Where are you starting from?** con **Set up Foundry** y, a continuación, a **What do you have already?** con **I have an Azure subscription or Foundry resources**. +3. Revisa las solicitudes de aprobación de herramientas. Si los comandos propuestos y su alcance son adecuados, selecciona **Allow azmcp …** para esta sesión para reducir las solicitudes de aprobación repetidas. +4. En **Microsoft Foundry: Create Project**, selecciona **Create new resource group** en **Choose a resource group**, introduce `rg-tailspin-toys`, elige una región que ofrezca el modelo que quieres e introduce `tailspin-toys` en **Enter project name**. `East US 2` y `Sweden Central` son opciones iniciales con una amplia disponibilidad de modelos; la disponibilidad y la cuota actuales determinan la elección real. Si retomas el trabajo, selecciona el proyecto existente. +5. Espera la notificación de implementación correcta. En el kit de herramientas, expande **My Resources** y confirma que este proyecto es el predeterminado. + +## Explorar e implementar un modelo + +Aquí importan más el cumplimiento de las reglas y la fundamentación en los datos que elegir el modelo más grande o más reciente. La incidencia aporta criterios concretos para comparar velocidad, fidelidad, disponibilidad regional y cuota. + +1. En Copilot Chat, selecciona **+**, después **GitHub Issues**, y adjunta **Add a Backer Concierge assistant for catalog questions**. Envía: + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. Lee las recomendaciones y elige el modelo que mejor se ajuste a los requisitos y a la cuota disponible. Pide a Copilot que lo implemente: + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. Confirma el proyecto, la implementación, la capacidad y el coste antes de aprobar. Si procede tras revisar el alcance, selecciona **Allow az …** para esta sesión para reducir las solicitudes repetidas. +4. Selecciona **Foundry Toolkit**, expande **My Resources** y selecciona **Models**. Confirma que el modelo implementado aparece en Foundry. La captura de pantalla es un ejemplo; tu región puede ofrecer un modelo diferente. + + ![Captura de pantalla que muestra un ejemplo de implementación de modelo en Foundry Toolkit.](../../../_images/vscode-model-deployed.png) + +## Probar el modelo implementado + +Model Playground no dispone del archivo del catálogo. Un subconjunto reducido de nueve juegos en el prompt del sistema basta para probar si el modelo cumple las reglas de fundamentación. + +1. En **Models**, selecciona el nombre del modelo implementado para abrir **Model Playground** con ese modelo ya seleccionado. Pega el siguiente prompt del sistema: + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. Prueba la fundamentación con `I love puzzle games about tracking down bugs. What should I back?` Debes obtener títulos reales de la lista con información correcta. +3. Prueba los datos ausentes con `How much has Pipeline Conquest raised so far, and how many backers does it have?` Debes obtener una negativa clara porque el catálogo no registra la financiación ni los patrocinadores, seguida de la información que sí conoce. +4. Prueba otro límite con `I need something for four players, about an hour long.` Debes obtener una explicación de que no se dispone del número de jugadores ni de la duración de las partidas, seguida de una pregunta de seguimiento útil. +5. Prueba la presión para salir del catálogo con `Do you have Wingspan? If not, what's the closest thing you've got?` No debe afirmar que Wingspan está en el catálogo ni describirlo a partir de conocimientos externos, y debe reconducir la conversación hacia títulos reales de Tailspin. +6. Prueba las peticiones vagas con `Recommend me something good.` Debes obtener una pregunta aclaratoria breve y ninguna recomendación hasta conocer la categoría o la temática. +7. Prueba la clasificación con `What are your three highest rated games?` Debes obtener Deployment Dynasty y Script Strike con 5.0, seguidos de Code Quest Odyssey con 4.8, en el orden correcto y con las cifras correctas. +8. Si alguna comprobación falla, comenta con Copilot la respuesta incorrecta y la regla, ajusta la configuración o la elección del modelo y repite las comprobaciones antes de continuar. + +## Punto de control al finalizar + +Has preparado el área de trabajo de VS Code, exportado el catálogo, creado un proyecto de Foundry y probado un modelo implementado frente a las reglas de fundamentación del Backer Concierge. El punto de control de este módulo es un modelo que recomienda juegos reales del catálogo sin inventar la información que falta; todavía no hay un agente implementado. + +A continuación, utilizarás el mismo proyecto `tailspin-toys` y la implementación del modelo seleccionada para crear e implementar el agente. Si paras aquí, [elimina los recursos de Azure][cleanup] para evitar costes continuados. + +| [Siguiente módulo: Crear e implementar un agente →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#eliminar-los-recursos +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/es-es/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/es-es/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..6bfc2aeb --- /dev/null +++ b/docs/es-es/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "Crear e implementar un agente" +description: "Genera la estructura de Backer Concierge y depúralo en VS Code; después, impleméntalo y pruébalo como agente hospedado de Foundry." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Módulo anterior: Preparar un proyecto y un modelo][previous-lesson] | +|:--| + +Este módulo utiliza el catálogo y el modelo probado de [Preparar un proyecto y un modelo][previous-lesson]. Microsoft Foundry Toolkit y su agente personalizado **AIAgentExpert** guían la creación local y la implementación hospedada en VS Code. + +## Objetivos + +- Generar la estructura de un agente fundamentado en el catálogo dentro del área de trabajo existente de Tailspin Toys. +- Depurar el comportamiento local con Agent Inspector. +- Implementar en el proyecto de Foundry existente y verificar el agente hospedado. + +## Escenario + +Una recomendación fiable debe seguir siéndolo más allá de una sola conversación. Tailspin Toys necesita que el asistente respete los límites del catálogo cuando los patrocinadores hagan preguntas vagas o insistan en obtener datos de financiación no disponibles. Un asistente hospedado debe comportarse con la misma fiabilidad que uno probado en privado. + +## Retomar el área de trabajo + +El agente utiliza la implementación del modelo existente; no hay que crear un nuevo proyecto de Foundry. + +1. Abre el mismo repositorio de Tailspin Toys en VS Code en `foundry-agent-vscode`. Confirma que existe `db/catalog.json` y que el proyecto `tailspin-toys` y la implementación del modelo probado están visibles en **Foundry Toolkit** > **My Resources**. +2. Confirma que se ha completado el [punto de control anterior][previous-lesson]. Si se eliminaron los recursos, vuelve a completar la preparación del proyecto y del modelo antes de continuar. +3. Instala Azure Developer CLI (`azd`) si todavía no está disponible. La implementación de agentes hospedados la utiliza; elige únicamente el comando correspondiente a tu sistema operativo: + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. Inicia sesión en la suscripción utilizada para el proyecto existente: + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> Los agentes hospedados y Foundry Toolkit están en versión preliminar pública. La implementación crea recursos facturables. Confirma la suscripción, los permisos, la región, la cuota y el coste estimado antes de aprobar comandos. + +## Crear y depurar el agente + +El kit de herramientas genera la estructura de código en el repositorio actual y abre un chat especializado de Copilot. Agent Inspector permite ver las solicitudes locales, los eventos y las llamadas a herramientas antes de la implementación. + +1. Selecciona **Foundry Toolkit**, expande **Developer Tools**, expande **+ Build** y selecciona **+ Create Agent**. En **Create Agent**, selecciona **Code an agent with Copilot**. + + ![Captura de pantalla que muestra la página de creación de agentes.](../../../_images/vscode-create-agent.png) + +2. En el nuevo chat, confirma que se cambia a **AIAgentExpert**. Sustituye el prompt generado por el prompt personalizado y envíalo: + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. Revisa el código generado en `agent/backer-concierge`. Confirma que el catálogo está incluido en el agente que se puede implementar, que las pruebas específicas pasan y que no se incluirán credenciales ni archivos de entorno locales en los commits. +4. Selecciona **Run and Debug** en la barra de actividades e inicia el depurador con F5. Confirma que **Agent Inspector** se carga y se conecta al servidor del agente. +5. Reutiliza los seis prompts de [Probar el modelo implementado][model-tests]. Comprueba las respuestas con el archivo `db/catalog.json` completo, en lugar de suponer que la clasificación del subconjunto de nueve juegos coincide con la del catálogo completo. +6. Alterna entre **Input & Output**, **Events** y **Tools** para inspeccionar los datos de las solicitudes y respuestas, los eventos de sesión y las llamadas a herramientas. Si el comportamiento incumple los criterios de aceptación, pide a Copilot que lo corrija y vuelve a ejecutar las pruebas específicas y las comprobaciones de Inspector antes de implementar. + + ![Captura de pantalla que muestra el flujo de depuración local del agente.](../../../_images/vscode-agent-debug.png) + +## Implementar y probar el agente hospedado + +La transferencia **Go production** empaqueta el agente existente para Foundry. No convierte el posterior proxy del sitio en un servicio público listo para producción. + +1. En el chat de Copilot de creación del agente, selecciona **Go production**, sustituye el prompt predeterminado por el siguiente y envíalo: + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![Captura de pantalla que muestra las opciones de transferencia del agente AIAgentExpert.](../../../_images/vscode-go-production-handoff.png) + +2. Revisa el chat y el terminal para comprobar los parámetros y las solicitudes de aprobación de comandos. Confirma que la implementación tiene como destino el proyecto `tailspin-toys` existente y revisa los recursos facturables antes de aprobar. +3. Si Copilot ofrece un conjunto de evaluaciones, puedes aceptarlo y completarlo como comprobación adicional. +4. Selecciona **Foundry Toolkit**, expande **My Resources** y selecciona **Agents**. En la pestaña **Agents**, cambia a **Hosted Agent**. + + ![Captura de pantalla que muestra el agente hospedado implementado.](../../../_images/vscode-agent-deployed.png) + +5. Selecciona el nombre del agente y confirma que el estado de implementación es **Running**. Cambia a **Playground** y repite las comprobaciones de fundamentación, datos ausentes, peticiones fuera del catálogo, peticiones vagas y clasificación con el catálogo implementado. + + ![Captura de pantalla que muestra una respuesta del agente hospedado implementado.](../../../_images/vscode-agent-response.png) + +6. Si la implementación o las respuestas fallan, inspecciona con Copilot el estado notificado y los registros, corrige el fallo en el proyecto existente y repite las comprobaciones. No continúes con una implementación sin verificar. + +## Punto de control al finalizar + +Has generado la estructura del Backer Concierge, depurado su fundamentación en el catálogo con Agent Inspector, lo has implementado en Foundry mediante el traspaso **Go production** y has vuelto a probar la versión hospedada en el Playground. El punto de control de este módulo es un agente hospedado en ejecución que respeta el catálogo sin inventar la información que falta. + +A continuación, utilizarás el mismo proyecto `tailspin-toys`, la implementación del modelo y el agente hospedado para conectar el agente al sitio. Si paras aquí, [elimina los recursos de Azure][cleanup] para evitar costes continuados. + +| [Siguiente módulo: Conectar el agente al sitio →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#probar-el-modelo-implementado +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#eliminar-los-recursos diff --git a/docs/es-es/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/es-es/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..7a094df0 --- /dev/null +++ b/docs/es-es/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "Conectar el agente al sitio" +description: "Conecta el Backer Concierge hospedado a través de un proxy local y prueba un widget de chat accesible." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← Módulo anterior: Crear e implementar un agente][previous-lesson] | +|:--| + +Este módulo conecta a Tailspin Toys el agente hospedado de [Crear e implementar un agente][previous-lesson]. Copilot Chat en VS Code crea una integración local, no un punto de conexión público de producción. + +## Objetivos + +- Mantener las credenciales y los identificadores de conversación de Foundry detrás de un proxy local del lado del servidor. +- Añadir un widget de chat accesible con continuidad de la conversación. +- Verificar el backend y la experiencia completa antes de eliminar los recursos. + +## Escenario + +Los patrocinadores deben poder pedir consejo al asistente sin salir del catálogo. Una conversación necesita conservar el contexto, funcionar con el teclado y proteger los datos privados de conexión. La confianza depende tanto de las recomendaciones honestas como de una experiencia segura y accesible. + +## Retomar el área de trabajo + +El agente hospedado existente es el destino de la integración. Tailspin Toys es un sitio web estático completamente prerenderizado, por lo que el código del navegador no puede almacenar las credenciales del agente de forma segura. + +1. Abre el mismo repositorio de Tailspin Toys en `foundry-agent-vscode` en VS Code. Confirma que el agente hospedado del punto de control anterior sigue en estado **Running** en el proyecto `tailspin-toys` existente y que el inicio de sesión local de Azure apunta a su suscripción. +2. Abre Copilot Chat en el modo **Agent** normal en lugar de **AIAgentExpert**. Adjunta **Add a Backer Concierge assistant for catalog questions**: selecciona **+**, después **GitHub Issues** y elige la incidencia. + +## Crear y verificar el proxy local + +Un proxy local de Azure Functions en `/api` almacena los datos de conexión y reenvía las solicitudes mientras el sitio se ejecuta localmente. Copilot puede utilizar **Azure skills** para prepararlo y validarlo. + +> [!IMPORTANT] +> Este proxy del taller es solo para desarrollo local. No lo implementes como un punto de conexión público anónimo. La producción requiere autenticación y controles contra el abuso específicos de la aplicación, incluidos límites de frecuencia o cuotas, restricciones de CORS, supervisión y controles de costes. + +1. Pide a Copilot que cree el proxy: + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. Revisa los cambios antes de aceptarlos. Confirma que las credenciales y los identificadores de conversación de Foundry permanecen en el servidor, que los ajustes locales se excluyen del control de versiones, que las solicitudes tienen límites y que las pruebas específicas pasan. +3. Demuestra que el backend funciona antes de crear la interfaz: + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. Comprueba la respuesta del terminal. Debes obtener JSON válido con una propiedad `response` que contenga la respuesta, sin información de precios inventada, credenciales ni identificadores de conversación internos. Si alguna comprobación falla, pide a Copilot que la corrija y repite la prueba del backend. +5. Selecciona **Keep** para conservar los cambios y utiliza **/clear** para empezar de cero con el widget en el mismo repositorio y la misma rama. Conserva la configuración del proxy local y la conexión con el agente hospedado existente. + +## Crear y probar el widget + +La interfaz ya tiene un backend verificado. Las pruebas de extremo a extremo comprueban tanto la usabilidad como los límites de información del catálogo. + +1. Pide a Copilot que añada el widget: + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Captura de pantalla que muestra el widget de chat Backer Concierge en funcionamiento](../../../_images/tailspin-toys-backer-concierge-agent.png) + +2. Mantén la función y el sitio en ejecución y, a continuación, verifica la experiencia completa: + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. Revisa los resultados de las pruebas y los cambios frente a los criterios de aceptación de la incidencia: respuestas fundamentadas en los datos, ausencia de cifras de financiación inventadas, una pregunta aclaratoria, una interfaz accesible y cobertura de pruebas de extremo a extremo. Confirma que se han corregido los fallos y se han vuelto a ejecutar las comprobaciones afectadas. + +## Punto de control al finalizar + +Has creado un proxy local que protege las credenciales, has conectado un widget de chat accesible y has verificado el flujo completo de conversación con el Backer Concierge hospedado. El punto de control de este módulo es una integración del sitio probada localmente que respeta los límites del catálogo y mantiene las credenciales y los identificadores internos de Foundry fuera del navegador. No es una implementación de producción del proxy ni del sitio. + +Cuando termines de experimentar, detén los servicios locales y [elimina los recursos de Azure][cleanup] para evitar costes continuados. Después, vuelve a la [introducción a VS Code][vscode-overview] del taller principal. + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#eliminar-los-recursos +[vscode-overview]: ../../ diff --git a/docs/es-es/vscode/7-foundry-toolkit/README.md b/docs/es-es/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..847d40cc --- /dev/null +++ b/docs/es-es/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: es-es/vscode/7-foundry-toolkit +title: "Opcional: Incorporar Foundry" +description: "Crea un Backer Concierge basado en el catálogo con VS Code y Microsoft Foundry Toolkit en tres módulos específicos." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Lección anterior: Iterar sobre el trabajo de GitHub Copilot][previous-lesson] | +|:--| + +El itinerario obligatorio de VS Code termina con el ejercicio 6. Esta ampliación opcional utiliza GitHub Copilot Chat y Microsoft Foundry Toolkit en VS Code para convertir el catálogo de Tailspin en un Backer Concierge, implementarlo como agente hospedado y conectarlo al sitio a través de un proxy local. + +## Escenario + +Los patrocinadores hacen preguntas que los filtros no pueden responder: ¿qué juego encaja con alguien a quien le encantan los juegos de palabras sobre git, o qué hace que un juego de puzles sea más adecuado que otro? Tailspin Toys necesita un asistente que recomiende títulos reales del catálogo, haga una pregunta aclaratoria cuando sea necesario y se gane la confianza de los usuarios al reconocer que las cifras de financiación u otros datos no están disponibles. + +## Módulos + +Cada módulo termina con un resultado funcional. Se mantienen el mismo repositorio del participante, la misma rama de funcionalidad y el mismo proyecto de Foundry durante los tres módulos; el proyecto no se vuelve a crear entre módulos. + +| Módulo | Resultado al finalizar | +|--------|-----------------------| +| [1. Preparar un proyecto y un modelo][module-1] | Catálogo exportado y modelo implementado probado frente a las reglas de fundamentación | +| [2. Crear e implementar un agente][module-2] | Agente local depurado y agente hospedado probado | +| [3. Conectar el agente al sitio][module-3] | Proxy local y widget accesible probados de extremo a extremo | + +> [!IMPORTANT] +> Microsoft Foundry Toolkit y los agentes hospedados están en versión preliminar pública. Estos módulos crean recursos de Azure facturables, incluidos una implementación de modelo y un agente hospedado. Los permisos de la suscripción, la disponibilidad regional, la cuota y el coste pueden limitar la participación. + +## Antes de empezar + +La ampliación parte de tu repositorio de Tailspin Toys, no del repositorio de documentación del taller. + +1. Confirma que el trabajo obligatorio del taller está guardado, confirmado mediante un commit y enviado al repositorio remoto antes de empezar la funcionalidad opcional. +2. Empieza por [Preparar un proyecto y un modelo][module-1]. Si retomas el trabajo, vuelve a abrir tu repositorio de Tailspin Toys en la rama `foundry-agent-vscode` y confirma que el proyecto `tailspin-toys` y su implementación del modelo siguen existiendo en **Foundry Toolkit** > **My Resources**. +3. Si paras después de cualquier módulo, sigue las indicaciones de [Eliminar los recursos][cleanup], salvo que decidas conservarlos para el siguiente módulo y aceptes los costes continuados. + +## Eliminar los recursos + +Cuando termines de experimentar en cualquier punto de control, elimina los recursos de Azure para evitar costes no deseados. La eliminación afecta a recursos que necesitan los módulos posteriores, por lo que continuar después exige volver a crearlos. + +> [!WARNING] +> Elimina `rg-tailspin-toys` solo si está dedicado a este ejercicio y no contiene recursos que quieras conservar. Al eliminar un grupo de recursos compartido, se eliminarían también recursos ajenos al taller. +> +> Si aprobaste otro nombre de grupo de recursos en el módulo 1, sustituye `rg-tailspin-toys` por ese nombre en todos los comandos siguientes. + +1. Detén en su terminal cualquier sesión de depuración de Agent Inspector, host de Azure Functions o servidor de desarrollo de Astro que hayas iniciado. +2. Si implementaste el agente hospedado en el módulo 2, abre un terminal en el directorio del agente generado que contiene `azure.yaml`, selecciona el mismo entorno de `azd` y ejecuta: + + ```bash + azd down --purge + ``` + +3. Comprueba la suscripción seleccionada y si el grupo de recursos del taller sigue existiendo: + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + Si el comando devuelve `false`, la eliminación ha terminado. Si devuelve `true`, inspecciona los recursos del grupo: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Verifica que todos los recursos restantes pertenecen a este ejercicio. Si paraste después del módulo 1, el proyecto y el modelo de Foundry todavía deben eliminarse aunque no hayas implementado un servicio de `azd`. + +4. Si el grupo de recursos dedicado al taller sigue existiendo y solo contiene recursos que quieres eliminar, ejecuta: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Como `--no-wait` devuelve el control antes de que termine la eliminación, vuelve a ejecutar el siguiente comando hasta que devuelva `false`: + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## Recursos + +- [Foundry Toolkit para Visual Studio Code][foundry-toolkit] +- [Información general de la extensión de agentes de Microsoft Foundry][foundry-extension] + +| [Siguiente módulo: Preparar un proyecto y un modelo →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #eliminar-los-recursos +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/es-es/vscode/README.md b/docs/es-es/vscode/README.md new file mode 100644 index 00000000..15d8feb0 --- /dev/null +++ b/docs/es-es/vscode/README.md @@ -0,0 +1,48 @@ +--- +slug: es-es/vscode +title: "VS Code" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +**[GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)** en VS Code lleva GitHub Copilot al editor de código que ya utilizas. Al trabajar en Visual Studio Code (y GitHub Codespaces), dirigirás Copilot Chat en modo agente, conectarás herramientas externas mediante MCP y utilizarás agentes personalizados, todo ello sin salir del IDE, donde Copilot puede ver todos tus archivos, el terminal y los problemas. + +Empezarás por añadir instrucciones personalizadas y observar cómo las sigue Copilot; después, utilizarás el modo agente para crear una funcionalidad de filtrado que abarque la interfaz, la capa de datos y las pruebas. A continuación, conectarás el servidor MCP de Playwright y dejarás que Copilot maneje un navegador para probar la funcionalidad antes de abrir una solicitud de incorporación de cambios. Por último, revisarás y utilizarás un agente personalizado para trabajar en la accesibilidad y, después, supervisarás, dirigirás e iterarás sobre los cambios de Copilot, todo ello sin salir del editor. + +## Ejercicios + +| Ejercicio | Tema | Descripción | +|----------|-------|-------------| +| [0. Requisitos previos][ex0] | Configuración | Crea tu repositorio y tu codespace | +| [1. Instrucciones personalizadas][ex1] | Contexto | Añade y verifica instrucciones personalizadas en VS Code | +| [2. Modo agente][ex2] | Generación de código | Crea una funcionalidad de filtrado con el modo agente | +| [3. MCP con Playwright][ex3] | Herramientas externas | Prueba la funcionalidad en un navegador con el servidor MCP de Playwright | +| [4. Agentes personalizados][ex4] | Agentes especializados | Revisa y utiliza agentes personalizados | +| [5. Gestión de agentes][ex5] | Supervisión | Supervisa y dirige sesiones de agentes | +| [6. Iteración][ex6] | Revisión | Revisa el trabajo de Copilot localmente y elige los siguientes pasos | +| [Opcional: Incorporar Foundry][foundry-toolkit] | Agentes de IA | Prepara un modelo, implementa un agente y conéctalo al sitio en tres módulos con VS Code y Foundry Toolkit | + +## Requisitos previos + +Antes de asistir a este taller, asegúrate de tener: + +- [ ] Una cuenta de GitHub con un plan activo **Copilot Student, Pro, Pro+, Business o Enterprise** +- [ ] Acceso a GitHub Codespaces + +> [!TIP] +> ¿No tienes un plan de pago? Los estudiantes verificados pueden obtener GitHub Copilot gratis a través de [GitHub Education][callout-student-plan-education]. El plan **Copilot Student** incluye las funcionalidades de agente, MCP, revisión de código y Copilot CLI que utiliza este taller, por lo que puedes completar todos los itinerarios con él. + +[callout-student-plan-education]: https://github.com/education/students +## Empezar + +**[Empieza por el ejercicio 0: Requisitos previos →][ex0]** + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-agent-mode/ +[ex3]: 3-mcp/ +[ex4]: 4-custom-agents/ +[ex5]: 5-managing-agents/ +[ex6]: 6-iterating/ +[foundry-toolkit]: 7-foundry-toolkit/ diff --git a/docs/ja-jp/vscode/6-iterating.md b/docs/ja-jp/vscode/6-iterating.md new file mode 100644 index 00000000..9de22894 --- /dev/null +++ b/docs/ja-jp/vscode/6-iterating.md @@ -0,0 +1,96 @@ +--- +title: "演習 6 - GitHub Copilot の作業を反復して改善する" +authors: + - geektrainer +lastUpdated: 2026-06-30 +next: false +--- + +| [← 前のレッスン: エージェントの監視と管理][previous-lesson] | +| :-- | + +## 作業をレビューする + +このラボでは、ユーザー体験を改善するいくつかのタスクに GitHub Copilot と取り組んできました。エージェントモードでクライアントとサーバーの両方にフィルターを追加し、Playwright MCP サーバーでその作業をブラウザーから手動でテストしました。その後、カスタムエージェントを使って、高コントラストモードとライトモードの切り替えというアクセシビリティ機能を実装し、進行中のセッションを方向付けして作業を広げました。次は、そのローカルの作業を公開し、チームと同じ方法でレビューします。 + +### シナリオ + +生成 AI が加わっても、ソフトウェア設計と DevOps の基本は変わりません。Copilot が生成するものには、引き続きしっかりとしたレビューのサイクルが必要です。このことを踏まえて、codespace からアクセシビリティの変更をプッシュし、プルリクエストを作成して、チームのほかのメンバーに参加してもらう前に差分を確認しましょう。 +## アクセシビリティ機能を公開する + +[演習 4][exercise-4]と[演習 5][exercise-5]でアクセシビリティ用カスタムエージェントと実装した、高コントラストモードとライトモードの切り替えは、コミット済みの変更として codespace にあります。チームのほかのメンバーがレビューできるように、ブランチにプッシュしてプルリクエストを作成します。 + +1. codespace に戻ります。 +2. VS Code の **Source Control** ビューを開きます。 +3. アクセシビリティの変更がコミット済みであることを確認します。演習 5 の未コミットの変更がある場合は、今ステージして、`Add high-contrast and light-mode toggles` などの内容が分かるメッセージでコミットします。 +4. **Publish Branch** を選択してブランチを公開します (または **...** メニュー → **Push** を使います)。 +5. VS Code から新しいブランチを github.com で開くように促されます。そのプロンプトを受け入れるか、手動でリポジトリに移動し、ブランチのバナーで **Compare & pull request** を選択します。 +6. 分かりやすいタイトル (例: `Add high-contrast and light-mode toggles`) と、何をなぜ行ったかをまとめた短い説明を設定します。 +7. **Create pull request** を選択します。 +8. PR が作成されたら、**Files changed** タブを選択し、作業全体をレビューします。特に次の点に注意します。 + - モードを切り替えるためのトグル UI コンポーネント。 + - ユーザー設定を永続化するためのローカルストレージの使用。 + - 高コントラストモードとライトモード用の CSS またはスタイルの変更。 + - アクセシビリティ属性 (ARIA ラベル、キーボードナビゲーションなど)。 + - モード切り替えを管理する JavaScript/TypeScript コード。 + +9. **Conversation** タブに戻ります。 +10. 承認待ちのワークフローがある場合は、**Approve and run workflows** を選択します。 + + ![ワークフローの承認と実行を行う Approve and run workflows](../../_images/shared-approve-workflows.png) +11. ワークフローの完了を待ちます。問題がなければ、成功したことを確認できるはずです。 + +> [!TIP] +> アクセシビリティの作業について別の意見が必要ですか。PR コメントで `@copilot` をタグ付けし、「この PR にほかの WCAG の問題がないかレビューしてください」や「キーボードナビゲーションの改善を提案してください」などと依頼します。Copilot は、そのコメントに対応する新しいセッションを開始します。 + +## 省略可能な演習 - ローカルでさらに試す + +IDE 内でエージェントと反復的に作業することもスキルの 1 つであり、身に付けるには繰り返しが欠かせません。VS Code から実行できる追加セッションのアイデアを紹介します。 + +- ゲーム詳細ページに、支援に関心のある人向けのフォームを追加します。 +- ゲーム一覧ページにページネーションを実装します。 +- `src/lib/` のデータアクセスヘルパーに入力検証とエラー処理を追加します。 +- アクセシビリティエージェントの対象範囲を広げます。たとえば、サイト全体のキーボードフォーカスの順序を監査します。 + +## まとめ + +おめでとうございます。VS Code コースを完了しました。このラボでは、次のことに取り組みました。 + +- **Playwright MCP を使って機能を手動でテストしました。** Playwright MCP サーバーを追加し、プルリクエストを作成する前に Copilot にブラウザーを操作させてフィルター機能を検証しました。 +- **エージェントモードでスタック全体にまたがる変更を連携して進めました。** 1 回のセッションで、クライアント、サーバー、テストにまたがるフィルター機能を追加しました。 +- **カスタムエージェントを使いました。** エージェント選択メニューからアクセシビリティに特化したカスタムエージェントを選び、リポジトリに高コントラストモードを実装する様子を確認しました。 +- **エージェントのセッションを管理し、方向付けしました。** 提案された変更をインラインでレビューし、必要なものを受け入れ、ライトモードの追加依頼でセッションを広げました。 +- **プルリクエストで一連の作業を締めくくりました。** ローカルの作業を公開し、チームと同じ方法で全体をレビューしました。 + +## 振り返りと次のステップ + +これで必須の VS Code コースは終了です。ここでワークショップを完了して構いません。 + +Copilot のエージェント機能について視野を広げたい場合は、ほかのコースで、異なる操作環境から関連するシナリオに取り組めます。 + +- 💻 **[CLI コース](../../cli/)** — Copilot CLI を使ってターミナルから同様の流れに取り組みます。プランモード、エージェントスキル、カスタムエージェント、`/share`、`/context`、`/delegate` などのスラッシュコマンドを扱います。 +- ☁️ **[クラウドエージェントコース](../../cloud/)** — クラウドエージェントへの Issue の割り当て、エージェントページでのセッションの監視、プルリクエストでの非同期の反復作業に重点を置きます。 + +ここで始めた作業をさらに発展させることもできます。[awesome-copilot][awesome-copilot] には、自分のプロジェクトに応用できる指示ファイル、カスタムエージェント、スキルが豊富にあります。 + +省略可能な拡張演習である[省略可能: Foundry を組み込む][exercise-7]では、VS Code と Microsoft Foundry Toolkit を使ってモデルを準備し、Backer Concierge をデプロイしてサイトに接続します。 + +## リソース + +- [GitHub Copilot][github-copilot] +- [VS Code の Copilot Chat][copilot-chat-vscode] +- [エージェントモードの使用][agent-mode] + +--- + +| [← 前のレッスン: エージェントの管理][previous-lesson] | +|:--| + +[previous-lesson]: ../5-managing-agents/ +[exercise-4]: ../4-custom-agents/ +[exercise-5]: ../5-managing-agents/ +[exercise-7]: ../7-foundry-toolkit/ +[github-copilot]: https://github.com/features/copilot +[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/chat/copilot-chat +[agent-mode]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/ja-jp/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/ja-jp/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..c566b01f --- /dev/null +++ b/docs/ja-jp/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "プロジェクトとモデルを準備する" +description: "Tailspin のカタログをエクスポートし、デプロイ済みモデルが Backer Concierge の受け入れ基準を満たすかテストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 省略可能: Foundry を組み込む][overview] | +|:--| + +この最初のモジュールでは、VS Code と Microsoft Foundry Toolkit を使って Backer Concierge のデータとモデルを準備します。必須演習で使った自分の Tailspin Toys リポジトリで作業します。 + +## 目標 + +- カタログをエクスポートし、含まれる情報と含まれない情報を把握します。 +- Foundry プロジェクトを準備し、受け入れ基準とクォータに照らしてモデルを選びます。 +- エージェントのコードを書く前に、Model Playground で根拠に基づいた回答ができるかを確認します。 + +## シナリオ + +Tailspin の支援者は、信頼できるおすすめを求めています。パズル好きの人が期待するのは、実在するタイトルと正確な評価であり、でっち上げの資金調達総額ではありません。コンシェルジュには、カタログの情報範囲を明確に守り、支援者の希望を推測するのではなく、役に立つ質問を 1 つする姿勢が必要です。 + +## ワークスペースを準備する + +このツールキットでは、モデルの探索、デプロイ、プロンプトエンジニアリング、評価、エージェントのデプロイを VS Code で実行できます。Azure へのアクセスと未コミットの変更がない機能ブランチを用意し、後の作業に備えます。 + +> [!IMPORTANT] +> Foundry Toolkit とホスト型エージェントはパブリックプレビューです。このモジュールでは課金対象の Azure リソースを作成します。作成を承認する前に、サブスクリプションの権限、リージョン、クォータ、見積もり費用を確認します。エージェントを構築する前に終了する場合も、[クリーンアップ][cleanup]できます。 + +1. Azure サブスクリプションにアクセスできることを確認します。[200 ドルのクレジット付き無料 Azure アカウント][azure-free]と [100 ドルのクレジット付き Azure for Students][azure-students]も選択肢ですが、それぞれの利用資格とサービス制限が適用されます。 +2. VS Code のアクティビティバーで **Extensions** を選択し、**Foundry Toolkit** を検索して **Install** を選択します。アクティビティバーにアイコンが表示されます。 +3. **Azure** アイコンを選択し、**Sign in to Azure…** を選択して、Foundry プロジェクト用のサブスクリプションを選びます。ツールキットで認証すると、Copilot は [Microsoft Foundry Skill][foundry-skill] を使って対話形式でリソースを準備できます。 +4. Tailspin Toys ワークスペースで **Terminal** > **New Terminal** を開くか、Control+\` (Mac)、または Ctrl+\` (Windows/Linux) を押します。これまでの作業をコミットしてプッシュ済みであることを確認し、機能ブランチを作成します。 + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. **Agent** モードで新しい Copilot Chat を開き、次のように依頼します。 + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. Copilot が **Add a Backer Concierge assistant for catalog questions** を提示することを確認します。受け入れ基準では、根拠に基づく回答、資金調達額をでっち上げないこと、確認の質問を 1 つすること、アクセシビリティに対応した UI、エンドツーエンドのテストカバレッジが求められています。 + +## カタログをエクスポートする + +カタログのエクスポートスクリプトは、エージェントが回答の根拠とするデータソースを用意します。 + +1. Tailspin Toys リポジトリのターミナルで、マイグレーション、初期データの投入、`db/catalog.json` の書き出しを実行します。 + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. `db/catalog.json` を開き、21 個のゲームが含まれ、それぞれにタイトル、説明、カテゴリ、パブリッシャー、星評価があり、さらに不足している情報を説明する `note` フィールドがあることを確認します。資金調達総額、支援者数、支援プラン、発売日は含まれていません。エージェントはこの情報範囲を守る必要があります。 + +## Foundry プロジェクトをセットアップする + +プロジェクトにはモデルを格納し、後でホスト型エージェントも格納します。このモジュールを再開する場合は、別のプロジェクトを作らず、同じプロジェクトを使います。 + +1. アクティビティバーで **Foundry Toolkit** を選択し、**Help and Feedback** を展開して **Ask Copilot** を選択します。ドロップダウンで使いたいモデルを確認し、生成された `/foundrytk-quick-start` プロンプトを送信します。 + + ![Foundry Toolkit のクイックスタートの流れを示すスクリーンショット。](../../../_images/vscode-foundry-setup.png) + +2. 対話式ワークフローで、**Where are you starting from?** には **Set up Foundry**、続く **What do you have already?** には **I have an Azure subscription or Foundry resources** と回答します。 +3. ツールの承認内容を確認します。提案されたコマンドとその対象範囲が適切であれば、このセッションで **Allow azmcp …** を選択し、繰り返し表示される承認プロンプトを減らします。 +4. **Microsoft Foundry: Create Project** の **Choose a resource group** で **Create new resource group** を選択し、`rg-tailspin-toys` と入力します。使う予定のモデルが提供されているリージョンを選び、**Enter project name** に `tailspin-toys` と入力します。`East US 2` と `Sweden Central` は、幅広いモデルが提供されている候補です。実際の選択は、その時点の提供状況とクォータで決まります。再開する場合は、代わりに既存のプロジェクトを選択します。 +5. デプロイ成功の通知を待ちます。ツールキットで **My Resources** を展開し、このプロジェクトが既定になっていることを確認します。 + +## モデルを探してデプロイする + +ここでは、最大または最新のモデルを選ぶことよりも、ルールに従い、根拠に基づいて回答することが重要です。Issue には、速度、指示への忠実さ、リージョンでの提供状況、クォータを比較するための具体的な基準が示されています。 + +1. Copilot Chat で **+**、**GitHub Issues** の順に選択し、**Add a Backer Concierge assistant for catalog questions** を添付します。次のプロンプトを送信します。 + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. 推奨内容を読み、要件と利用可能なクォータに最も合うモデルを選びます。Copilot にデプロイを依頼します。 + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. 承認する前に、プロジェクト、デプロイ、容量、費用を確認します。対象範囲を確認して適切であれば、このセッションで **Allow az …** を選択し、繰り返し表示されるプロンプトを減らします。 +4. **Foundry Toolkit** を選択し、**My Resources** を展開して **Models** を選択します。デプロイ済みモデルが Foundry の下に表示されることを確認します。スクリーンショットは一例です。リージョンによっては別のモデルが提供されます。 + + ![Foundry Toolkit でのモデルデプロイの例を示すスクリーンショット。](../../../_images/vscode-model-deployed.png) + +## デプロイ済みモデルをテストする + +Model Playground にはカタログファイルがありません。システムプロンプトに 9 個のゲームだけを抜き出して含めれば、モデルが根拠に基づいて回答するためのルールに従うかをテストできます。 + +1. **Models** からデプロイ済みモデルの名前を選択し、そのモデルがあらかじめ設定された **Model Playground** を開きます。次のシステムプロンプトを貼り付けます。 + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. `I love puzzle games about tracking down bugs. What should I back?` で、根拠に基づく回答をテストします。リストに実在するタイトルを、正しい情報で紹介することが期待されます。 +3. `How much has Pipeline Conquest raised so far, and how many backers does it have?` で、不足しているデータへの対応をテストします。カタログでは資金調達や支援者を管理していないため、明確に回答を断り、その後で分かっている情報を伝えることが期待されます。 +4. `I need something for four players, about an hour long.` で、別の情報範囲もテストします。プレイヤー数とプレイ時間の情報がないと説明し、次の提案につながる質問を 1 つすることが期待されます。 +5. `Do you have Wingspan? If not, what's the closest thing you've got?` で、カタログ外の情報を求められた場合の対応をテストします。Wingspan がカタログにあるとは主張せず、外部の知識による説明もせず、実在する Tailspin のタイトルの紹介に切り替えることが期待されます。 +6. `Recommend me something good.` で、曖昧な依頼への対応をテストします。短い確認の質問を 1 つし、カテゴリまたはテーマが分かるまでおすすめを出さないことが期待されます。 +7. `What are your three highest rated games?` で、順位付けをテストします。Deployment Dynasty と Script Strike が 5.0、続いて Code Quest Odyssey が 4.8 と、正しい順序と数値で回答することが期待されます。 +8. いずれかの確認に失敗した場合は、問題のある回答とルールについて Copilot と相談し、設定またはモデルの選択を調整して、先に進む前に確認を繰り返します。 + +## 完了時のチェックポイント + +VS Code ワークスペースを準備し、カタログをエクスポートし、Foundry プロジェクトを作成して、デプロイしたモデルが Backer Concierge の根拠に基づく回答のルールに従うことを確認しました。このモジュールのチェックポイントは、情報がない場合に作り話をせず、カタログに実在するゲームを勧めるモデルです。エージェントのデプロイはまだ行っていません。 + +次は、同じ `tailspin-toys` プロジェクトと選択したモデルのデプロイを使って、エージェントを構築してデプロイします。ここで終了する場合は、継続的な費用が発生しないように [Azure リソースをクリーンアップします][cleanup]。 + +| [次のモジュール: エージェントを構築してデプロイする →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#リソースをクリーンアップする +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/ja-jp/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/ja-jp/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..772c3aad --- /dev/null +++ b/docs/ja-jp/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "エージェントを構築してデプロイする" +description: "VS Code で Backer Concierge のひな形を作成してデバッグし、Foundry ホスト型エージェントとしてデプロイしてテストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 前のモジュール: プロジェクトとモデルを準備する][previous-lesson] | +|:--| + +このモジュールでは、[プロジェクトとモデルを準備する][previous-lesson]で用意したカタログとテスト済みモデルを使います。Microsoft Foundry Toolkit とそのカスタムエージェント **AIAgentExpert** が、VS Code でのローカル構築とホスト環境へのデプロイを案内します。 + +## 目標 + +- 既存の Tailspin Toys ワークスペースに、カタログを根拠として回答するエージェントのひな形を作成します。 +- Agent Inspector でローカルの動作をデバッグします。 +- 既存の Foundry プロジェクトにデプロイし、ホスト型エージェントを検証します。 + +## シナリオ + +信頼できるおすすめを提供するには、1 回の会話でうまくいくだけでは不十分です。Tailspin Toys のコンシェルジュには、支援者が曖昧な質問をしたり、手元にない資金調達の詳細をしつこく求めたりしても、カタログの情報範囲を守ることが求められます。ホスト環境のコンシェルジュにも、非公開でテストしたときと同じ信頼性が必要です。 + +## ワークスペースで作業を再開する + +エージェントは既存のモデルデプロイを使います。新しい Foundry プロジェクトを作成する必要はありません。 + +1. VS Code で同じ Tailspin Toys リポジトリを開き、`foundry-agent-vscode` ブランチを使います。`db/catalog.json` が存在し、**Foundry Toolkit** > **My Resources** に `tailspin-toys` プロジェクトとテスト済みモデルのデプロイが表示されることを確認します。 +2. [前のチェックポイント][previous-lesson]が完了していることを確認します。リソースをクリーンアップした場合は、先に進む前にプロジェクトとモデルの準備をもう一度完了します。 +3. Azure Developer CLI (`azd`) がまだ利用できない場合はインストールします。ホスト型エージェントのデプロイに使います。自分の OS に対応するコマンドだけを選びます。 + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. 既存のプロジェクトで使っているサブスクリプションにサインインします。 + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> ホスト型エージェントと Foundry Toolkit はパブリックプレビューです。デプロイすると課金対象のリソースが作成されます。コマンドを承認する前に、サブスクリプション、権限、リージョン、クォータ、見積もり費用を確認します。 + +## エージェントを作成してデバッグする + +ツールキットは現在のリポジトリにコードのひな形を作成し、専用の Copilot Chat を開きます。Agent Inspector では、デプロイ前にローカルのリクエスト、イベント、ツール呼び出しを確認できます。 + +1. **Foundry Toolkit** を選択し、**Developer Tools**、**+ Build** の順に展開して **+ Create Agent** を選択します。**Create Agent** で **Code an agent with Copilot** を選択します。 + + ![エージェント作成ページを示すスクリーンショット。](../../../_images/vscode-create-agent.png) + +2. 新しいチャットで **AIAgentExpert** に切り替わっていることを確認します。生成されたプロンプトを次のカスタマイズ済みプロンプトに置き換え、送信します。 + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. `agent/backer-concierge` に生成されたコードをレビューします。デプロイ可能なエージェントにカタログが含まれ、対象を絞ったテストに合格し、資格情報やローカル環境ファイルがコミットされないことを確認します。 +4. アクティビティバーで **Run and Debug** を選択し、F5 でデバッガーを起動します。**Agent Inspector** が読み込まれ、エージェントサーバーに接続することを確認します。 +5. [デプロイ済みモデルをテストする][model-tests]の 6 つのプロンプトをすべて再利用します。9 個のゲームの抜粋での順位がカタログ全体の順位だと思い込まず、`db/catalog.json` 全体に照らして回答を確認します。 +6. **Input & Output**、**Events**、**Tools** を切り替え、ペイロード、セッションイベント、ツール呼び出しを調べます。動作が受け入れ基準に反する場合は、Copilot に修正を依頼し、デプロイ前に対象を絞ったテストと Inspector での確認を再実行します。 + + ![ローカルでのエージェントのデバッグ手順を示すスクリーンショット。](../../../_images/vscode-agent-debug.png) + +## ホスト型エージェントをデプロイしてテストする + +**Go production** のハンドオフでは、既存のエージェントを Foundry 用にパッケージ化します。これによって、後で作成するサイトのプロキシが本番対応の公開サービスになるわけではありません。 + +1. エージェント作成用の Copilot Chat で **Go production** を選択し、既定のプロンプトを次の内容に置き換えて送信します。 + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![AIAgentExpert エージェントのハンドオフの選択肢を示すスクリーンショット。](../../../_images/vscode-go-production-handoff.png) + +2. チャットとターミナルでパラメーターとコマンドの承認内容を確認します。デプロイ先が既存の `tailspin-toys` プロジェクトであることを確認し、承認する前に課金対象のリソースを確認します。 +3. Copilot が評価スイートを提案した場合は、必要に応じて受け入れ、追加の確認として実行します。 +4. **Foundry Toolkit** を選択し、**My Resources** を展開して **Agents** を選択します。**Agents** タブで **Hosted Agent** に切り替えます。 + + ![デプロイ済みのホスト型エージェントを示すスクリーンショット。](../../../_images/vscode-agent-deployed.png) + +5. エージェント名を選択し、デプロイ状態が **Running** であることを確認します。**Playground** に切り替え、デプロイしたカタログに照らして、根拠に基づく回答、不足しているデータ、カタログ外の情報、曖昧な依頼、順位付けの確認を繰り返します。 + + ![デプロイ済みのホスト型エージェントからの回答を示すスクリーンショット。](../../../_images/vscode-agent-response.png) + +6. デプロイや回答に問題がある場合は、Copilot とともに報告された状態とログを調べ、既存のプロジェクト内で問題を修正して、確認を繰り返します。デプロイの検証が済むまで先に進まないでください。 + +## 完了時のチェックポイント + +Backer Concierge のひな形を生成し、Agent Inspector でカタログに基づく回答をデバッグし、**Go production** の受け渡しで Foundry にデプロイして、ホスト型バージョンを Playground で再テストしました。このモジュールのチェックポイントは、情報がない場合に作り話をせず、カタログの範囲を守って稼働するホスト型エージェントです。 + +次は、同じ `tailspin-toys` プロジェクト、モデルのデプロイ、ホスト型エージェントを使って、エージェントをサイトに接続します。ここで終了する場合は、継続的な費用が発生しないように [Azure リソースをクリーンアップします][cleanup]。 + +| [次のモジュール: エージェントをサイトに接続する →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#デプロイ済みモデルをテストする +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#リソースをクリーンアップする diff --git a/docs/ja-jp/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/ja-jp/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..479a2bc0 --- /dev/null +++ b/docs/ja-jp/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "エージェントをサイトに接続する" +description: "ホスト環境の Backer Concierge をローカルプロキシ経由で接続し、アクセシビリティに対応したチャットウィジェットをテストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← 前のモジュール: エージェントを構築してデプロイする][previous-lesson] | +|:--| + +このモジュールでは、[エージェントを構築してデプロイする][previous-lesson]で用意したホスト型エージェントを Tailspin Toys に接続します。VS Code の Copilot Chat で作成するのはローカルの統合であり、公開された本番エンドポイントではありません。 + +## 目標 + +- 資格情報と Foundry の会話識別子を、ローカルのサーバー側プロキシの背後に保持します。 +- 会話の継続性を備え、アクセシビリティに対応したチャットウィジェットを追加します。 +- リソースをクリーンアップする前に、バックエンドと体験全体を検証します。 + +## シナリオ + +支援者は、カタログを離れずにコンシェルジュに相談できることを期待しています。会話では文脈を保持し、キーボードで操作でき、非公開の接続情報を保護する必要があります。信頼を得るには、誠実なおすすめだけでなく、安全でアクセシビリティに対応した体験も欠かせません。 + +## ワークスペースで作業を再開する + +統合の接続先は既存のホスト型エージェントです。Tailspin Toys は完全に事前レンダリングされた静的 Web サイトなので、ブラウザーのコードにエージェントの資格情報を安全に保持することはできません。 + +1. VS Code で同じ Tailspin Toys リポジトリを開き、`foundry-agent-vscode` ブランチを使います。前のチェックポイントで用意したホスト型エージェントが、既存の `tailspin-toys` プロジェクトで引き続き **Running** であることと、ローカルの Azure サインインがそのサブスクリプションを対象としていることを確認します。 +2. **AIAgentExpert** ではなく、通常の **Agent** モードで Copilot Chat を開きます。**+**、**GitHub Issues** の順に選択し、Issue **Add a Backer Concierge assistant for catalog questions** を選んで添付します。 + +## ローカルプロキシを構築して検証する + +`/api` 内のローカル Azure Functions プロキシが接続情報を保持し、サイトをローカルで実行している間のリクエストを転送します。Copilot は **Azure skills** を使って準備と検証を進められます。 + +> [!IMPORTANT] +> このワークショップのプロキシはローカル開発専用です。匿名でアクセスできる公開エンドポイントとしてデプロイしないでください。本番環境では、アプリケーション固有の認証と不正利用対策が必要です。これには、レート制限やクォータ、CORS 制限、監視、コスト管理が含まれます。 + +1. Copilot にプロキシの作成を依頼します。 + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. 受け入れる前に変更をレビューします。資格情報と Foundry の会話識別子がサーバーにとどまり、ローカル設定がバージョン管理から除外され、リクエストに制限が設けられ、対象を絞ったテストに合格していることを確認します。 +3. UI を構築する前に、バックエンドが動作することを確かめます。 + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. ターミナルの応答を確認します。回答を含む `response` プロパティを持つ有効な JSON であり、価格情報のでっち上げがなく、資格情報や内部の会話識別子を含まないことが期待されます。確認に失敗した場合は、Copilot に修正を依頼し、バックエンドのテストを繰り返します。 +5. **Keep** で変更を保持し、**/clear** を使って、同じリポジトリとブランチでウィジェット用の新しいチャットを始めます。ローカルプロキシの設定と既存のホスト型エージェントへの接続は維持します。 + +## ウィジェットを構築してテストする + +これで UI の接続先となるバックエンドの検証が済みました。エンドツーエンドテストでは、使いやすさとカタログの情報範囲の両方を確認します。 + +1. Copilot にウィジェットの追加を依頼します。 + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Backer Concierge のチャットウィジェットの動作を示すスクリーンショット](../../../_images/tailspin-toys-backer-concierge-agent.png) + +2. Function とサイトを実行したまま、体験全体を検証します。 + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. テスト結果と変更を Issue の受け入れ基準に照らしてレビューします。基準は、根拠に基づく回答、資金調達額をでっち上げないこと、確認の質問を 1 つすること、アクセシビリティに対応した UI、エンドツーエンドのテストカバレッジです。問題が修正され、影響する確認が再実行されたことを確認します。 + +## 完了時のチェックポイント + +資格情報を安全に扱うローカルプロキシを構築し、アクセシビリティに対応したチャットウィジェットを接続して、ホスト型 Backer Concierge との会話フロー全体を検証しました。このモジュールのチェックポイントは、カタログの範囲を守り、資格情報と Foundry の内部識別子をブラウザーに渡さない、ローカルでテスト済みのサイト統合です。プロキシやサイトの本番環境へのデプロイではありません。 + +試すのを終えたら、ローカルのサービスを停止し、継続的な費用が発生しないように [Azure リソースをクリーンアップします][cleanup]。その後、メインのワークショップの [VS Code の概要][vscode-overview]に戻ります。 + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#リソースをクリーンアップする +[vscode-overview]: ../../ diff --git a/docs/ja-jp/vscode/7-foundry-toolkit/README.md b/docs/ja-jp/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..78134ca4 --- /dev/null +++ b/docs/ja-jp/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: ja-jp/vscode/7-foundry-toolkit +title: "省略可能: Foundry を組み込む" +description: "VS Code と Microsoft Foundry Toolkit を使い、根拠に基づいて回答する Backer Concierge を 3 つのモジュールで構築します。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 前のレッスン: GitHub Copilot の作業を反復して改善する][previous-lesson] | +|:--| + +必須の VS Code コースは演習 6 で完了です。この省略可能な拡張演習では、VS Code の GitHub Copilot Chat と Microsoft Foundry Toolkit を使って Tailspin のカタログを Backer Concierge に活用し、ホスト型エージェントとしてデプロイして、ローカルプロキシ経由でサイトに接続します。 + +## シナリオ + +支援者からは、フィルターでは答えられない質問が寄せられます。git の言葉遊びが好きな人に合うゲームはどれか、あるパズルゲームが別のゲームより自分に向いている理由は何か、といった質問です。Tailspin Toys には、カタログに実在するタイトルを勧め、必要に応じて確認の質問をし、資金調達額などの情報がないときはそのことを率直に伝えて信頼を得るコンシェルジュが必要です。 + +## モジュール + +各モジュールは、動作を確認できるチェックポイントで終わります。3 つのモジュールを通して、同じ受講者用リポジトリ、機能ブランチ、Foundry プロジェクトを使います。モジュールの間でプロジェクトを作り直すことはありません。 + +| モジュール | 完了時のチェックポイント | +|--------|-----------------------| +| [1. プロジェクトとモデルを準備する][module-1] | カタログをエクスポートし、デプロイ済みモデルが根拠に基づいて回答するためのルールに従うことを検証済み | +| [2. エージェントを構築してデプロイする][module-2] | ローカルエージェントをデバッグし、ホスト型エージェントをテスト済み | +| [3. エージェントをサイトに接続する][module-3] | ローカルプロキシとアクセシビリティに対応したウィジェットをエンドツーエンドでテスト済み | + +> [!IMPORTANT] +> Microsoft Foundry Toolkit とホスト型エージェントはパブリックプレビューです。これらのモジュールでは、モデルのデプロイやホスト型エージェントなど、課金対象の Azure リソースを作成します。サブスクリプションの権限、リージョンでの提供状況、クォータ、費用によっては参加が制限される場合があります。 + +## 始める前に + +この拡張演習では、ワークショップのドキュメント用リポジトリではなく、自分の Tailspin Toys リポジトリを使います。 + +1. 省略可能な機能に着手する前に、必須演習の作業を保存、コミット、プッシュ済みであることを確認します。 +2. [プロジェクトとモデルを準備する][module-1]から始めます。再開する場合は、Tailspin Toys リポジトリを `foundry-agent-vscode` ブランチで開き直し、**Foundry Toolkit** > **My Resources** に `tailspin-toys` プロジェクトとそのモデルデプロイが残っていることを確認します。 +3. どのモジュールで終了する場合も、次のモジュール用に意図的にリソースを残し、継続的な費用を受け入れるのでなければ、[リソースをクリーンアップする][cleanup]の手順に従います。 + +## リソースをクリーンアップする + +どのチェックポイントであっても、試すのを終えたら、不要な費用が発生しないように Azure リソースを削除します。クリーンアップでは後続のモジュールで必要なリソースも削除されるため、その後に続ける場合は作り直しが必要です。 + +> [!WARNING] +> `rg-tailspin-toys` を削除するのは、このリソースグループがこの演習専用で、残しておきたいリソースが含まれていない場合だけにしてください。共有リソースグループを削除すると、無関係なリソースも削除されます。 +> +> モジュール 1 で別のリソースグループ名を承認した場合は、以下のすべてのコマンドで `rg-tailspin-toys` をその名前に置き換えてください。 + +1. 起動した Agent Inspector のデバッグセッション、Azure Functions ホスト、Astro 開発サーバーを、それぞれのターミナルで停止します。 +2. モジュール 2 でホスト型エージェントをデプロイした場合は、`azure.yaml` がある生成済みエージェントディレクトリでターミナルを開き、同じ `azd` 環境を選択してから次のコマンドを実行します。 + + ```bash + azd down --purge + ``` + +3. 選択されているサブスクリプションと、ワークショップのリソースグループがまだ存在するかどうかを確認します。 + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + コマンドが `false` を返した場合、クリーンアップは完了です。`true` を返した場合は、グループ内のリソースを調べます。 + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 残っているリソースがすべてこの演習のものであることを確認します。モジュール 1 で終了した場合は、`azd` サービスをデプロイしていなくても、Foundry プロジェクトとモデルのクリーンアップが必要です。 + +4. ワークショップ専用のリソースグループがまだ存在し、削除する予定のリソースだけが含まれている場合は、次のコマンドを実行します。 + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. `--no-wait` は削除の完了前に制御を返すため、次のコマンドが `false` を返すまで繰り返し実行します。 + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## リソース + +- [Visual Studio Code 向け Foundry Toolkit][foundry-toolkit] +- [Microsoft Foundry エージェント拡張機能の概要][foundry-extension] + +| [次のモジュール: プロジェクトとモデルを準備する →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #リソースをクリーンアップする +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/ja-jp/vscode/README.md b/docs/ja-jp/vscode/README.md new file mode 100644 index 00000000..8783d480 --- /dev/null +++ b/docs/ja-jp/vscode/README.md @@ -0,0 +1,48 @@ +--- +slug: ja-jp/vscode +title: "VS Code" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +VS Code の **[GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)** を使うと、普段のコードエディターで GitHub Copilot を利用できます。Visual Studio Code (および GitHub Codespaces) で、Copilot Chat のエージェントモードを操作し、MCP を通じて外部ツールを接続し、カスタムエージェントを活用します。すべて IDE を離れずに進められ、Copilot はファイル、ターミナル、問題の全体を把握できます。 + +まずカスタム指示を追加し、Copilot がその指示に従う様子を確認します。次に、エージェントモードを使って UI、データ層、テストにまたがるフィルター機能を構築します。その後、Playwright MCP サーバーを接続し、プルリクエストを作成する前に Copilot にブラウザーを操作させて機能をテストします。最後に、アクセシビリティ作業用のカスタムエージェントをレビューして使い、Copilot の変更を監視し、方向付けながら反復して改善します。すべてエディターを離れずに進められます。 + +## 演習 + +| 演習 | トピック | 説明 | +|----------|-------|-------------| +| [0. 前提条件][ex0] | セットアップ | リポジトリと codespace を作成します | +| [1. カスタム指示][ex1] | コンテキスト | VS Code でカスタム指示を追加して検証します | +| [2. エージェントモード][ex2] | コード生成 | エージェントモードでフィルター機能を構築します | +| [3. Playwright による MCP][ex3] | 外部ツール | Playwright MCP サーバーを使ってブラウザーで機能をテストします | +| [4. カスタムエージェント][ex4] | 専門エージェント | カスタムエージェントをレビューして使います | +| [5. エージェントの管理][ex5] | 監視 | エージェントのセッションを監視し、方向付けします | +| [6. 反復して改善する][ex6] | レビュー | Copilot の作業をローカルでレビューし、次のステップを選びます | +| [省略可能: Foundry を組み込む][foundry-toolkit] | AI エージェント | VS Code と Foundry Toolkit を使う 3 つのモジュールで、モデルを準備し、エージェントをデプロイしてサイトに接続します | + +## 前提条件 + +このワークショップに参加する前に、次のものを用意してください。 + +- [ ] 有効な **Copilot Student、Pro、Pro+、Business、Enterprise** のいずれかのプランがある GitHub アカウント +- [ ] GitHub Codespaces へのアクセス + +> [!TIP] +> 有料プランをお持ちでない場合、認証済みの学生は [GitHub Education][callout-student-plan-education] を通じて GitHub Copilot を無料で利用できます。**Copilot Student** プランには、このワークショップで使うエージェント、MCP、コードレビュー、Copilot CLI の機能が含まれるため、どのコースも完了できます。 + +[callout-student-plan-education]: https://github.com/education/students +## 始める + +**[演習 0: 前提条件から始める →][ex0]** + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-agent-mode/ +[ex3]: 3-mcp/ +[ex4]: 4-custom-agents/ +[ex5]: 5-managing-agents/ +[ex6]: 6-iterating/ +[foundry-toolkit]: 7-foundry-toolkit/ diff --git a/docs/ko-kr/vscode/6-iterating.md b/docs/ko-kr/vscode/6-iterating.md new file mode 100644 index 00000000..c05c9a7e --- /dev/null +++ b/docs/ko-kr/vscode/6-iterating.md @@ -0,0 +1,96 @@ +--- +title: "실습 6 - GitHub Copilot의 작업 반복 개선" +authors: + - geektrainer +lastUpdated: 2026-06-30 +next: false +--- + +| [← 이전 실습: 에이전트 모니터링 및 관리][previous-lesson] | +| :-- | + +## 작업 검토 + +지금까지 이 실습에서 GitHub Copilot과 함께 사용자 경험을 개선하는 여러 작업을 수행했습니다. 에이전트 모드(Agent mode)로 클라이언트와 서버 전반에 필터링을 추가하고, Playwright MCP 서버로 브라우저에서 해당 작업을 수동 테스트했습니다. 그런 다음 사용자 지정 에이전트로 고대비 및 밝은 모드 전환 기능을 구현하고, 진행 중인 세션의 방향을 조정하여 작업을 확장했습니다. 이제 로컬 작업을 게시하고 팀에서 검토하는 방식으로 살펴볼 차례입니다. + +### 시나리오 + +생성형 AI가 도입되어도 소프트웨어 설계와 DevOps의 기본은 변하지 않습니다. Copilot이 만든 결과물도 정식 검토 과정을 거쳐야 합니다. 이를 염두에 두고 codespace의 접근성 변경 사항을 푸시한 뒤 풀 리퀘스트(Pull request)를 열고, 팀의 나머지 구성원이 참여하기 전에 변경 내용을 살펴봅니다. +## 접근성 기능 게시 + +[실습 4][exercise-4]와 [실습 5][exercise-5]에서 접근성 사용자 지정 에이전트로 구현한 고대비 및 밝은 모드 전환 기능은 codespace에 커밋된 변경 사항으로 남아 있습니다. 팀의 나머지 구성원이 검토할 수 있도록 브랜치에 푸시하고 풀 리퀘스트를 엽니다. + +1. codespace로 돌아갑니다. +2. VS Code에서 **Source Control** 보기를 엽니다. +3. 접근성 변경 사항을 커밋했는지 확인합니다. 실습 5의 변경 사항 중 커밋하지 않은 것이 있다면 스테이징한 뒤 `Add high-contrast and light-mode toggles`와 같이 내용을 알 수 있는 메시지로 커밋합니다. +4. **Publish Branch**를 선택하여 브랜치를 게시합니다. 또는 **...** 메뉴 → **Push**를 사용합니다. +5. VS Code에서 github.com의 새 브랜치를 열지 묻습니다. 안내를 수락하거나 직접 리포지토리로 이동하여 브랜치 배너의 **Compare & pull request**를 선택합니다. +6. 명확한 제목(예: `Add high-contrast and light-mode toggles`)을 지정하고 수행한 작업과 이유를 요약하는 짧은 설명을 작성합니다. +7. **Create pull request**를 선택합니다. +8. PR을 열면 **Files changed** 탭을 선택하여 작업 전체를 검토합니다. 특히 다음 항목에 주의합니다. + - 모드를 전환하는 토글 UI 컴포넌트. + - 사용자 기본 설정을 유지하기 위한 로컬 스토리지 사용. + - 고대비 및 밝은 모드의 CSS 또는 스타일 변경 사항. + - 접근성 속성(ARIA 레이블, 키보드 탐색 등). + - 모드 전환을 관리하는 JavaScript/TypeScript 코드. + +9. **Conversation** 탭으로 돌아갑니다. +10. 승인을 기다리는 워크플로가 있다면 **Approve and run workflows**를 선택합니다. + + ![워크플로 승인 및 실행](../../_images/shared-approve-workflows.png) +11. 워크플로가 완료될 때까지 기다립니다. 문제가 없다면 통과한 결과가 표시됩니다. + +> [!TIP] +> 접근성 작업에 대한 다른 의견이 필요하다면 PR 댓글에 `@copilot`을 태그하고 "이 PR에 추가적인 WCAG 문제가 있는지 검토해 줘" 또는 "키보드 탐색 개선 사항을 제안해 줘"와 같이 요청합니다. Copilot이 새 세션을 시작하여 댓글의 요청을 처리합니다. + +## 선택 실습 - 로컬에서 계속 탐색 + +IDE에서 에이전트와 반복적으로 작업하는 것도 하나의 기술이며, 이를 익히려면 반복해야 합니다. VS Code에서 진행할 수 있는 후속 세션의 예시는 다음과 같습니다. + +- 게임 상세 페이지에 후원자 관심 등록 양식을 추가합니다. +- 게임 목록 페이지에 페이지 매김을 구현합니다. +- `src/lib/`의 데이터 접근 도우미에 입력 유효성 검사와 오류 처리를 추가합니다. +- 접근성 에이전트의 범위를 확장합니다. 예를 들어 사이트 전체의 키보드 포커스 순서를 점검합니다. + +## 요약 + +축하합니다. VS Code 과정을 완료했습니다! 이 실습에서 수행한 작업은 다음과 같습니다. + +- **Playwright MCP로 기능을 수동 테스트했습니다.** Playwright MCP 서버를 추가하고 Copilot이 브라우저를 조작하여 필터링 기능을 검증하도록 한 뒤 풀 리퀘스트를 열었습니다. +- **에이전트 모드로 스택 전반의 변경 사항을 함께 처리했습니다.** 한 세션에서 클라이언트, 서버, 테스트에 걸친 필터 기능을 추가했습니다. +- **사용자 지정 에이전트를 사용했습니다.** 에이전트 선택기에서 접근성 중심의 사용자 지정 에이전트를 선택하고 리포지토리에 고대비 모드를 구현하는 과정을 살펴보았습니다. +- **에이전트 세션을 관리하고 방향을 조정했습니다.** 제안된 변경 사항을 인라인으로 검토하고 원하는 내용을 수락했으며, 밝은 모드 후속 작업으로 세션을 확장했습니다. +- **풀 리퀘스트로 작업을 마무리했습니다.** 로컬 작업을 게시하고 팀에서 검토하는 방식으로 처음부터 끝까지 살펴보았습니다. + +## 검토 및 다음 단계 + +이것으로 필수 VS Code 과정을 마칩니다. 워크숍을 완료했으므로 여기서 마무리해도 됩니다. + +Copilot의 에이전트 기능을 더 폭넓게 이해하고 싶다면, 다른 과정에서 서로 다른 환경을 통해 관련 시나리오를 살펴볼 수 있습니다. + +- 💻 [**CLI 과정**](../../cli/) — 터미널에서 Copilot CLI로 비슷한 흐름을 진행합니다. 계획 모드, 에이전트 스킬, 사용자 지정 에이전트, `/share`, `/context`, `/delegate`와 같은 슬래시 명령을 다룹니다. +- ☁️ [**클라우드 에이전트 과정**](../../cloud/) — 클라우드 에이전트에 이슈를 할당하고, 에이전트 페이지에서 세션을 모니터링하며, 풀 리퀘스트를 비동기적으로 반복 개선하는 데 초점을 맞춥니다. + +여기서 시작한 작업을 계속 확장할 수도 있습니다. [awesome-copilot][awesome-copilot]에서 본인의 프로젝트에 맞게 활용할 수 있는 더 많은 지침 파일, 사용자 지정 에이전트, 스킬을 찾아볼 수 있습니다. + +선택 확장 과정인 [선택 사항: Foundry 통합][exercise-7]에서는 VS Code와 Microsoft Foundry Toolkit을 사용하여 모델을 준비하고 Backer Concierge를 배포한 뒤 사이트에 연결합니다. + +## 참고 자료 + +- [GitHub Copilot][github-copilot] +- [VS Code의 Copilot Chat][copilot-chat-vscode] +- [에이전트 모드 사용][agent-mode] + +--- + +| [← 이전 실습: 에이전트 관리][previous-lesson] | +|:--| + +[previous-lesson]: ../5-managing-agents/ +[exercise-4]: ../4-custom-agents/ +[exercise-5]: ../5-managing-agents/ +[exercise-7]: ../7-foundry-toolkit/ +[github-copilot]: https://github.com/features/copilot +[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/chat/copilot-chat +[agent-mode]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/ko-kr/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/ko-kr/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..18073680 --- /dev/null +++ b/docs/ko-kr/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "프로젝트 및 모델 준비" +description: "Tailspin 카탈로그를 내보내고 Backer Concierge의 수락 기준에 따라 배포한 모델을 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 선택 사항: Foundry 통합][overview] | +|:--| + +첫 번째 모듈에서는 VS Code와 Microsoft Foundry Toolkit을 사용하여 Backer Concierge에 필요한 데이터와 모델을 준비합니다. 필수 워크숍에서 사용한 본인의 Tailspin Toys 리포지토리에서 작업합니다. + +## 학습 목표 + +- 카탈로그를 내보내고 제공하는 정보의 범위를 파악합니다. +- Foundry 프로젝트를 준비하고 수락 기준과 할당량에 따라 모델을 선택합니다. +- 에이전트 코드를 작성하기 전에 Model Playground에서 그라운딩(Grounding) 동작을 검증합니다. + +## 시나리오 + +Tailspin 후원자는 신뢰할 수 있는 추천을 원합니다. 퍼즐 게임 팬은 지어낸 모금액이 아니라 실제 게임과 정확한 평점을 기대합니다. 안내 도우미는 카탈로그의 정보 범위를 명확히 지키고, 후원자가 원하는 것을 추측하기보다 도움이 되는 질문 하나를 하는 습관을 갖추어야 합니다. + +## 작업 영역 준비 + +툴킷은 모델 탐색, 배포, 프롬프트 엔지니어링(Prompt engineering), 평가, 에이전트 배포를 VS Code에서 지원합니다. Azure 접근 권한을 확보하고 변경 사항을 정리한 기능 브랜치를 마련하여 이후 작업을 준비합니다. + +> [!IMPORTANT] +> Foundry Toolkit과 호스팅 에이전트(Hosted agent)는 공개 미리 보기로 제공됩니다. 이 모듈에서는 유료 Azure 리소스를 만듭니다. 생성을 승인하기 전에 구독 권한, 지역, 할당량, 예상 비용을 확인합니다. 에이전트를 만들기 전에 중단하더라도 [리소스 정리][cleanup]를 수행할 수 있습니다. + +1. Azure 구독에 접근할 수 있는지 확인합니다. 자격 요건과 서비스 제한에 따라 [$200 크레딧을 제공하는 무료 Azure 계정][azure-free]이나 [$100 크레딧을 제공하는 Azure for Students][azure-students]를 사용할 수 있습니다. +2. VS Code의 작업 표시줄에서 **Extensions**를 선택하고 **Foundry Toolkit**을 검색한 뒤 **Install**을 선택합니다. 작업 표시줄에 툴킷 아이콘이 나타납니다. +3. **Azure** 아이콘을 선택하고 **Sign in to Azure…**를 선택한 뒤 Foundry 프로젝트에 사용할 구독을 선택합니다. 툴킷 인증을 완료하면 Copilot이 [Microsoft Foundry Skill][foundry-skill]을 사용하여 대화 방식으로 리소스를 준비할 수 있습니다. +4. Tailspin Toys 작업 영역에서 **Terminal** > **New Terminal**을 열거나 Control+\`(Mac) 또는 Ctrl+\`(Windows/Linux)를 누릅니다. 이전 작업을 커밋하고 푸시했는지 확인한 뒤 기능 브랜치를 만듭니다. + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. **Agent** 모드로 새 Copilot Chat을 열고 다음과 같이 요청합니다. + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. Copilot이 **Add a Backer Concierge assistant for catalog questions** 이슈를 표시하는지 확인합니다. 수락 기준은 근거에 기반한 답변, 모금액을 지어내지 않는 동작, 명확히 하기 위한 질문 하나, 엔드투엔드 테스트를 갖춘 접근성 있는 UI를 요구합니다. + +## 카탈로그 내보내기 + +카탈로그 내보내기 스크립트는 에이전트가 답변의 근거로 사용할 데이터 원본을 제공합니다. + +1. Tailspin Toys 리포지토리 터미널에서 마이그레이션과 시드 데이터 입력을 수행한 뒤 `db/catalog.json`을 작성합니다. + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. `db/catalog.json`을 열고 게임 21개가 들어 있는지 확인합니다. 각 게임에는 제목, 설명, 카테고리, 배급사, 별점과 함께 누락된 정보를 설명하는 `note` 필드가 있어야 합니다. 총모금액, 후원자 수, 후원 등급, 출시일은 포함하지 않으므로 에이전트는 이 정보 범위를 지켜야 합니다. + +## Foundry 프로젝트 설정 + +프로젝트에는 모델을 두고 나중에는 호스팅 에이전트도 추가합니다. 이 모듈을 이어서 진행할 때는 다른 프로젝트를 만들지 않고 동일한 프로젝트를 사용합니다. + +1. 작업 표시줄에서 **Foundry Toolkit**을 선택하고 **Help and Feedback**을 펼친 뒤 **Ask Copilot**을 선택합니다. 드롭다운에서 원하는 모델을 확인하고 생성된 `/foundrytk-quick-start` 프롬프트를 보냅니다. + + ![Foundry Toolkit 빠른 시작 순서를 보여 주는 스크린샷.](../../../_images/vscode-foundry-setup.png) + +2. 대화형 워크플로에서 **Where are you starting from?**에 **Set up Foundry**로 답한 뒤 **What do you have already?**에 **I have an Azure subscription or Foundry resources**로 답합니다. +3. 도구 승인 요청을 검토합니다. 제안한 명령과 범위가 적절하다면 이 세션에 대해 **Allow azmcp …**를 선택하여 반복되는 승인 요청을 줄입니다. +4. **Microsoft Foundry: Create Project**의 **Choose a resource group**에서 **Create new resource group**을 선택하고 `rg-tailspin-toys`를 입력합니다. 사용할 모델을 제공하는 지역을 선택하고 **Enter project name**에 `tailspin-toys`를 입력합니다. `East US 2`와 `Sweden Central`은 다양한 모델을 제공하는 초기 후보 지역입니다. 실제 선택은 현재 가용성과 할당량에 따라 결정합니다. 이어서 진행하는 경우에는 기존 프로젝트를 선택합니다. +5. 배포 성공 알림이 나타날 때까지 기다립니다. 툴킷에서 **My Resources**를 펼치고 이 프로젝트가 기본 프로젝트인지 확인합니다. + +## 모델 탐색 및 배포 + +여기서는 가장 크거나 가장 새로운 모델을 선택하는 것보다 규칙 준수와 그라운딩이 더 중요합니다. 이슈는 속도, 충실도, 지역별 가용성, 할당량을 비교할 수 있는 구체적인 기준을 제공합니다. + +1. Copilot Chat에서 **+**, **GitHub Issues**를 차례로 선택하고 **Add a Backer Concierge assistant for catalog questions**를 첨부합니다. 다음 프롬프트를 보냅니다. + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. 추천 내용을 읽고 요구 사항과 사용 가능한 할당량에 가장 적합한 모델을 선택합니다. Copilot에 배포를 요청합니다. + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. 승인하기 전에 프로젝트, 배포, 용량, 비용을 확인합니다. 범위를 검토한 결과 적절하다면 이 세션에 대해 **Allow az …**를 선택하여 반복되는 요청을 줄입니다. +4. **Foundry Toolkit**을 선택하고 **My Resources**를 펼친 뒤 **Models**를 선택합니다. 배포한 모델이 Foundry 아래에 나타나는지 확인합니다. 스크린샷은 예시이며 지역에 따라 다른 모델을 제공할 수 있습니다. + + ![Foundry Toolkit의 모델 배포 예시를 보여 주는 스크린샷.](../../../_images/vscode-model-deployed.png) + +## 배포한 모델 테스트 + +Model Playground에는 카탈로그 파일이 없습니다. 시스템 프롬프트(System prompt)에 게임 9개로 줄인 하위 집합을 넣으면 모델이 그라운딩 규칙을 따르는지 테스트하기에 충분합니다. + +1. **Models**에서 배포한 모델 이름을 선택하여 해당 모델이 미리 지정된 **Model Playground**를 엽니다. 다음 시스템 프롬프트를 붙여 넣습니다. + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. `I love puzzle games about tracking down bugs. What should I back?`로 그라운딩을 테스트합니다. 목록에 있는 실제 게임을 정확한 정보와 함께 제시해야 합니다. +3. `How much has Pipeline Conquest raised so far, and how many backers does it have?`로 누락된 정보를 테스트합니다. 카탈로그에서 모금액이나 후원자를 추적하지 않으므로 명확히 답변을 거절한 다음 알고 있는 정보를 제공해야 합니다. +4. `I need something for four players, about an hour long.`으로 다른 정보 범위를 테스트합니다. 플레이어 수와 플레이 시간을 알 수 없다고 설명한 뒤 다음 추천에 도움이 되는 후속 질문 하나를 해야 합니다. +5. `Do you have Wingspan? If not, what's the closest thing you've got?`로 카탈로그에 없는 게임을 요구하는 상황을 테스트합니다. Wingspan이 카탈로그에 있다고 주장하거나 외부 지식으로 설명하지 않고 실제 Tailspin 게임으로 대화를 전환해야 합니다. +6. `Recommend me something good.`으로 모호한 요청을 테스트합니다. 짧은 확인 질문 하나를 하고, 카테고리나 테마를 알기 전에는 추천하지 않아야 합니다. +7. `What are your three highest rated games?`로 순위를 테스트합니다. Deployment Dynasty와 Script Strike가 5.0점, 그다음 Code Quest Odyssey가 4.8점으로 올바른 순서와 정확한 점수를 제시해야 합니다. +8. 점검에 실패하면 Copilot과 실패한 답변 및 규칙을 논의하고, 구성이나 모델 선택을 조정한 뒤 점검을 반복하여 통과한 후 계속합니다. + +## 완료 점검 + +VS Code 작업 영역을 준비하고 카탈로그를 내보냈으며, Foundry 프로젝트를 만들고 배포한 모델이 Backer Concierge의 근거 기반 응답 규칙을 지키는지 테스트했습니다. 이 모듈의 완료 점검 항목은 없는 정보를 지어내지 않고 카탈로그에 실제로 있는 게임을 추천하는 모델이며, 아직 배포한 에이전트는 아닙니다. + +다음에는 동일한 `tailspin-toys` 프로젝트와 선택한 모델 배포를 사용하여 에이전트를 빌드하고 배포합니다. 여기서 중단한다면 지속적인 비용이 발생하지 않도록 [Azure 리소스를 정리합니다][cleanup]. + +| [다음 모듈: 에이전트 빌드 및 배포 →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#리소스-정리 +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/ko-kr/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/ko-kr/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..e686042d --- /dev/null +++ b/docs/ko-kr/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "에이전트 빌드 및 배포" +description: "VS Code에서 Backer Concierge의 스캐폴드를 생성하고 디버깅한 뒤 Foundry 호스팅 에이전트로 배포하고 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 이전 모듈: 프로젝트 및 모델 준비][previous-lesson] | +|:--| + +이 모듈에서는 [프로젝트 및 모델 준비][previous-lesson]에서 만든 카탈로그와 테스트한 모델을 사용합니다. Microsoft Foundry Toolkit과 **AIAgentExpert** 사용자 지정 에이전트가 VS Code에서 로컬 빌드와 호스팅 배포를 안내합니다. + +## 학습 목표 + +- 기존 Tailspin Toys 작업 영역에서 카탈로그에 근거한 에이전트의 스캐폴드(Scaffold)를 생성합니다. +- Agent Inspector로 로컬 동작을 디버깅합니다. +- 기존 Foundry 프로젝트에 배포하고 호스팅 에이전트(Hosted agent)를 검증합니다. + +## 시나리오 + +신뢰할 수 있는 추천은 단 한 번의 대화에서만 성립해서는 안 됩니다. Tailspin Toys의 안내 도우미는 후원자가 모호한 질문을 하거나 알 수 없는 모금 정보를 집요하게 요구하더라도 카탈로그의 정보 범위를 지켜야 합니다. 호스팅된 안내 도우미도 비공개로 테스트했을 때와 똑같이 안정적으로 동작해야 합니다. + +## 작업 영역에서 이어서 진행 + +에이전트는 기존 모델 배포를 사용하므로 새 Foundry 프로젝트를 만들 필요가 없습니다. + +1. VS Code에서 동일한 Tailspin Toys 리포지토리의 `foundry-agent-vscode`를 엽니다. `db/catalog.json`이 존재하고 **Foundry Toolkit** > **My Resources**에 `tailspin-toys` 프로젝트와 테스트한 모델 배포가 표시되는지 확인합니다. +2. [이전 완료 점검][previous-lesson]을 마쳤는지 확인합니다. 리소스를 정리했다면 프로젝트와 모델 준비를 다시 완료한 뒤 계속합니다. +3. Azure Developer CLI(`azd`)가 아직 없다면 설치합니다. 호스팅 에이전트 배포에 필요합니다. 운영 체제에 맞는 명령만 선택합니다. + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. 기존 프로젝트에 사용하는 구독으로 로그인합니다. + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> 호스팅 에이전트와 Foundry Toolkit은 공개 미리 보기로 제공됩니다. 배포 시 유료 리소스를 만듭니다. 명령을 승인하기 전에 구독, 권한, 지역, 할당량, 예상 비용을 확인합니다. + +## 에이전트 생성 및 디버깅 + +툴킷은 현재 리포지토리에 코드 스캐폴드를 생성하고 특화된 Copilot Chat을 엽니다. Agent Inspector를 사용하면 배포 전에 로컬 요청, 이벤트, 도구 호출을 확인할 수 있습니다. + +1. **Foundry Toolkit**을 선택하고 **Developer Tools**, **+ Build**를 차례로 펼친 뒤 **+ Create Agent**를 선택합니다. **Create Agent**에서 **Code an agent with Copilot**을 선택합니다. + + ![에이전트 생성 페이지를 보여 주는 스크린샷.](../../../_images/vscode-create-agent.png) + +2. 새 채팅이 **AIAgentExpert**로 전환되는지 확인합니다. 생성된 프롬프트를 다음의 사용자 지정 프롬프트로 바꾸고 전송합니다. + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. `agent/backer-concierge`에 생성된 코드를 검토합니다. 배포 가능한 에이전트에 카탈로그가 포함되어 있고, 관련 테스트를 통과했으며, 자격 증명이나 로컬 환경 파일이 커밋되지 않을지 확인합니다. +4. 작업 표시줄에서 **Run and Debug**를 선택하고 F5로 디버거를 시작합니다. **Agent Inspector**가 열리고 에이전트 서버에 연결되는지 확인합니다. +5. [배포한 모델 테스트][model-tests]의 프롬프트 여섯 개를 모두 재사용합니다. 게임 9개로 구성된 하위 집합의 순위가 전체 카탈로그 순위와 같다고 가정하지 말고 전체 `db/catalog.json`을 기준으로 답변을 점검합니다. +6. **Input & Output**, **Events**, **Tools** 사이를 전환하여 페이로드(Payload), 세션 이벤트, 도구 호출을 살펴봅니다. 수락 기준을 위반하는 동작이 있다면 Copilot에 수정을 요청하고 배포하기 전에 관련 테스트와 Inspector 점검을 다시 실행합니다. + + ![로컬 에이전트 디버깅 워크플로를 보여 주는 스크린샷.](../../../_images/vscode-agent-debug.png) + +## 호스팅 에이전트 배포 및 테스트 + +**Go production** 핸드오프(Handoff)는 기존 에이전트를 Foundry용으로 패키징합니다. 이후에 만드는 사이트 프록시(Proxy)를 프로덕션용 공개 서비스로 만들어 주는 것은 아닙니다. + +1. 에이전트를 생성한 Copilot Chat에서 **Go production**을 선택하고 기본 프롬프트를 다음 내용으로 바꾼 뒤 전송합니다. + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![AIAgentExpert 에이전트의 핸드오프 옵션을 보여 주는 스크린샷.](../../../_images/vscode-go-production-handoff.png) + +2. 채팅과 터미널에서 매개 변수와 명령 승인 요청을 검토합니다. 배포 대상이 기존 `tailspin-toys` 프로젝트인지 확인하고 승인하기 전에 유료 리소스를 검토합니다. +3. Copilot이 평가 테스트 모음을 제안하면 추가 점검으로 수락하여 진행할 수 있습니다. +4. **Foundry Toolkit**을 선택하고 **My Resources**를 펼친 뒤 **Agents**를 선택합니다. **Agents** 탭에서 **Hosted Agent**로 전환합니다. + + ![배포한 호스팅 에이전트를 보여 주는 스크린샷.](../../../_images/vscode-agent-deployed.png) + +5. 에이전트 이름을 선택하고 배포 상태가 **Running**인지 확인합니다. **Playground**로 전환하고 배포된 카탈로그를 기준으로 그라운딩(Grounding), 누락된 정보, 카탈로그 외부 항목, 모호한 요청, 순위 점검을 반복합니다. + + ![배포한 호스팅 에이전트의 답변을 보여 주는 스크린샷.](../../../_images/vscode-agent-response.png) + +6. 배포나 답변에 문제가 있다면 Copilot과 함께 보고된 상태 및 로그를 살펴보고, 기존 프로젝트에서 문제를 수정한 뒤 점검을 반복합니다. 배포를 검증하지 않은 채로 계속하지 않습니다. + +## 완료 점검 + +Backer Concierge를 스캐폴드하고 Agent Inspector에서 카탈로그 근거 기반 응답을 디버깅했으며, **Go production** 핸드오프로 Foundry에 배포한 뒤 Playground에서 호스팅 버전을 다시 테스트했습니다. 이 모듈의 완료 점검 항목은 없는 정보를 지어내지 않고 카탈로그 범위를 지키며 실행 중인 호스팅 에이전트입니다. + +다음에는 동일한 `tailspin-toys` 프로젝트, 모델 배포, 호스팅 에이전트를 사용하여 사이트에 에이전트를 연결합니다. 여기서 중단한다면 지속적인 비용이 발생하지 않도록 [Azure 리소스를 정리합니다][cleanup]. + +| [다음 모듈: 사이트에 에이전트 연결 →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#배포한-모델-테스트 +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#리소스-정리 diff --git a/docs/ko-kr/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/ko-kr/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..492b5b3b --- /dev/null +++ b/docs/ko-kr/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "사이트에 에이전트 연결" +description: "로컬 프록시를 통해 호스팅된 Backer Concierge를 연결하고 접근성을 갖춘 채팅 위젯을 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← 이전 모듈: 에이전트 빌드 및 배포][previous-lesson] | +|:--| + +이 모듈에서는 [에이전트 빌드 및 배포][previous-lesson]의 호스팅 에이전트(Hosted agent)를 Tailspin Toys에 연결합니다. VS Code의 Copilot Chat은 공개 프로덕션 엔드포인트가 아니라 로컬 통합을 만듭니다. + +## 학습 목표 + +- 자격 증명과 Foundry 대화 식별자를 로컬 서버 측 프록시(Proxy) 내부에 유지합니다. +- 대화의 연속성을 유지하는 접근성 있는 채팅 위젯을 추가합니다. +- 리소스를 정리하기 전에 백엔드와 전체 사용자 경험을 검증합니다. + +## 시나리오 + +후원자는 카탈로그를 벗어나지 않고도 안내 도우미에게 조언을 구할 수 있어야 합니다. 대화는 맥락을 유지하고, 키보드로 이용할 수 있으며, 비공개 연결 정보를 보호해야 합니다. 신뢰를 얻으려면 정직한 추천뿐만 아니라 안전하고 접근성을 갖춘 경험도 필요합니다. + +## 작업 영역에서 이어서 진행 + +통합 대상은 기존 호스팅 에이전트입니다. Tailspin Toys는 모든 페이지를 미리 렌더링한 정적 웹사이트이므로 브라우저 코드에 에이전트의 자격 증명을 안전하게 보관할 수 없습니다. + +1. VS Code에서 동일한 Tailspin Toys 리포지토리의 `foundry-agent-vscode`를 엽니다. 이전 완료 점검의 호스팅 에이전트가 기존 `tailspin-toys` 프로젝트에서 여전히 **Running** 상태이고 로컬 Azure 로그인이 해당 구독을 대상으로 하는지 확인합니다. +2. **AIAgentExpert** 대신 일반 **Agent** 모드로 Copilot Chat을 엽니다. **+**, **GitHub Issues**를 차례로 선택한 뒤 해당 이슈를 선택하여 **Add a Backer Concierge assistant for catalog questions**를 첨부합니다. + +## 로컬 프록시 빌드 및 검증 + +`/api`의 로컬 Azure Functions 프록시는 사이트가 로컬에서 실행되는 동안 연결 정보를 보관하고 요청을 전달합니다. Copilot은 **Azure skills**를 사용하여 프록시를 준비하고 검증할 수 있습니다. + +> [!IMPORTANT] +> 이 워크숍 프록시는 로컬 개발 전용입니다. 익명으로 접근할 수 있는 공개 엔드포인트로 배포하지 않습니다. 프로덕션에는 애플리케이션에 맞는 인증과 악용 방지 제어가 필요하며, 여기에는 요청 속도 제한이나 할당량, CORS 제한, 모니터링, 비용 제어가 포함됩니다. + +1. Copilot에 프록시 생성을 요청합니다. + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. 변경 사항을 수락하기 전에 검토합니다. 자격 증명과 Foundry 대화 식별자를 서버에 유지하고, 로컬 설정을 버전 관리에서 제외하며, 요청에 제한을 적용하고, 관련 테스트를 통과했는지 확인합니다. +3. UI를 만들기 전에 백엔드가 작동함을 입증합니다. + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. 터미널의 응답을 확인합니다. 답변을 담은 `response` 속성이 있는 유효한 JSON이어야 하며, 지어낸 가격 정보나 자격 증명, 내부 대화 식별자가 없어야 합니다. 점검에 실패하면 Copilot에 수정을 요청하고 백엔드 테스트를 반복합니다. +5. **Keep**으로 변경 사항을 유지하고 **/clear**를 사용하여 동일한 리포지토리와 브랜치에서 위젯 작업을 새로 시작합니다. 로컬 프록시 구성과 기존 호스팅 에이전트 연결을 유지합니다. + +## 위젯 빌드 및 테스트 + +이제 UI에서 사용할 백엔드를 검증했습니다. 엔드투엔드 테스트(End-to-end test)로 사용성과 카탈로그의 정보 범위를 모두 점검합니다. + +1. Copilot에 위젯 추가를 요청합니다. + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Backer Concierge 채팅 위젯이 동작하는 모습을 보여 주는 스크린샷](../../../_images/tailspin-toys-backer-concierge-agent.png) + +2. Function과 사이트를 계속 실행한 상태에서 전체 사용자 경험을 검증합니다. + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. 이슈의 수락 기준에 따라 테스트 결과와 변경 사항을 검토합니다. 근거에 기반한 답변, 모금액을 지어내지 않는 동작, 명확히 하기 위한 질문 하나, 접근성 있는 UI, 엔드투엔드 테스트가 기준입니다. 실패한 부분을 수정하고 관련 점검을 다시 실행했는지 확인합니다. + +## 완료 점검 + +자격 증명을 안전하게 보호하는 로컬 프록시를 만들고 접근성 있는 채팅 위젯을 연결했으며, 호스팅 Backer Concierge를 대상으로 전체 대화 흐름을 검증했습니다. 이 모듈의 완료 점검 항목은 카탈로그 범위를 지키고 자격 증명과 Foundry 내부 식별자를 브라우저에 노출하지 않는, 로컬에서 테스트한 사이트 통합입니다. 프록시나 사이트의 프로덕션 배포가 아닙니다. + +실습을 마치면 로컬 서비스를 중지하고 지속적인 비용이 발생하지 않도록 [Azure 리소스를 정리합니다][cleanup]. 그런 다음 핵심 워크숍의 [VS Code 개요][vscode-overview]로 돌아갑니다. + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#리소스-정리 +[vscode-overview]: ../../ diff --git a/docs/ko-kr/vscode/7-foundry-toolkit/README.md b/docs/ko-kr/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..44cb8bfb --- /dev/null +++ b/docs/ko-kr/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: ko-kr/vscode/7-foundry-toolkit +title: "선택 사항: Foundry 통합" +description: "VS Code와 Microsoft Foundry Toolkit으로 세 가지 집중 모듈에 걸쳐 카탈로그에 근거한 Backer Concierge를 만듭니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 이전 실습: GitHub Copilot의 작업 반복 개선][previous-lesson] | +|:--| + +필수 VS Code 과정은 실습 6에서 완료됩니다. 이 선택 확장 과정에서는 VS Code의 GitHub Copilot Chat과 Microsoft Foundry Toolkit을 사용하여 Tailspin 카탈로그를 기반으로 Backer Concierge를 만들고, 호스팅 에이전트(Hosted agent)로 배포한 뒤 로컬 프록시(Proxy)를 통해 사이트에 연결합니다. + +## 시나리오 + +후원자는 필터만으로는 답할 수 없는 질문을 합니다. git 말장난을 좋아하는 사람에게 어떤 게임이 어울리는지, 특정 퍼즐 게임이 다른 게임보다 더 잘 맞는 이유는 무엇인지 궁금해합니다. Tailspin Toys에는 실제 카탈로그의 게임을 추천하고, 필요할 때 명확히 하기 위한 질문을 하며, 모금액이나 기타 정보를 알 수 없을 때 이를 솔직히 인정하여 신뢰를 얻는 안내 도우미가 필요합니다. + +## 모듈 + +각 모듈은 작동하는 결과물을 확인하는 것으로 마무리합니다. 세 모듈 모두 동일한 학습자 리포지토리, 기능 브랜치, Foundry 프로젝트를 사용하며, 모듈 사이에 프로젝트를 다시 만들지 않습니다. + +| 모듈 | 완료 점검 항목 | +|--------|-----------------------| +| [1. 프로젝트 및 모델 준비][module-1] | 카탈로그를 내보내고 그라운딩(Grounding) 규칙에 따라 배포한 모델 테스트 | +| [2. 에이전트 빌드 및 배포][module-2] | 로컬 에이전트 디버깅 및 호스팅 에이전트 테스트 | +| [3. 사이트에 에이전트 연결][module-3] | 로컬 프록시 및 접근성을 갖춘 위젯의 엔드투엔드 테스트 | + +> [!IMPORTANT] +> Microsoft Foundry Toolkit과 호스팅 에이전트는 공개 미리 보기로 제공됩니다. 이 모듈에서는 모델 배포와 호스팅 에이전트를 비롯한 유료 Azure 리소스를 만듭니다. 구독 권한, 지역별 가용성, 할당량, 비용에 따라 참여가 제한될 수 있습니다. + +## 시작하기 전에 + +이 확장 과정은 워크숍 문서 리포지토리가 아니라 본인의 Tailspin Toys 리포지토리에서 진행합니다. + +1. 선택 기능을 시작하기 전에 필수 워크숍 작업을 저장하고 커밋하여 푸시했는지 확인합니다. +2. [프로젝트 및 모델 준비][module-1]부터 시작합니다. 이어서 진행하는 경우 Tailspin Toys 리포지토리를 `foundry-agent-vscode` 브랜치에서 다시 열고 **Foundry Toolkit** > **My Resources**에 `tailspin-toys` 프로젝트와 모델 배포가 남아 있는지 확인합니다. +3. 어느 모듈에서든 중단할 때는 다음 모듈을 위해 의도적으로 리소스를 유지하고 지속적인 비용을 부담하는 경우가 아니라면 [리소스 정리][cleanup]를 따릅니다. + +## 리소스 정리 + +어느 체크포인트에서든 실습을 마쳤다면 불필요한 비용이 발생하지 않도록 Azure 리소스를 삭제합니다. 정리하면 이후 모듈에 필요한 리소스도 함께 삭제되므로, 나중에 이어서 진행하려면 다시 만들어야 합니다. + +> [!WARNING] +> `rg-tailspin-toys`는 이 실습 전용이고 보관할 리소스가 없는 경우에만 삭제합니다. 공유 리소스 그룹을 삭제하면 관련 없는 리소스까지 제거됩니다. +> +> 모듈 1에서 다른 리소스 그룹 이름을 승인했다면 아래의 모든 명령에서 `rg-tailspin-toys`를 해당 이름으로 바꿉니다. + +1. 시작한 Agent Inspector 디버그 세션, Azure Functions 호스트, Astro 개발 서버를 각 터미널에서 중지합니다. +2. 모듈 2에서 호스팅 에이전트를 배포했다면 `azure.yaml`이 있는 생성된 에이전트 디렉터리에서 터미널을 열고 동일한 `azd` 환경을 선택한 뒤 다음을 실행합니다. + + ```bash + azd down --purge + ``` + +3. 선택한 구독과 워크숍 리소스 그룹이 아직 남아 있는지 확인합니다. + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + 명령이 `false`를 반환하면 정리가 완료된 것입니다. `true`를 반환하면 그룹의 리소스를 검토합니다. + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 남아 있는 리소스가 모두 이 실습에 속하는지 확인합니다. 모듈 1에서 중단했다면 `azd` 서비스를 배포하지 않았더라도 Foundry 프로젝트와 모델은 정리해야 합니다. + +4. 워크숍 전용 리소스 그룹이 아직 존재하고 삭제하려는 리소스만 포함되어 있다면 다음을 실행합니다. + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. `--no-wait`는 삭제가 완료되기 전에 반환되므로, 다음 명령이 `false`를 반환할 때까지 다시 실행합니다. + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## 참고 자료 + +- [Visual Studio Code용 Foundry Toolkit][foundry-toolkit] +- [Microsoft Foundry 에이전트 확장 개요][foundry-extension] + +| [다음 모듈: 프로젝트 및 모델 준비 →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #리소스-정리 +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/ko-kr/vscode/README.md b/docs/ko-kr/vscode/README.md new file mode 100644 index 00000000..73c6407e --- /dev/null +++ b/docs/ko-kr/vscode/README.md @@ -0,0 +1,48 @@ +--- +slug: ko-kr/vscode +title: "VS Code" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +VS Code의 [**GitHub Copilot Chat**](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)은 이미 사용 중인 코드 편집기에 GitHub Copilot을 통합합니다. Visual Studio Code와 GitHub Codespaces에서 Copilot Chat의 에이전트 모드(Agent mode)를 사용하고, MCP를 통해 외부 도구를 연결하며, 사용자 지정 에이전트를 활용합니다. IDE를 벗어나지 않고 이 모든 작업을 수행하며, Copilot은 파일, 터미널, 문제를 모두 확인할 수 있습니다. + +먼저 사용자 지정 지침을 추가하고 Copilot이 이를 따르는지 살펴봅니다. 그런 다음 에이전트 모드로 UI, 데이터 계층, 테스트에 걸쳐 필터링 기능을 만듭니다. 이어서 Playwright MCP 서버를 연결하고 Copilot이 브라우저를 조작하여 기능을 테스트하도록 한 뒤 풀 리퀘스트(Pull request)를 엽니다. 마지막으로 접근성 작업을 위한 사용자 지정 에이전트를 검토하고 사용한 다음, Copilot의 변경 사항을 모니터링하고 방향을 조정하며 반복해서 개선합니다. 모든 작업은 편집기 안에서 진행합니다. + +## 실습 + +| 실습 | 주제 | 설명 | +|----------|-------|-------------| +| [0. 사전 요구 사항][ex0] | 설정 | 리포지토리와 codespace 만들기 | +| [1. 사용자 지정 지침][ex1] | 컨텍스트 | VS Code에서 사용자 지정 지침 추가 및 검증 | +| [2. 에이전트 모드][ex2] | 코드 생성 | 에이전트 모드로 필터링 기능 만들기 | +| [3. Playwright와 MCP][ex3] | 외부 도구 | Playwright MCP 서버로 브라우저에서 기능 테스트 | +| [4. 사용자 지정 에이전트][ex4] | 특화된 에이전트 | 사용자 지정 에이전트 검토 및 사용 | +| [5. 에이전트 관리][ex5] | 모니터링 | 에이전트 세션 모니터링 및 방향 조정 | +| [6. 반복 개선][ex6] | 검토 | 로컬에서 Copilot의 작업을 검토하고 다음 단계 선택 | +| [선택 사항: Foundry 통합][foundry-toolkit] | AI 에이전트 | VS Code와 Foundry Toolkit으로 세 모듈에 걸쳐 모델을 준비하고 에이전트를 배포한 뒤 사이트에 연결 | + +## 사전 요구 사항 + +워크숍에 참여하기 전에 다음을 준비합니다. + +- [ ] **Copilot Student, Pro, Pro+, Business 또는 Enterprise** 요금제를 사용 중인 GitHub 계정 +- [ ] GitHub Codespaces 접근 권한 + +> [!TIP] +> 유료 요금제가 없어도 괜찮습니다. 인증된 학생은 [GitHub Education][callout-student-plan-education]을 통해 GitHub Copilot을 무료로 사용할 수 있습니다. **Copilot Student** 요금제에는 이 워크숍에서 사용하는 에이전트, MCP, 코드 리뷰, Copilot CLI 기능이 포함되어 있으므로 모든 과정을 완료할 수 있습니다. + +[callout-student-plan-education]: https://github.com/education/students +## 시작하기 + +[**실습 0: 사전 요구 사항부터 시작 →**][ex0] + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-agent-mode/ +[ex3]: 3-mcp/ +[ex4]: 4-custom-agents/ +[ex5]: 5-managing-agents/ +[ex6]: 6-iterating/ +[foundry-toolkit]: 7-foundry-toolkit/ diff --git a/docs/pt-br/vscode/6-iterating.md b/docs/pt-br/vscode/6-iterating.md new file mode 100644 index 00000000..f0a44dce --- /dev/null +++ b/docs/pt-br/vscode/6-iterating.md @@ -0,0 +1,96 @@ +--- +title: "Exercício 6 - Iterar sobre o trabalho do GitHub Copilot" +authors: + - geektrainer +lastUpdated: 2026-06-30 +next: false +--- + +| [← Lição anterior: Monitorar e gerenciar agentes][previous-lesson] | +| :-- | + +## Revisar o trabalho + +Ao longo deste laboratório, você trabalhou com o GitHub Copilot em várias tarefas voltadas a melhorar a experiência do usuário. Usou o modo de agente para adicionar filtragem no cliente e no servidor, o servidor MCP do Playwright para testar manualmente esse trabalho em um navegador e, depois, um agente personalizado para implementar recursos de acessibilidade — controles para alternar o alto contraste e o modo claro — e orientou a sessão em andamento para ampliar o trabalho. Agora é hora de publicar esse trabalho local e revisá-lo da mesma forma que sua equipe faria. + +### Cenário + +Os fundamentos do design de software e do DevOps não mudam com a adição de IA generativa. Você ainda precisa de um ciclo real de revisão de tudo o que o Copilot produz. Com isso em mente, vamos enviar as alterações de acessibilidade do codespace ao repositório remoto, abrir um pull request e examinar o diff antes de envolver o restante da equipe. +## Publicar os recursos de acessibilidade + +Os controles de alto contraste e modo claro que você implementou com o agente personalizado de acessibilidade no [Exercício 4][exercise-4] e no [Exercício 5][exercise-5] estão no codespace como alterações registradas em commits. Vamos enviá-las para uma branch no repositório remoto e abrir um pull request para que o restante da equipe possa revisar. + +1. Retorne ao codespace. +2. Abra a exibição **Source Control** no VS Code. +3. Confirme que as alterações de acessibilidade estão registradas em commits. Se houver alterações do Exercício 5 ainda não registradas em commits, adicione-as à área de preparação e faça um commit agora com uma mensagem descritiva, como `Add high-contrast and light-mode toggles`. +4. Publique a branch selecionando **Publish Branch** (ou use o menu **...** → **Push**). +5. O VS Code oferecerá a opção de abrir a nova branch no github.com. Aceite a solicitação ou acesse o repositório manualmente e selecione **Compare & pull request** no banner da branch. +6. Defina um título claro (por exemplo, `Add high-contrast and light-mode toggles`) e uma descrição curta que resuma o que foi feito e por quê. +7. Selecione **Create pull request**. +8. Depois que o PR estiver aberto, selecione a guia **Files changed** para revisar o trabalho de ponta a ponta. Preste atenção especial a: + - Os componentes de interface dos controles para alternar entre os modos. + - O uso do armazenamento local para persistir as preferências do usuário. + - As alterações de CSS ou de estilos para os modos de alto contraste e claro. + - Os atributos de acessibilidade (rótulos ARIA, navegação por teclado etc.). + - Qualquer código JavaScript/TypeScript que gerencie a alternância de modos. + +9. Retorne à guia **Conversation**. +10. Se houver fluxos de trabalho aguardando aprovação, selecione **Approve and run workflows**. + + ![Aprovar e executar fluxos de trabalho](../../_images/shared-approve-workflows.png) +11. Aguarde a conclusão dos fluxos de trabalho. Se tudo correr bem, eles deverão passar. + +> [!TIP] +> Quer uma segunda opinião sobre o trabalho de acessibilidade? Marque `@copilot` em um comentário no PR com uma solicitação como "revise este PR em busca de outros problemas relacionados às WCAG" ou "sugira melhorias na navegação por teclado". O Copilot iniciará uma nova sessão para atender ao comentário. + +## Exercício opcional - continuar explorando localmente + +Trabalhar de forma iterativa com um agente no IDE é uma habilidade, e a única forma de desenvolvê-la é praticar. Algumas ideias para próximas sessões que você pode executar no VS Code: + +- Adicione um formulário de interesse para apoiadores na página de detalhes do jogo. +- Implemente paginação na página de lista de jogos. +- Adicione validação de entrada e tratamento de erros às funções auxiliares de acesso a dados em `src/lib/`. +- Amplie o escopo do agente de acessibilidade — por exemplo, audite a ordem de foco do teclado em todo o site. + +## Resumo + +Parabéns — você concluiu a trilha do VS Code! Ao longo deste laboratório, você: + +- **Usou o Playwright MCP para testar manualmente a funcionalidade.** Adicionou o servidor MCP do Playwright e deixou o Copilot controlar um navegador para verificar a funcionalidade de filtragem antes de abrir um pull request. +- **Conduziu o modo de agente em alterações coordenadas por toda a stack.** Adicionou uma funcionalidade de filtragem que envolveu o cliente, o servidor e os testes em uma única sessão. +- **Usou um agente personalizado.** Selecionou o agente personalizado voltado à acessibilidade no seletor de agentes e observou a implementação do modo de alto contraste no repositório. +- **Gerenciou e orientou uma sessão de agente.** Revisou as alterações propostas diretamente no editor, aceitou o que queria e ampliou a sessão com uma solicitação adicional de modo claro. +- **Concluiu o ciclo com um pull request.** Publicou o trabalho local e o revisou de ponta a ponta da mesma forma que sua equipe faria. + +## Revisão e próximos passos + +Isso encerra a trilha obrigatória do VS Code. Você pode parar aqui com o workshop concluído. + +Se quiser ampliar sua perspectiva sobre os recursos de agente do Copilot, as outras trilhas abordam cenários relacionados em interfaces diferentes: + +- 💻 **[Trilha da CLI](../../cli/)** — execute fluxos semelhantes no terminal com o Copilot CLI: modo de planejamento, skills de agentes, agentes personalizados e comandos de barra, como `/share`, `/context` e `/delegate`. +- ☁️ **[Trilha do agente na nuvem](../../cloud/)** — concentre-se em atribuir issues ao agente na nuvem, monitorar sessões pela página de agentes e iterar de forma assíncrona em pull requests. + +Você também pode continuar desenvolvendo o que começou aqui. O [awesome-copilot][awesome-copilot] é uma ótima fonte de arquivos de instruções, agentes personalizados e skills que você pode adaptar aos seus projetos. + +Como extensão opcional, [Opcional: Incorporar o Foundry][exercise-7] usa o VS Code e o Microsoft Foundry Toolkit para preparar um modelo, implantar um Backer Concierge e conectá-lo ao site. + +## Recursos + +- [GitHub Copilot][github-copilot] +- [Copilot Chat no VS Code][copilot-chat-vscode] +- [Uso do modo de agente][agent-mode] + +--- + +| [← Lição anterior: Gerenciar agentes][previous-lesson] | +|:--| + +[previous-lesson]: ../5-managing-agents/ +[exercise-4]: ../4-custom-agents/ +[exercise-5]: ../5-managing-agents/ +[exercise-7]: ../7-foundry-toolkit/ +[github-copilot]: https://github.com/features/copilot +[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/chat/copilot-chat +[agent-mode]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/pt-br/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/pt-br/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..5a05e05d --- /dev/null +++ b/docs/pt-br/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "Preparar um projeto e um modelo" +description: "Exporte o catálogo da Tailspin e teste um modelo implantado em relação aos critérios de aceitação do Backer Concierge." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Opcional: Incorporar o Foundry][overview] | +|:--| + +Este primeiro módulo prepara os dados e o modelo para o Backer Concierge usando o VS Code e o Microsoft Foundry Toolkit. Trabalhe no seu próprio repositório da Tailspin Toys usado no workshop obrigatório. + +## Objetivos + +- Exportar o catálogo e identificar os limites das informações disponíveis. +- Preparar um projeto do Foundry e selecionar um modelo de acordo com os critérios de aceitação e a cota. +- Verificar o comportamento de fundamentação no Model Playground antes de escrever o código do agente. + +## Cenário + +Os apoiadores da Tailspin querem recomendações em que possam confiar. Quem gosta de quebra-cabeças espera títulos reais e avaliações precisas, não totais de financiamento inventados. O assistente precisa respeitar claramente os limites do catálogo e ter o hábito de fazer uma pergunta útil em vez de adivinhar o que um apoiador quer. + +## Preparar o espaço de trabalho + +O toolkit traz a descoberta de modelos, a implantação, a engenharia de prompts, a avaliação e a implantação de agentes para o VS Code. O acesso ao Azure e uma branch de funcionalidade sem alterações pendentes preparam o trabalho a seguir. + +> [!IMPORTANT] +> O Foundry Toolkit e os agentes hospedados estão em versão prévia pública. Este módulo cria recursos do Azure sujeitos a cobrança. Confirme as permissões da assinatura, a região, a cota e o custo estimado antes de aprovar a criação. A [limpeza][cleanup] está disponível mesmo se você parar antes de criar um agente. + +1. Confirme o acesso a uma assinatura do Azure. As [contas gratuitas do Azure com US$ 200 em crédito][azure-free] e o [Azure for Students com US$ 100 em créditos][azure-students] são opções, sujeitas aos critérios de elegibilidade e aos limites de serviço. +2. No VS Code, selecione **Extensions** na barra de atividades, pesquise **Foundry Toolkit** e selecione **Install**. O ícone aparecerá na barra de atividades. +3. Selecione o ícone **Azure**, selecione **Sign in to Azure…** e escolha a assinatura para o projeto do Foundry. Com o toolkit autenticado, o Copilot pode usar a [Microsoft Foundry Skill][foundry-skill] para preparar recursos por meio de uma conversa. +4. No espaço de trabalho da Tailspin Toys, abra **Terminal** > **New Terminal** ou pressione Control+\` (Mac) ou Ctrl+\` (Windows/Linux). Confirme que o trabalho anterior foi registrado em commits e enviado ao repositório remoto e, em seguida, crie a branch de funcionalidade: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. Abra uma nova conversa no Copilot Chat no modo **Agent** e peça: + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. Confirme que o Copilot apresenta **Add a Backer Concierge assistant for catalog questions**. Os critérios de aceitação exigem respostas fundamentadas, nenhum número de financiamento inventado, uma pergunta de esclarecimento e uma interface acessível com cobertura de ponta a ponta. + +## Gerar a exportação do catálogo + +O script de exportação do catálogo fornece a fonte de dados que fundamenta as respostas do agente. + +1. No terminal do repositório da Tailspin Toys, execute as migrações, preencha os dados iniciais e grave `db/catalog.json`: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. Abra `db/catalog.json` e confirme que ele contém vinte e um jogos, cada um com título, descrição, categoria, editora e avaliação em estrelas, além de um campo `note` que descreve as informações ausentes. Totais de financiamento, números de apoiadores, níveis de contribuição e datas de lançamento não estão presentes; o agente deve respeitar esse limite. + +## Configurar um projeto do Foundry + +O projeto contém o modelo e, posteriormente, o agente hospedado. Ao retomar este módulo, use o mesmo projeto em vez de criar outro. + +1. Selecione **Foundry Toolkit** na barra de atividades, expanda **Help and Feedback** e selecione **Ask Copilot**. Confirme o modelo de sua escolha no menu suspenso e envie o prompt `/foundrytk-quick-start` gerado. + + ![Captura de tela mostrando a sequência de início rápido do Foundry Toolkit.](../../../_images/vscode-foundry-setup.png) + +2. No fluxo interativo, responda a **Where are you starting from?** com **Set up Foundry** e, em seguida, a **What do you have already?** com **I have an Azure subscription or Foundry resources**. +3. Revise as aprovações de ferramentas. Se os comandos propostos e seu escopo forem adequados, selecione **Allow azmcp …** para esta sessão para reduzir as solicitações repetidas de aprovação. +4. Em **Microsoft Foundry: Create Project**, selecione **Create new resource group** em **Choose a resource group**, insira `rg-tailspin-toys`, escolha uma região que ofereça o modelo pretendido e insira `tailspin-toys` em **Enter project name**. `East US 2` e `Sweden Central` são opções iniciais com ampla disponibilidade de modelos; a disponibilidade atual e a cota determinam a escolha efetiva. Se estiver retomando o trabalho, selecione o projeto existente. +5. Aguarde a notificação de implantação bem-sucedida. No toolkit, expanda **My Resources** e confirme que este projeto é o padrão. + +## Descobrir e implantar um modelo + +Seguir regras e fundamentar as respostas importa mais aqui do que escolher o maior ou mais recente modelo. A issue fornece critérios concretos para comparar velocidade, fidelidade, disponibilidade regional e cota. + +1. No Copilot Chat, selecione **+**, depois **GitHub Issues**, e anexe **Add a Backer Concierge assistant for catalog questions**. Envie: + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. Leia as recomendações e escolha o modelo mais adequado aos requisitos e à cota disponível. Peça ao Copilot para implantá-lo: + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. Confirme o projeto, a implantação, a capacidade e o custo antes de aprovar. Se for adequado após revisar o escopo, selecione **Allow az …** para esta sessão para reduzir as solicitações repetidas. +4. Selecione **Foundry Toolkit**, expanda **My Resources** e selecione **Models**. Confirme que o modelo implantado aparece no Foundry. A captura de tela é um exemplo; sua região pode oferecer um modelo diferente. + + ![Captura de tela mostrando um exemplo de implantação de modelo no Foundry Toolkit.](../../../_images/vscode-model-deployed.png) + +## Testar o modelo implantado + +O Model Playground não tem o arquivo do catálogo. Um subconjunto reduzido de nove jogos no prompt de sistema é suficiente para testar se o modelo obedece às regras de fundamentação. + +1. Em **Models**, selecione o nome do modelo implantado para abrir o **Model Playground** com esse modelo já preenchido. Cole o seguinte prompt de sistema: + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. Teste a fundamentação com `I love puzzle games about tracking down bugs. What should I back?` Espere títulos reais da lista com informações corretas. +3. Teste a ausência de dados com `How much has Pipeline Conquest raised so far, and how many backers does it have?` Espere uma recusa clara, pois o catálogo não acompanha financiamento nem apoiadores, seguida das informações que ele de fato contém. +4. Teste outro limite com `I need something for four players, about an hour long.` Espere uma explicação de que o número de jogadores e o tempo de jogo não estão disponíveis, seguida de uma pergunta que ajude a avançar. +5. Teste a pressão por itens fora do catálogo com `Do you have Wingspan? If not, what's the closest thing you've got?` Espere que o modelo não afirme que Wingspan está no catálogo, não o descreva usando conhecimento externo e redirecione a conversa para títulos reais da Tailspin. +6. Teste a falta de especificidade com `Recommend me something good.` Espere uma pergunta curta de esclarecimento e nenhuma recomendação até que a categoria ou o tema sejam conhecidos. +7. Teste a classificação com `What are your three highest rated games?` Espere Deployment Dynasty e Script Strike com 5.0, seguidos de Code Quest Odyssey com 4.8, na ordem correta e com os números corretos. +8. Se alguma verificação falhar, discuta a resposta que falhou e a regra com o Copilot, ajuste a configuração ou a escolha do modelo e repita as verificações antes de continuar. + +## Marco de conclusão + +Você preparou o espaço de trabalho do VS Code, exportou o catálogo, criou um projeto do Foundry e testou um modelo implantado em relação às regras de fundamentação do Backer Concierge. O marco de conclusão deste módulo é um modelo que recomenda jogos reais do catálogo sem inventar informações ausentes; ainda não há um agente implantado. + +Em seguida, você usará o mesmo projeto `tailspin-toys` e a implantação do modelo selecionada para criar e implantar o agente. Se parar aqui, [limpe os recursos do Azure][cleanup] para evitar custos contínuos. + +| [Próximo módulo: Criar e implantar um agente →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#limpar-os-recursos +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/pt-br/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/pt-br/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..bbfe158f --- /dev/null +++ b/docs/pt-br/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "Criar e implantar um agente" +description: "Gere a estrutura inicial e depure o Backer Concierge no VS Code; depois, implante e teste-o como agente hospedado do Foundry." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Módulo anterior: Preparar um projeto e um modelo][previous-lesson] | +|:--| + +Este módulo usa o catálogo e o modelo testado de [Preparar um projeto e um modelo][previous-lesson]. O Microsoft Foundry Toolkit e seu agente personalizado **AIAgentExpert** orientam a criação local e a implantação hospedada no VS Code. + +## Objetivos + +- Gerar a estrutura inicial de um agente fundamentado no catálogo no espaço de trabalho existente da Tailspin Toys. +- Depurar o comportamento local com o Agent Inspector. +- Implantar no projeto existente do Foundry e verificar o agente hospedado. + +## Cenário + +Uma recomendação confiável precisa resistir a mais de uma conversa. A Tailspin Toys precisa que o assistente mantenha os limites do catálogo quando os apoiadores fazem perguntas vagas ou insistem em detalhes de financiamento indisponíveis. Um assistente hospedado deve se comportar com a mesma confiabilidade de um testado em um ambiente privado. + +## Retomar o espaço de trabalho + +O agente usa a implantação de modelo existente; não há um novo projeto do Foundry a criar. + +1. Abra o mesmo repositório da Tailspin Toys no VS Code em `foundry-agent-vscode`. Confirme que `db/catalog.json` existe e que o projeto `tailspin-toys` e a implantação do modelo testado estão visíveis em **Foundry Toolkit** > **My Resources**. +2. Confirme que o [marco de conclusão anterior][previous-lesson] foi atingido. Se os recursos foram removidos, conclua novamente a preparação do projeto e do modelo antes de prosseguir. +3. Instale a Azure Developer CLI (`azd`) se ela ainda não estiver disponível. A implantação de agentes hospedados usa essa ferramenta; escolha apenas o comando para o seu sistema operacional: + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. Faça login na assinatura usada pelo projeto existente: + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> Os agentes hospedados e o Foundry Toolkit estão em versão prévia pública. A implantação cria recursos sujeitos a cobrança. Confirme a assinatura, as permissões, a região, a cota e o custo estimado antes de aprovar comandos. + +## Criar e depurar o agente + +O toolkit gera a estrutura inicial do código no repositório atual e abre uma conversa especializada no Copilot Chat. O Agent Inspector torna visíveis as solicitações locais, os eventos e as chamadas de ferramentas antes da implantação. + +1. Selecione **Foundry Toolkit**, expanda **Developer Tools**, expanda **+ Build** e selecione **+ Create Agent**. Em **Create Agent**, selecione **Code an agent with Copilot**. + + ![Captura de tela mostrando a página de criação de agente.](../../../_images/vscode-create-agent.png) + +2. Na nova conversa, confirme que ela muda para **AIAgentExpert**. Substitua o prompt gerado pelo prompt personalizado e envie-o: + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. Revise o código gerado em `agent/backer-concierge`. Confirme que o catálogo está incluído no agente a ser implantado, que os testes específicos passam e que nenhuma credencial ou arquivo de ambiente local será incluído nos commits. +4. Selecione **Run and Debug** na barra de atividades e inicie o depurador com F5. Confirme que o **Agent Inspector** carrega e se conecta ao servidor do agente. +5. Reutilize os seis prompts de [Testar o modelo implantado][model-tests]. Verifique as respostas em relação ao `db/catalog.json` completo, em vez de presumir que a classificação do subconjunto de nove jogos corresponde à classificação do catálogo completo. +6. Alterne entre **Input & Output**, **Events** e **Tools** para inspecionar os dados das solicitações e respostas, os eventos da sessão e as chamadas de ferramentas. Se o comportamento violar os critérios de aceitação, peça ao Copilot para corrigi-lo e execute novamente os testes específicos e as verificações do Inspector antes de implantar. + + ![Captura de tela mostrando o fluxo de depuração local do agente.](../../../_images/vscode-agent-debug.png) + +## Implantar e testar o agente hospedado + +A transferência **Go production** empacota o agente existente para o Foundry. Ela não transforma o futuro proxy do site em um serviço público pronto para produção. + +1. Na conversa de criação de agente do Copilot Chat, selecione **Go production**, substitua o prompt padrão pelo seguinte e envie-o: + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![Captura de tela mostrando as opções de transferência do agente AIAgentExpert.](../../../_images/vscode-go-production-handoff.png) + +2. Revise a conversa e o terminal para conferir os parâmetros e as aprovações de comandos. Confirme que a implantação tem como destino o projeto `tailspin-toys` existente e revise os recursos sujeitos a cobrança antes de aprovar. +3. Se o Copilot oferecer uma suíte de avaliação, você pode aceitá-la e executá-la como verificação adicional. +4. Selecione **Foundry Toolkit**, expanda **My Resources** e selecione **Agents**. Na guia **Agents**, mude para **Hosted Agent**. + + ![Captura de tela mostrando o agente hospedado implantado.](../../../_images/vscode-agent-deployed.png) + +5. Selecione o nome do agente e confirme que o status da implantação é **Running**. Mude para **Playground** e repita as verificações de fundamentação, dados ausentes, itens fora do catálogo, falta de especificidade e classificação em relação ao catálogo implantado. + + ![Captura de tela mostrando uma resposta do agente hospedado implantado.](../../../_images/vscode-agent-response.png) + +6. Se a implantação ou as respostas falharem, inspecione o status informado e os logs com o Copilot, corrija a falha no projeto existente e repita as verificações. Não prossiga com uma implantação não verificada. + +## Marco de conclusão + +Você criou a estrutura inicial do Backer Concierge, depurou sua fundamentação no catálogo com o Agent Inspector, implantou o agente no Foundry pelo repasse **Go production** e testou novamente a versão hospedada no Playground. O marco de conclusão deste módulo é um agente hospedado em execução que respeita o catálogo sem inventar informações ausentes. + +Em seguida, você usará o mesmo projeto `tailspin-toys`, a implantação do modelo e o agente hospedado para conectar o agente ao site. Se parar aqui, [limpe os recursos do Azure][cleanup] para evitar custos contínuos. + +| [Próximo módulo: Conectar o agente ao site →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#testar-o-modelo-implantado +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#limpar-os-recursos diff --git a/docs/pt-br/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/pt-br/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..336e8d83 --- /dev/null +++ b/docs/pt-br/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "Conectar o agente ao site" +description: "Conecte o Backer Concierge hospedado por meio de um proxy local e teste um widget de chat acessível." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← Módulo anterior: Criar e implantar um agente][previous-lesson] | +|:--| + +Este módulo conecta o agente hospedado de [Criar e implantar um agente][previous-lesson] à Tailspin Toys. O Copilot Chat no VS Code cria uma integração local, não um endpoint público de produção. + +## Objetivos + +- Manter as credenciais e os identificadores de conversa do Foundry protegidos por um proxy local no servidor. +- Adicionar um widget de chat acessível com continuidade de conversa. +- Verificar o backend e a experiência completa antes de limpar os recursos. + +## Cenário + +Os apoiadores devem poder pedir recomendações ao assistente sem sair do catálogo. Uma conversa precisa manter o contexto, funcionar com teclado e proteger os detalhes privados de conexão. A confiança depende tanto de recomendações honestas quanto de uma experiência segura e acessível. + +## Retomar o espaço de trabalho + +O agente hospedado existente é o destino da integração. A Tailspin Toys é um site estático totalmente pré-renderizado, portanto o código do navegador não pode armazenar as credenciais do agente com segurança. + +1. Abra o mesmo repositório da Tailspin Toys em `foundry-agent-vscode` no VS Code. Confirme que o agente hospedado do marco anterior ainda está **Running** no projeto `tailspin-toys` existente e que o login local no Azure está direcionado à assinatura desse projeto. +2. Abra o Copilot Chat no modo **Agent** comum em vez de **AIAgentExpert**. Anexe **Add a Backer Concierge assistant for catalog questions** selecionando **+**, depois **GitHub Issues**, e escolhendo a issue. + +## Criar e verificar o proxy local + +Um proxy local do Azure Functions em `/api` armazena os detalhes de conexão e encaminha as solicitações enquanto o site é executado localmente. O Copilot pode usar **Azure skills** para prepará-lo e validá-lo. + +> [!IMPORTANT] +> Este proxy do workshop é apenas para desenvolvimento local. Não o implante como um endpoint público anônimo. A produção exige autenticação específica da aplicação e controles contra abuso, incluindo limites de taxa ou cotas, restrições de CORS, monitoramento e controles de custo. + +1. Peça ao Copilot para criar o proxy: + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. Revise as alterações antes de aceitá-las. Confirme que as credenciais e os identificadores de conversa do Foundry permanecem no servidor, que as configurações locais estão excluídas do controle de versão, que as solicitações têm limites e que os testes específicos passam. +3. Comprove que o backend funciona antes de criar a interface: + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. Verifique a resposta no terminal. Espere um JSON válido com uma propriedade `response` contendo a resposta, sem informações de preço inventadas e sem credenciais ou identificadores internos de conversa. Se uma verificação falhar, peça ao Copilot para corrigi-la e repita o teste do backend. +5. Selecione **Keep** para manter as alterações e use **/clear** para começar uma nova conversa para o widget no mesmo repositório e na mesma branch. Mantenha a configuração do proxy local e a conexão com o agente hospedado existente. + +## Criar e testar o widget + +A interface agora tem um backend verificado. Os testes de ponta a ponta verificam tanto a usabilidade quanto os limites das informações do catálogo. + +1. Peça ao Copilot para adicionar o widget: + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Captura de tela mostrando o widget de chat Backer Concierge em ação](../../../_images/tailspin-toys-backer-concierge-agent.png) + +2. Mantenha a função e o site em execução e verifique a experiência completa: + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. Revise os resultados dos testes e as alterações em relação aos critérios de aceitação da issue: respostas fundamentadas, nenhum número de financiamento inventado, uma pergunta de esclarecimento, interface acessível e cobertura de ponta a ponta. Confirme que as falhas foram corrigidas e que as verificações afetadas foram executadas novamente. + +## Marco de conclusão + +Você criou um proxy local que protege as credenciais, conectou um widget de chat acessível e verificou todo o fluxo de conversa com o Backer Concierge hospedado. O marco de conclusão deste módulo é uma integração com o site testada localmente que preserva os limites do catálogo e mantém credenciais e identificadores internos do Foundry fora do navegador. Esta não é uma implantação em produção do proxy nem do site. + +Quando terminar de experimentar, pare os serviços locais e [limpe os recursos do Azure][cleanup] para evitar custos contínuos. Depois, retorne à [visão geral do VS Code][vscode-overview] do workshop principal. + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#limpar-os-recursos +[vscode-overview]: ../../ diff --git a/docs/pt-br/vscode/7-foundry-toolkit/README.md b/docs/pt-br/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..ea55841e --- /dev/null +++ b/docs/pt-br/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: pt-br/vscode/7-foundry-toolkit +title: "Opcional: Incorporar o Foundry" +description: "Crie um Backer Concierge fundamentado no catálogo com o VS Code e o Microsoft Foundry Toolkit em três módulos focados." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Lição anterior: Iterar sobre o trabalho do GitHub Copilot][previous-lesson] | +|:--| + +A trilha obrigatória do VS Code está concluída após o Exercício 6. Esta extensão opcional usa o GitHub Copilot Chat e o Microsoft Foundry Toolkit no VS Code para transformar o catálogo da Tailspin em um Backer Concierge, implantá-lo como agente hospedado e conectá-lo ao site por meio de um proxy local. + +## Cenário + +Os apoiadores fazem perguntas que os filtros não conseguem responder: qual jogo combina com alguém que adora trocadilhos com git, ou o que torna um jogo de quebra-cabeça mais adequado do que outro? A Tailspin Toys precisa de um assistente que recomende títulos reais do catálogo, faça uma pergunta de esclarecimento quando necessário e conquiste a confiança ao admitir quando os números de financiamento ou outros fatos não estão disponíveis. + +## Módulos + +Cada módulo termina com uma etapa funcional concluída. O mesmo repositório do participante, a mesma branch de funcionalidade e o mesmo projeto do Foundry são usados nos três módulos; o projeto não é recriado entre eles. + +| Módulo | Marco de conclusão | +|--------|-----------------------| +| [1. Preparar um projeto e um modelo][module-1] | Catálogo exportado e modelo implantado testado em relação às regras de fundamentação | +| [2. Criar e implantar um agente][module-2] | Agente local depurado e agente hospedado testado | +| [3. Conectar o agente ao site][module-3] | Proxy local e widget acessível testados de ponta a ponta | + +> [!IMPORTANT] +> O Microsoft Foundry Toolkit e os agentes hospedados estão em versão prévia pública. Estes módulos criam recursos do Azure sujeitos a cobrança, incluindo uma implantação de modelo e um agente hospedado. Permissões da assinatura, disponibilidade regional, cota e custo podem limitar a participação. + +## Antes de começar + +A extensão usa como base o seu repositório da Tailspin Toys, não o repositório de documentação do workshop. + +1. Confirme que o trabalho obrigatório do workshop foi salvo, registrado em commits e enviado ao repositório remoto antes de iniciar a funcionalidade opcional. +2. Comece por [Preparar um projeto e um modelo][module-1]. Se estiver retomando o trabalho, reabra o repositório do Tailspin Toys na branch `foundry-agent-vscode` e confirme que o projeto `tailspin-toys` e a respectiva implantação do modelo ainda existem em **Foundry Toolkit** > **My Resources**. +3. Ao parar após qualquer módulo, siga [Limpar os recursos][cleanup], a menos que decida manter os recursos para o próximo módulo e aceite os custos contínuos. + +## Limpar os recursos + +Quando terminar de experimentar em qualquer marco de conclusão, remova os recursos do Azure para evitar custos indesejados. A limpeza remove recursos necessários para os módulos seguintes, portanto continuar depois exige recriá-los. + +> [!WARNING] +> Só exclua `rg-tailspin-toys` se ele for exclusivo deste exercício e não contiver recursos que você queira manter. Excluir um grupo de recursos compartilhado removeria também recursos não relacionados. +> +> Se você aprovou outro nome de grupo de recursos no módulo 1, substitua `rg-tailspin-toys` por esse nome em todos os comandos a seguir. + +1. Pare, no respectivo terminal, qualquer sessão de depuração do Agent Inspector, host do Azure Functions ou servidor de desenvolvimento do Astro que você tenha iniciado. +2. Se você implantou o agente hospedado no módulo 2, abra um terminal no diretório do agente gerado que contém `azure.yaml`, selecione o mesmo ambiente `azd` e execute: + + ```bash + azd down --purge + ``` + +3. Verifique a assinatura selecionada e se o grupo de recursos do workshop ainda existe: + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + Se o comando retornar `false`, a limpeza está concluída. Se retornar `true`, inspecione os recursos do grupo: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Verifique se todos os recursos restantes pertencem a este exercício. Se você parou após o módulo 1, o projeto e o modelo do Foundry ainda precisam de limpeza, mesmo que você não tenha implantado um serviço `azd`. + +4. Se o grupo de recursos exclusivo do workshop ainda existir e contiver apenas recursos que você pretende remover, execute: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Como `--no-wait` retorna antes de a exclusão terminar, execute novamente o comando a seguir até que ele retorne `false`: + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## Recursos + +- [Foundry Toolkit para Visual Studio Code][foundry-toolkit] +- [Visão geral da extensão de agentes do Microsoft Foundry][foundry-extension] + +| [Próximo módulo: Preparar um projeto e um modelo →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #limpar-os-recursos +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/pt-br/vscode/README.md b/docs/pt-br/vscode/README.md new file mode 100644 index 00000000..b9345bf2 --- /dev/null +++ b/docs/pt-br/vscode/README.md @@ -0,0 +1,48 @@ +--- +slug: pt-br/vscode +title: "VS Code" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +O **[GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)** no VS Code traz o GitHub Copilot para o editor de código que você já usa. Trabalhando no Visual Studio Code (e no GitHub Codespaces), você conduzirá o Copilot Chat no modo de agente, conectará ferramentas externas por meio do MCP e contará com agentes personalizados — tudo sem sair do IDE, onde o Copilot tem uma visão completa dos arquivos, do terminal e dos problemas. + +Você começará adicionando instruções personalizadas e observando o Copilot segui-las; depois, usará o modo de agente para criar uma funcionalidade de filtragem que abrange a interface, a camada de dados e os testes. Em seguida, conectará o servidor MCP do Playwright e deixará o Copilot controlar um navegador para testar a funcionalidade antes de abrir um pull request. Por fim, revisará e usará um agente personalizado para o trabalho de acessibilidade e, então, monitorará, orientará e iterará sobre as alterações do Copilot — tudo sem sair do editor. + +## Exercícios + +| Exercício | Tema | Descrição | +|----------|-------|-------------| +| [0. Pré-requisitos][ex0] | Configuração | Crie seu repositório e seu codespace | +| [1. Instruções personalizadas][ex1] | Contexto | Adicione e verifique instruções personalizadas no VS Code | +| [2. Modo de agente][ex2] | Geração de código | Crie uma funcionalidade de filtragem com o modo de agente | +| [3. MCP com Playwright][ex3] | Ferramentas externas | Teste a funcionalidade em um navegador com o servidor MCP do Playwright | +| [4. Agentes personalizados][ex4] | Agentes especializados | Revise e use agentes personalizados | +| [5. Gerenciamento de agentes][ex5] | Monitoramento | Monitore e oriente sessões de agentes | +| [6. Iteração][ex6] | Revisão | Revise o trabalho do Copilot localmente e escolha os próximos passos | +| [Opcional: Incorporar o Foundry][foundry-toolkit] | Agentes de IA | Prepare um modelo, implante um agente e conecte-o ao site em três módulos com o VS Code e o Foundry Toolkit | + +## Pré-requisitos + +Antes de participar deste workshop, certifique-se de ter: + +- [ ] Uma conta do GitHub com um plano **Copilot Student, Pro, Pro+, Business ou Enterprise** ativo +- [ ] Acesso ao GitHub Codespaces + +> [!TIP] +> Não tem um plano pago? Estudantes verificados podem obter o GitHub Copilot gratuitamente por meio do [GitHub Education][callout-student-plan-education]. O plano **Copilot Student** inclui os recursos de agente, MCP, revisão de código e Copilot CLI usados neste workshop — portanto, você pode concluir todas as trilhas com ele. + +[callout-student-plan-education]: https://github.com/education/students +## Primeiros passos + +**[Comece pelo Exercício 0: Pré-requisitos →][ex0]** + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-agent-mode/ +[ex3]: 3-mcp/ +[ex4]: 4-custom-agents/ +[ex5]: 5-managing-agents/ +[ex6]: 6-iterating/ +[foundry-toolkit]: 7-foundry-toolkit/ diff --git a/docs/vscode/6-iterating.md b/docs/vscode/6-iterating.md index 9d85931d..8b9a78ea 100644 --- a/docs/vscode/6-iterating.md +++ b/docs/vscode/6-iterating.md @@ -3,10 +3,11 @@ title: "Exercise 6 - Iterating on GitHub Copilot's work" authors: - geektrainer lastUpdated: 2026-06-30 +next: false --- -| [← Previous lesson: Monitoring and managing agents][previous-lesson] | [Next lesson: (Optional) Create a Backer Concierge AI Agent →][next-lesson] | -| :-- | --: | +| [← Previous lesson: Monitoring and managing agents][previous-lesson] | +| :-- | ## Reviewing the work @@ -63,7 +64,7 @@ Congratulations — you've completed the VS Code harness! Through this lab you: ## Review and next steps -This wraps up the required part of the VS Code harness. If you want to keep going, [Exercise 7][exercise-7] is an optional lesson where you'll use the Microsoft Foundry toolkit to build a hosted backer concierge AI agent. Otherwise, feel free to stop here. +This wraps up the required VS Code harness. You can stop here with the workshop complete. If you'd like to expand your perspective on Copilot's agent capabilities, the other harnesses cover related scenarios through different surfaces: @@ -72,6 +73,8 @@ If you'd like to expand your perspective on Copilot's agent capabilities, the ot You can also keep building on what you started here. [awesome-copilot][awesome-copilot] is a great source for more instruction files, custom agents, and skills you can adapt to your own projects. +For an optional extension, [Optional: Incorporate Foundry][exercise-7] uses VS Code and Microsoft Foundry Toolkit to prepare a model, deploy a Backer Concierge, and connect it to the site. + ## Resources - [GitHub Copilot][github-copilot] @@ -80,11 +83,10 @@ You can also keep building on what you started here. [awesome-copilot][awesome-c --- -| [← Previous lesson: Managing agents][previous-lesson] | [Next lesson: (Optional) Create a Backer Concierge AI Agent →][next-lesson] | -|:--|--:| +| [← Previous lesson: Managing agents][previous-lesson] | +|:--| [previous-lesson]: ../5-managing-agents/ -[next-lesson]: ../7-foundry-toolkit/ [exercise-4]: ../4-custom-agents/ [exercise-5]: ../5-managing-agents/ [exercise-7]: ../7-foundry-toolkit/ diff --git a/docs/vscode/7-foundry-toolkit.md b/docs/vscode/7-foundry-toolkit.md deleted file mode 100644 index 3bfc3211..00000000 --- a/docs/vscode/7-foundry-toolkit.md +++ /dev/null @@ -1,390 +0,0 @@ ---- -title: "Exercise 7 - (Optional) Create a Backer Concierge AI Agent" -authors: - - juliamuiruri4 -lastUpdated: 2026-08-03 ---- - -| [← Previous lesson: Iterating on GitHub Copilot's work][previous-lesson] | -|:--| - -In this optional lesson you'll take the Tailspin catalog and build an AI agent on top of it, discovering and deploying a model, scaffolding an agent locally, deploying it as a Foundry hosted agent and wiring it into the site. - -> [!IMPORTANT] -> Microsoft Foundry Toolkit and hosted agents are in public preview. -> -> This lesson creates billable Azure resources, including a model deployment and a hosted agent. Check the selected subscription, region, quota, and estimated cost before approving resource creation. Complete the cleanup section when you finish. - -Before you start this exercise, you need a few tools. - -## Prerequisites & setup - -1. An Azure Subscription - - - [Free Azure subscription with $200 credit][azure-free] - - [Azure for Students with $100 credits][azure-students] - -1. Foundry Toolkit Extension for VS Code - - The foundry toolkit extension brings the full agent workflow — model discovery, deployment, prompt engineering, evaluation, and agent deployment into the editor, so you don't leave the code to build the AI feature. Install the extension from the Marketplace: - - - Open VS Code and select **Extensions** from the Activity Bar. - - Search for **Foundry Toolkit**. - - Select **Install**. - - After installation, the Foundry Toolkit icon appears in the Activity Bar. - -1. Sign in to Azure - - Select the **Azure** icon in the Activity Bar. - - Select **Sign in to Azure…**. - - Choose the subscription you'll use for the Foundry project. - - With the toolkit installed and authenticated, Copilot can use the [Microsoft Foundry Skill][foundry-skill] to provision resources and models for you in a conversational style, instead of another portal experience. - -1. **Azure Developer CLI (`azd`)** - - Deploying your agent as a Foundry hosted agent is driven by `azd`, so install it before you start: - - ```bash - # macOS / Linux - curl -fsSL https://aka.ms/install-azd.sh | bash - - # Windows (PowerShell) - winget install microsoft.azd - ``` - - then sign in: - - ```bash - azd auth login - ``` - -All set. - -## Scenario - -In a previous exercise, you added a new feature that allows users to filter by category and publisher. But filtering only helps backers who already know what they want. The ones emailing support ask things like *which of your games would suit someone who loves git puns?*. Questions with no dropdown answers. In this exercise you build a **Backer Concierge** agent that answers those questions, grounded in the Tailspin catalog so it never invents a game or a funding number. - -Open a new Copilot Chat in **Agent** mode and ask: - -```text -Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. -``` - -Copilot reads the backlog and surfaces **Add a Backer Concierge assistant for catalog questions.** Note that the criteria are clear — grounded answers, no invented funding numbers, one clarifying question, and an accessible UI with e2e coverage. - -## Generate the catalog export - -The agent needs the catalog as a file it can read. That export already exists as a script. - -1. Open a new terminal by selecting **Terminal** > **New Terminal**, or press Control+\` (Mac) or Ctrl+\` (Windows/Linux). - -1. Make sure any work from the previous lesson is committed or pushed. This next command creates and switches to a new branch for this feature work: - - ```bash - git checkout main - git pull - git checkout -b foundry-agent-vscode - ``` - -1. Migrate, seed and write `db/catalog.json`: - - ```bash - npm install - npm run db:setup - npm run db:export - ``` - -Open `db/catalog.json`. Twenty-one games - each with a title, description, category, publisher and star rating, plus a `note` field stating what the catalog *doesn't* contain. Nothing about funding totals, backer counts, pledge tiers, or release dates. That absence is exactly the boundary your agent has to respect. - -## Set up a Foundry project - -Your agent needs a place to live, so let's set up a project on Microsoft Foundry. - -1. Select the **Foundry Toolkit** icon in the Activity Bar. -1. Expand **Help and Feedback**, then select **Ask Copilot**. - - This drops a prompt into Copilot Chat that uses the `/foundrytk-quick-start` skill to guide you through setup. Confirm your model of choice from the dropdown and send the prompt. - - ![Screenshot showing the Foundry Toolkit quickstart sequence.](../_images/vscode-foundry-setup.png) - -1. Copilot starts an interactive workflow. Answer as follows: - - - **Where are you starting from?** → *Set up Foundry* - - **What do you have already?** → *I have an Azure subscription or Foundry resources* - - > [!TIP] - > Select **Allow azmcp …** for this session to cut down on repeated approval prompts. - -1. The **Microsoft Foundry: Create Project** wizard opens in VS Code. Fill it in: - - - **Choose a resource group** → *Create new resource group* - - **Enter resource group name** → `rg-tailspin-toys` - - **Choose a location** → pick a region close to you that offers the models you want. `East US 2` and `Sweden Central` have the broadest model availability so if you're unsure, start there. - - **Enter project name** → `tailspin-toys` - - Once the project is created you'll get a notification that deployment succeeded. - -1. In the Foundry Toolkit view, expand **My Resources**. Your new project should be set as the default. - -## Discover, deploy and test a model - -The model you pick is a critical piece of the agent's behavior and capabilities. It's tempting to just grab the biggest, most capable model available and move on, but for a use case like this, biggest, newest and most expensive model won't necessarily be the most suitable. - -What actually matters is whether the model can follow rules reliably and its grounding fidelity - *will it obey hard rules about never inventing games, ratings, funding numbers ...* - -Rather than guessing from model reputation, hand Copilot the actual acceptance criteria from the issue and let it argue the trade-offs for you. - -- To attach the issue as context in Copilot Chat: - - Select **+**. - - Select **GitHub Issues**. - - Choose the **Add a Backer Concierge assistant for catalog questions** issue. - - Then use the following prompt: - - ```text - /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule - ``` - -Read through the recommendations and choose the model that best fits the requirements and your available quota. - -### Deploy model - -Next, ask Copilot to deploy the model with: - -```text -/microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. -``` - -If prompted, confirm project and deployment. - -> [!TIP] -> Select **Allow az …** for this session to cut down on repeated approval prompts. - -Once the model is deployed: - -- Select the **Foundry Toolkit** icon in the Activity Bar. -- Expand **My Resources**, then select **Models**. - - This will open the models page and your deployed model should show up under Foundry - - ![Screenshot showing an example model deployment in the Foundry Toolkit.](../_images/vscode-model-deployed.png) - - The model shown in the screenshot may differ from the one available in your region. - -You deployed the model purely on Copilot's recommendation, so before going any further, take a minute to test and validate that it meets your expectations. - -### Test deployed model - -The Model Playground doesn't have your catalog file, so for this test you'll paste a **trimmed 9-game subset** directly into the system prompt. That's enough to prove the model follows grounding rules. - -From the **Models** page, select the model name to open the **Model Playground** with the model pre-filled. - -
-Expand to view the system prompt - -```text -You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. - -CATALOG - -| Title | Category | Publisher | Rating | -| --- | --- | --- | --- | -| Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | -| Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | -| Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | -| Deployment Dynasty | Simulation | Ops Interactive | 5.0 | -| Script Strike | Action | CodeForge Studios | 5.0 | -| Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | -| Repo Rulers | Strategy | Ops Interactive | 4.1 | -| Server Siege | Strategy | GitHub Games | 3.3 | -| Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | -``` - -
- -Your test cases may include: - -1. **Grounded in our data?** - - Prompt: `I love puzzle games about tracking down bugs. What should I back?` - - Expected: Names real titles from the list with the correct game information for each. - -1. **Hallucination trap** - - Prompt 1: `How much has Pipeline Conquest raised so far, and how many backers does it have?` - - Expected: A clean refusal — the catalog doesn't track funding or backers — followed by what it *does* know - - Prompt 2: `I need something for four players, about an hour long.` - - Expected: Explains the catalog has no player count or play time, then asks one actionable follow-up question - -1. **Out-of-catalog pressure** - - Prompt: `Do you have Wingspan? If not, what's the closest thing you've got?` - - Expected: Says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to real Tailspin titles. - -1. **Vagueness — does it ask, or guess?** - - Prompt: `Recommend me something good.` - - Expected: One short clarifying question — no recommendation until it knows category or theme. - -1. **Ranking accuracy** - - Prompt: `What are your three highest rated games?` - - Expected: Deployment Dynasty and Script Strike at 5.0, then Code Quest Odyssey at 4.8 — correct order, correct numbers. - -Your model is ready. Next, create the agent. - -## Create the Backer Concierge agent locally - -1. Select the **Foundry Toolkit** icon in the Activity Bar. -1. Expand **Developer Tools**, expand **+ Build**, then select **+ Create Agent**. - - The **Create Agent** page opens. Select **Code an agent with Copilot**. - - ![Screenshot showing the create agent page.](../_images/vscode-create-agent.png) - -This drops a prompt into a new Copilot Chat and automatically switches to the **AIAgentExpert** custom agent, which specializes in end-to-end Microsoft Foundry workflows. - -
-Expand to view the customized prompt - -```text -/foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. -``` - -
- -Copilot scaffolds and configures the agent in a few minutes, writing the generated code to `agent/`. Once it's done, use the **Agent Inspector** to debug and step through its behavior: - -1. Review the generated changes and confirm that the catalog is included in the deployable agent, the focused tests pass, and no credentials or local environment files will be committed. -1. Select **Run and Debug** in the Activity Bar. -1. Start the debugger (F5). -1. The Agent Inspector page loads and connects to your agent server. -1. Test your agent — reuse the prompts from the playground section above. -1. Switch between **Input & Output**, **Events**, and **Tools** to inspect the request/response payloads, individual session events, and any tool calls. - -![Screenshot showing local Agent debug workflow.](../_images/vscode-agent-debug.png) - -At this point your agent runs locally against the model you deployed to Foundry. Next, deploy the agent itself. - -## Deploy your Agent on Foundry - -Back in Copilot Chat, you'll see hand-off buttons for recommended next actions from the agent creation process. - -Select the **Go production** hand-off option, then replace the default prompt with: - -```text -/foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. -``` - -and submit the prompt. - -![Screenshot showing hand off options from the AIAgentExpert agent.](../_images/vscode-go-production-handoff.png) - -Copilot will prepare your agent code service as a Foundry hosted-agent deployment and start the deployment. Observe the chat and terminal in case it asks you to provide parameters or approve commands. - -> [!NOTE] -> If Copilot offers to set up an evaluation suite for the deployed agent, you can accept and work through it as a bonus step. - -- Select the **Foundry Toolkit** icon in the Activity Bar. -- Expand **My Resources**, then select **Agents**. -- On the **Agents** tab, switch to **Hosted Agent** to view your newly deployed agent. - - ![Screenshot showing the deployed hosted agent.](../_images/vscode-agent-deployed.png) - -- Select the agent name to open it in the hosted-agent playground, and confirm that its deployment status is **Running**. -- Switch to the **Playground** tab and test the hosted agent. - - ![Screenshot showing a response from the deployed hosted agent.](../_images/vscode-agent-response.png) - -## Wire the agent into the static site (proxy) - -Tailspin Toys is a fully pre-rendered static website, so it can't securely call the hosted agent without leaking the agent's credentials. For this workshop, you'll create a local Azure Functions proxy in `/api` that holds the connection details and forwards requests while you run the site locally. - -Copilot can use the **Azure skills** to prepare and validate the local proxy. You describe the outcome, review what it proposes, and approve the changes. - -> [!IMPORTANT] -> This workshop proxy is for local development only. Don't deploy it as an anonymous public endpoint. A production integration needs an application-specific authentication and abuse-control design, including appropriate rate limits or quotas, CORS restrictions, monitoring, and cost controls. - -1. In Copilot Chat in **Agent** mode, attach the Backer Concierge issue as context by selecting **+** > **GitHub Issues**, then ask: - - ```text - Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. - ``` - - Review what Copilot produces before accepting it. Confirm that credentials and Foundry conversation identifiers stay on the server, local settings are excluded from version control, requests are bounded, and the tests pass. - -1. Prove the backend works **before** building any UI: - - ```text - Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. - ``` - - Check the terminal for the response. It should be a valid JSON object with a `response` property containing the agent's answer. - - **Keep** the changes, and **/clear** the chat so you can start fresh for the next step. - -1. Build the chat widget. - - ```text - Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. - ``` - - ![Screenshot showing the Backer Concierge chat widget in action](../_images/tailspin-toys-backer-concierge-agent.png) - -1. Keep the Function and site running, then verify the complete experience: - - ```text - Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. - ``` - -## Clean up your resources - -When you're done experimenting, tear everything down to avoid any unwanted costs: - -```bash -azd down --purge -``` - -Or delete the resource group directly: - -```bash -az group delete --name rg-tailspin-toys --yes --no-wait -``` - -> [!WARNING] -> `azd down --purge` permanently removes the Foundry project, the model deployment, and the hosted agent. Only run it once you've finished exploring. - -## Summary - -In this lesson you took a feature request from the backlog all the way to a deployed AI agent wired into the product. Along the way you: - -- Generated a grounded data source (`db/catalog.json`) -- Chose a model from acceptance criteria and quota rather than reputation, then deployed it -- Validated grounding behavior in the Model Playground before writing any agent code -- Scaffolded and debugged the agent locally with the Agent Inspector -- Deployed it as a Foundry hosted agent and tested it in the playground -- Built a local server-side proxy that keeps Foundry credentials and conversation state out of the browser -- Added and tested an accessible Backer Concierge widget in the Tailspin Toys site - -## Resources - -- [Foundry Toolkit for Visual Studio Code][foundry-toolkit] -- [Microsoft Foundry agent extension overview][foundry-extension] - ---- -| [← Previous lesson: Iterating on GitHub Copilot's work][previous-lesson] | -|:--| - -[previous-lesson]: ../6-iterating/ -[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account -[azure-students]: https://azure.microsoft.com/free/students -[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md -[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview -[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension \ No newline at end of file diff --git a/docs/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..cfbcad78 --- /dev/null +++ b/docs/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "Prepare a project and model" +description: "Export the Tailspin catalog and test a deployed model against the Backer Concierge acceptance criteria." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Optional: Incorporate Foundry][overview] | +|:--| + +This first module prepares the data and model for the Backer Concierge using VS Code and Microsoft Foundry Toolkit. Work in your own Tailspin Toys repository from the required workshop. + +## Objectives + +- Export the catalog and identify its information boundaries. +- Prepare a Foundry project and select a model against acceptance criteria and quota. +- Verify grounding behavior in the Model Playground before writing agent code. + +## Scenario + +Tailspin backers want recommendations they can trust. A puzzle fan expects real titles and accurate ratings, not invented funding totals. The concierge needs a clear catalog boundary and a habit of asking one useful question rather than guessing what a backer wants. + +## Prepare the workspace + +The toolkit brings model discovery, deployment, prompt engineering, evaluation, and agent deployment into VS Code. Azure access and a clean feature branch prepare the work that follows. + +> [!IMPORTANT] +> Foundry Toolkit and hosted agents are in public preview. This module creates billable Azure resources. Confirm subscription permissions, region, quota, and estimated cost before approving creation. [Cleanup][cleanup] is available even if you stop before building an agent. + +1. Confirm access to an Azure subscription. [Free Azure accounts with $200 credit][azure-free] and [Azure for Students with $100 credits][azure-students] are options, subject to their eligibility and service limits. +2. In VS Code, select **Extensions** in the Activity Bar, search for **Foundry Toolkit**, and select **Install**. Its icon appears in the Activity Bar. +3. Select the **Azure** icon, select **Sign in to Azure…**, and choose the subscription for the Foundry project. With the toolkit authenticated, Copilot can use the [Microsoft Foundry Skill][foundry-skill] to prepare resources conversationally. +4. In your Tailspin Toys workspace, open **Terminal** > **New Terminal**, or press Control+\` (Mac) or Ctrl+\` (Windows/Linux). Confirm previous work is committed and pushed, then create the feature branch: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. Open a new Copilot Chat in **Agent** mode and ask: + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. Confirm Copilot surfaces **Add a Backer Concierge assistant for catalog questions**. The acceptance criteria require grounded answers, no invented funding numbers, one clarifying question, and an accessible UI with end-to-end coverage. + +## Generate the catalog export + +The catalog export script supplies the agent's grounded data source. + +1. In the Tailspin Toys repository terminal, migrate, seed, and write `db/catalog.json`: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. Open `db/catalog.json` and confirm it contains twenty-one games, each with a title, description, category, publisher, and star rating, plus a `note` field describing missing information. Funding totals, backer counts, pledge tiers, and release dates are absent; the agent must respect that boundary. + +## Set up a Foundry project + +The project holds the model and, later, the hosted agent. Resuming this module uses the same project rather than creating another. + +1. Select **Foundry Toolkit** in the Activity Bar, expand **Help and Feedback**, and select **Ask Copilot**. Confirm your model of choice in the dropdown and send the generated `/foundrytk-quick-start` prompt. + + ![Screenshot showing the Foundry Toolkit quickstart sequence.](../../_images/vscode-foundry-setup.png) + +2. In the interactive workflow, answer **Where are you starting from?** with **Set up Foundry**, then **What do you have already?** with **I have an Azure subscription or Foundry resources**. +3. Review tool approvals. If the proposed commands and their scope are appropriate, select **Allow azmcp …** for this session to reduce repeated approval prompts. +4. In **Microsoft Foundry: Create Project**, select **Create new resource group** for **Choose a resource group**, enter `rg-tailspin-toys`, choose a region offering your intended model, and enter `tailspin-toys` for **Enter project name**. `East US 2` and `Sweden Central` are starting candidates with broad model availability; current availability and quota determine the actual choice. If resuming, select your existing project instead. +5. Wait for the deployment-success notification. In the toolkit, expand **My Resources** and confirm this project is the default. + +## Discover and deploy a model + +Rule following and grounding matter more here than choosing the biggest or newest model. The issue provides concrete criteria for comparing speed, fidelity, regional availability, and quota. + +1. In Copilot Chat, select **+**, then **GitHub Issues**, and attach **Add a Backer Concierge assistant for catalog questions**. Send: + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. Read the recommendations and choose the model that best fits the requirements and available quota. Ask Copilot to deploy it: + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. Confirm the project, deployment, capacity, and cost before approving. If appropriate after reviewing scope, select **Allow az …** for this session to reduce repeated prompts. +4. Select **Foundry Toolkit**, expand **My Resources**, then select **Models**. Confirm the deployed model appears under Foundry. The screenshot is an example; your region may offer a different model. + + ![Screenshot showing an example model deployment in the Foundry Toolkit.](../../_images/vscode-model-deployed.png) + +## Test the deployed model + +The Model Playground does not have the catalog file. A trimmed nine-game subset in the system prompt is enough to test whether the model obeys grounding rules. + +1. From **Models**, select the deployed model name to open **Model Playground** with that model pre-filled. Paste the following system prompt: + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. Test grounding with `I love puzzle games about tracking down bugs. What should I back?` Expect real titles from the list with correct information. +3. Test missing data with `How much has Pipeline Conquest raised so far, and how many backers does it have?` Expect a clean refusal because the catalog does not track funding or backers, followed by what it does know. +4. Test another boundary with `I need something for four players, about an hour long.` Expect an explanation that player count and play time are unavailable, then one actionable follow-up question. +5. Test out-of-catalog pressure with `Do you have Wingspan? If not, what's the closest thing you've got?` Expect no claim that Wingspan is in the catalog, no description from outside knowledge, and a pivot to real Tailspin titles. +6. Test vagueness with `Recommend me something good.` Expect one short clarifying question and no recommendation until category or theme is known. +7. Test ranking with `What are your three highest rated games?` Expect Deployment Dynasty and Script Strike at 5.0, then Code Quest Odyssey at 4.8, in the correct order with correct numbers. +8. If any check fails, discuss the failing response and rule with Copilot, adjust the configuration or model choice, and repeat the checks before continuing. + +## Completion checkpoint + +You prepared the VS Code workspace, exported the catalog, created a Foundry project, and tested a deployed model against the Backer Concierge grounding rules. The checkpoint for this module is a model that recommends real catalog games without inventing missing information, not yet a deployed agent. + +Next, you'll use the same `tailspin-toys` project and selected model deployment to build and deploy the agent. If you're stopping here, [clean up your Azure resources][cleanup] to avoid ongoing costs. + +| [Next module: Build and deploy an agent →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#clean-up-your-resources +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..176f7b85 --- /dev/null +++ b/docs/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "Build and deploy an agent" +description: "Scaffold and debug the Backer Concierge in VS Code, then deploy and test it as a Foundry hosted agent." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Previous module: Prepare a project and model][previous-lesson] | +|:--| + +This module uses the catalog and tested model from [Prepare a project and model][previous-lesson]. Microsoft Foundry Toolkit and its **AIAgentExpert** custom agent guide the local build and hosted deployment in VS Code. + +## Objectives + +- Scaffold a catalog-grounded agent in the existing Tailspin Toys workspace. +- Debug local behavior with Agent Inspector. +- Deploy to the existing Foundry project and verify the hosted agent. + +## Scenario + +A trustworthy recommendation must survive more than a single conversation. Tailspin Toys needs the concierge to keep its catalog boundaries when backers ask vague questions or press for unavailable funding details. A hosted concierge should behave just as reliably as one tested privately. + +## Resume the workspace + +The agent uses the existing model deployment; there is no new Foundry project to create. + +1. Open the same Tailspin Toys repository in VS Code on `foundry-agent-vscode`. Confirm `db/catalog.json` exists and the project `tailspin-toys` and tested model deployment are visible under **Foundry Toolkit** > **My Resources**. +2. Confirm the [previous checkpoint][previous-lesson] is complete. If resources were cleaned up, complete the project/model preparation again before proceeding. +3. Install Azure Developer CLI (`azd`) if it is not already available. Hosted-agent deployment uses it; choose only the command for your operating system: + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. Sign in to the subscription used for the existing project: + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> Hosted agents and Foundry Toolkit are in public preview. Deployment creates billable resources. Confirm subscription, permissions, region, quota, and estimated cost before approving commands. + +## Create and debug the agent + +The toolkit scaffolds code in the current repository and opens a specialized Copilot Chat. Agent Inspector makes local requests, events, and tool calls visible before deployment. + +1. Select **Foundry Toolkit**, expand **Developer Tools**, expand **+ Build**, and select **+ Create Agent**. On **Create Agent**, select **Code an agent with Copilot**. + + ![Screenshot showing the create agent page.](../../_images/vscode-create-agent.png) + +2. In the new chat, confirm it switches to **AIAgentExpert**. Replace the generated prompt with the customized prompt and submit it: + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. Review the generated code under `agent/backer-concierge`. Confirm the catalog is included in the deployable agent, focused tests pass, and no credentials or local environment files will be committed. +4. Select **Run and Debug** in the Activity Bar and start the debugger with F5. Confirm **Agent Inspector** loads and connects to the agent server. +5. Reuse all six prompts from [Test the deployed model][model-tests]. Check answers against the full `db/catalog.json`, rather than assuming the nine-game subset's ranking is the full catalog ranking. +6. Switch between **Input & Output**, **Events**, and **Tools** to inspect payloads, session events, and tool calls. If behavior violates the acceptance criteria, ask Copilot to fix it and rerun focused tests and Inspector checks before deploying. + + ![Screenshot showing local Agent debug workflow.](../../_images/vscode-agent-debug.png) + +## Deploy and test the hosted agent + +The **Go production** handoff packages the existing agent for Foundry. It does not make the later site proxy a production-ready public service. + +1. In the agent-creation Copilot Chat, select **Go production**, replace the default prompt with the following, and submit it: + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![Screenshot showing hand off options from the AIAgentExpert agent.](../../_images/vscode-go-production-handoff.png) + +2. Review the chat and terminal for parameters and command approvals. Confirm deployment targets the existing `tailspin-toys` project and review billable resources before approving. +3. If Copilot offers an evaluation suite, optionally accept and work through it as an additional check. +4. Select **Foundry Toolkit**, expand **My Resources**, and select **Agents**. On the **Agents** tab, switch to **Hosted Agent**. + + ![Screenshot showing the deployed hosted agent.](../../_images/vscode-agent-deployed.png) + +5. Select the agent name and confirm deployment status is **Running**. Switch to **Playground** and repeat the grounding, missing-data, out-of-catalog, vagueness, and ranking checks against the deployed catalog. + + ![Screenshot showing a response from the deployed hosted agent.](../../_images/vscode-agent-response.png) + +6. If deployment or responses fail, inspect the reported status and logs with Copilot, correct the failure in the existing project, and repeat the checks. Do not proceed with an unverified deployment. + +## Completion checkpoint + +You scaffolded the Backer Concierge, debugged its catalog grounding in Agent Inspector, deployed it to Foundry through the **Go production** handoff, and retested the hosted version in the Playground. The checkpoint for this module is a running hosted agent that respects the catalog without inventing missing information. + +Next, you'll use the same `tailspin-toys` project, model deployment, and hosted agent to connect the agent to the site. If you're stopping here, [clean up your Azure resources][cleanup] to avoid ongoing costs. + +| [Next module: Connect the agent to the site →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#test-the-deployed-model +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#clean-up-your-resources diff --git a/docs/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..2e3a0be4 --- /dev/null +++ b/docs/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "Connect the agent to the site" +description: "Connect the hosted Backer Concierge through a local proxy and test an accessible chat widget." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← Previous module: Build and deploy an agent][previous-lesson] | +|:--| + +This module connects the hosted agent from [Build and deploy an agent][previous-lesson] to Tailspin Toys. Copilot Chat in VS Code creates a local integration, not a public production endpoint. + +## Objectives + +- Keep credentials and Foundry conversation identifiers behind a local server-side proxy. +- Add an accessible chat widget with conversation continuity. +- Verify the backend and full experience before cleaning up resources. + +## Scenario + +Backers should be able to ask the concierge for advice without leaving the catalog. A conversation needs to retain context, work with a keyboard, and protect private connection details. Trust depends on both honest recommendations and a safe, accessible experience. + +## Resume the workspace + +The existing hosted agent is the integration target. Tailspin Toys is a fully pre-rendered static website, so browser code cannot securely hold the agent's credentials. + +1. Open the same Tailspin Toys repository on `foundry-agent-vscode` in VS Code. Confirm the hosted agent from the previous checkpoint is still **Running** in the existing `tailspin-toys` project and that your local Azure sign-in targets its subscription. +2. Open Copilot Chat in regular **Agent** mode instead of **AIAgentExpert**. Attach **Add a Backer Concierge assistant for catalog questions** by selecting **+**, then **GitHub Issues**, and choosing the issue. + +## Build and verify the local proxy + +A local Azure Functions proxy in `/api` holds connection details and forwards requests while the site runs locally. Copilot can use **Azure skills** to prepare and validate it. + +> [!IMPORTANT] +> This workshop proxy is for local development only. Do not deploy it as an anonymous public endpoint. Production needs application-specific authentication and abuse controls, including rate limits or quotas, CORS restrictions, monitoring, and cost controls. + +1. Ask Copilot to create the proxy: + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. Review changes before accepting them. Confirm credentials and Foundry conversation identifiers stay on the server, local settings are excluded from version control, requests are bounded, and focused tests pass. +3. Prove the backend works before building UI: + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. Check the terminal response. Expect valid JSON with a `response` property containing the answer, no invented price information, and no credentials or internal conversation identifiers. If a check fails, ask Copilot to fix it and repeat the backend test. +5. **Keep** the changes and use **/clear** to start fresh for the widget in the same repository and branch. Retain the local proxy configuration and existing hosted-agent connection. + +## Build and test the widget + +The UI now has a verified backend. End-to-end tests check both usability and the catalog's information boundaries. + +1. Ask Copilot to add the widget: + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Screenshot showing the Backer Concierge chat widget in action](../../_images/tailspin-toys-backer-concierge-agent.png) + +2. Keep the Function and site running, then verify the complete experience: + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. Review the test results and changes against the issue acceptance criteria: grounded answers, no invented funding numbers, one clarifying question, accessible UI, and end-to-end coverage. Confirm failures are fixed and the affected checks rerun. + +## Completion checkpoint + +You built a local credential-safe proxy, connected an accessible chat widget, and verified the full conversation flow against the hosted Backer Concierge. The checkpoint for this module is a locally tested site integration that preserves the catalog boundary and keeps credentials and internal Foundry identifiers out of the browser. It is not a production deployment of the proxy or site. + +When you're finished experimenting, stop the local services and [clean up your Azure resources][cleanup] to avoid ongoing costs. Then return to the [VS Code overview][vscode-overview] on the core workshop. + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#clean-up-your-resources +[vscode-overview]: ../../ diff --git a/docs/vscode/7-foundry-toolkit/README.md b/docs/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..4549ad9a --- /dev/null +++ b/docs/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: vscode/7-foundry-toolkit +title: "Optional: Incorporate Foundry" +description: "Build a grounded Backer Concierge with VS Code and Microsoft Foundry Toolkit in three focused modules." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← Previous lesson: Iterating on GitHub Copilot's work][previous-lesson] | +|:--| + +The required VS Code harness is complete after Exercise 6. This optional extension uses GitHub Copilot Chat and Microsoft Foundry Toolkit in VS Code to turn the Tailspin catalog into a Backer Concierge, deploy it as a hosted agent, and connect it to the site through a local proxy. + +## Scenario + +Backers ask questions that filters cannot answer: which game suits someone who loves git puns, or what makes one puzzle game a better fit than another? Tailspin Toys needs a concierge that recommends real catalog titles, asks a clarifying question when needed, and earns trust by admitting when funding numbers or other facts are unavailable. + +## Modules + +Each module ends with a working checkpoint. The same learner repository, feature branch, and Foundry project carry through all three; there is no project recreation between modules. + +| Module | Completion checkpoint | +|--------|-----------------------| +| [1. Prepare a project and model][module-1] | Catalog exported and deployed model tested against grounding rules | +| [2. Build and deploy an agent][module-2] | Local agent debugged and hosted agent tested | +| [3. Connect the agent to the site][module-3] | Local proxy and accessible widget tested end to end | + +> [!IMPORTANT] +> Microsoft Foundry Toolkit and hosted agents are in public preview. These modules create billable Azure resources, including a model deployment and a hosted agent. Subscription permissions, region availability, quota, and cost can limit participation. + +## Before you begin + +The extension builds on your Tailspin Toys repository, not the workshop documentation repository. + +1. Confirm the required workshop work is saved, committed, and pushed before starting the optional feature. +2. Start with [Prepare a project and model][module-1]. If resuming, reopen your Tailspin Toys repository on the `foundry-agent-vscode` branch and confirm the `tailspin-toys` project and its model deployment still exist under **Foundry Toolkit** > **My Resources**. +3. When stopping after any module, follow [Clean up your resources][cleanup] unless you intentionally keep resources for the next module and accept ongoing costs. + +## Clean up your resources + +When you're done experimenting at any checkpoint, remove the Azure resources to avoid unwanted costs. Cleanup removes resources needed by later modules, so continuing afterward requires recreating them. + +> [!WARNING] +> Only delete `rg-tailspin-toys` if it is dedicated to this exercise and contains no resources you need to keep. Deleting a shared resource group would remove unrelated resources too. +> +> If you approved a different resource-group name in module 1, substitute it for `rg-tailspin-toys` in every command below. + +1. Stop any local Agent Inspector debug session, Azure Functions host, or Astro development server you started in its terminal. +2. If you deployed the hosted agent in module 2, open a terminal in the generated agent directory that contains `azure.yaml`, select the same `azd` environment, then run: + + ```bash + azd down --purge + ``` + +3. Check the selected subscription and whether the workshop resource group still exists: + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + If the command returns `false`, cleanup is complete. If it returns `true`, inspect the resources in the group: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Verify that all remaining resources belong to this exercise. If you stopped after module 1, the Foundry project and model still need cleanup even though you did not deploy an `azd` service. + +4. If the dedicated workshop resource group still exists and contains only resources you intend to remove, run: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Because `--no-wait` returns before deletion completes, rerun the following command until it returns `false`: + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## Resources + +- [Foundry Toolkit for Visual Studio Code][foundry-toolkit] +- [Microsoft Foundry agent extension overview][foundry-extension] + +| [Next module: Prepare a project and model →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #clean-up-your-resources +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/vscode/README.md b/docs/vscode/README.md index 8bf2277b..00cd80d5 100644 --- a/docs/vscode/README.md +++ b/docs/vscode/README.md @@ -21,7 +21,7 @@ You'll start by adding custom instructions and watching Copilot follow them, the | [4. Custom Agents][ex4] | Specialized Agents | Review and use custom agents | | [5. Managing Agents][ex5] | Monitoring | Monitor and steer agent sessions | | [6. Iterating][ex6] | Review | Review Copilot's work locally and choose next steps | -| [7. Create a Backer Concierge AI Agent (Optional)][foundry-toolkit] | AI agents | Discover, deploy, and wire up a Microsoft Foundry hosted agent from VS Code | +| [Optional: Incorporate Foundry][foundry-toolkit] | AI agents | Prepare a model, deploy an agent, and connect it to the site in three modules with VS Code and Foundry Toolkit | ## Prerequisites diff --git a/docs/zh-cn/vscode/6-iterating.md b/docs/zh-cn/vscode/6-iterating.md new file mode 100644 index 00000000..8bb83837 --- /dev/null +++ b/docs/zh-cn/vscode/6-iterating.md @@ -0,0 +1,96 @@ +--- +title: "练习 6 - 迭代 GitHub Copilot 的工作" +authors: + - geektrainer +lastUpdated: 2026-06-30 +next: false +--- + +| [← 上一课：监控和管理代理][previous-lesson] | +| :-- | + +## 审阅工作 + +在本实验中，已经与 GitHub Copilot 合作完成了多项改善用户体验的任务：使用代理模式在客户端和服务器端添加筛选功能，通过 Playwright MCP 服务器在浏览器中手动测试，再使用自定义代理实现高对比度和浅色模式切换等无障碍功能，并在会话进行中引导代理扩展工作。现在，该发布这些本地成果，并按照团队的方式进行审阅了。 + +### 场景 + +引入生成式 AI 并不会改变软件设计和 DevOps 的基本原则。Copilot 生成的任何成果仍然需要完整的审阅流程。因此，接下来将 codespace 中的无障碍更改推送到远程，创建拉取请求，并在邀请团队其他成员参与前逐项查看差异。 +## 发布无障碍功能 + +在[练习 4][exercise-4] 和[练习 5][exercise-5] 中，使用无障碍自定义代理实现的高对比度和浅色模式切换功能，已作为提交保存在 codespace 中。接下来，将它们推送到分支并创建拉取请求，供其他团队成员审阅。 + +1. 返回 codespace。 +2. 在 VS Code 中打开 **Source Control** 视图。 +3. 确认无障碍更改已提交。如果练习 5 中还有未提交的更改，现在将其暂存并提交，使用描述性提交消息，例如 `Add high-contrast and light-mode toggles`。 +4. 选择 **Publish Branch** 发布分支（或使用 **...** 菜单 → **Push**）。 +5. VS Code 会提示在 github.com 上打开新分支。接受提示，或手动前往存储库，在分支横幅上选择 **Compare & pull request**。 +6. 设置清晰的标题（例如 `Add high-contrast and light-mode toggles`），并用简短说明概括完成的工作及其原因。 +7. 选择 **Create pull request**。 +8. 拉取请求创建后，选择 **Files changed** 选项卡，完整审阅工作。重点关注： + - 用于切换模式的 UI 组件。 + - 使用本地存储持久保存用户偏好的方式。 + - 高对比度和浅色模式的 CSS 或样式更改。 + - 无障碍属性（ARIA 标签、键盘导航等）。 + - 管理模式切换的 JavaScript/TypeScript 代码。 + +9. 返回 **Conversation** 选项卡。 +10. 如果工作流正在等待批准，选择 **Approve and run workflows**。 + + ![批准并运行工作流](../../_images/shared-approve-workflows.png) +11. 等待工作流完成。如果一切正常，所有工作流都应通过。 + +> [!TIP] +> 想为无障碍改进再获取一份意见？在拉取请求评论中提及 `@copilot`，并提出请求，例如“审查此拉取请求，找出其他 WCAG 问题”或“建议如何改进键盘导航”。Copilot 会启动新会话来处理这条评论。 + +## 可选练习 - 继续在本地探索 + +在 IDE 中与代理迭代协作是一项技能，只有反复练习才能掌握。以下是一些可从 VS Code 发起的后续会话思路： + +- 在游戏详情页添加支持者意向表单。 +- 在游戏列表页实现分页。 +- 为 `src/lib/` 中的数据访问辅助函数添加输入验证和错误处理。 +- 扩展无障碍代理的工作范围，例如审查整个网站的键盘焦点顺序。 + +## 总结 + +恭喜，已完成 VS Code 学习路径！通过本实验，已经： + +- **使用 Playwright MCP 手动测试功能。** 添加 Playwright MCP 服务器，让 Copilot 操作浏览器验证筛选功能，然后再创建拉取请求。 +- **使用代理模式协调全栈更改。** 在一个会话中添加了涉及客户端、服务器端和测试的筛选功能。 +- **使用自定义代理。** 从代理选择器中选择专注于无障碍的自定义代理，观察它在存储库中实现高对比度模式。 +- **管理并引导代理会话。** 在编辑器内审阅建议的更改，接受所需内容，并通过后续请求扩展会话，添加浅色模式。 +- **通过拉取请求完成闭环。** 发布本地成果，并按照团队的方式进行完整审阅。 + +## 回顾与后续步骤 + +至此，VS Code 学习路径的必修部分已经结束。可以在这里停止，工作坊已完成。 + +如果想进一步了解 Copilot 的代理能力，其他学习路径会通过不同界面介绍相关场景： + +- 💻 **[CLI 学习路径](../../cli/)** — 在终端中使用 Copilot CLI 完成类似流程：计划模式、代理技能、自定义代理，以及 `/share`、`/context` 和 `/delegate` 等斜杠命令。 +- ☁️ **[云端代理学习路径](../../cloud/)** — 重点介绍将议题分配给云端代理、通过代理页面监控会话，以及在拉取请求上进行异步迭代。 + +也可以在已有成果上继续开发。[awesome-copilot][awesome-copilot] 提供了丰富的指令文件、自定义代理和技能，可根据自身项目需要加以调整。 + +作为可选扩展，[可选：集成 Foundry][exercise-7] 使用 VS Code 和 Microsoft Foundry Toolkit 准备模型、部署 Backer Concierge，并将其连接到网站。 + +## 资源 + +- [GitHub Copilot][github-copilot] +- [VS Code 中的 Copilot Chat][copilot-chat-vscode] +- [使用代理模式][agent-mode] + +--- + +| [← 上一课：管理代理][previous-lesson] | +|:--| + +[previous-lesson]: ../5-managing-agents/ +[exercise-4]: ../4-custom-agents/ +[exercise-5]: ../5-managing-agents/ +[exercise-7]: ../7-foundry-toolkit/ +[github-copilot]: https://github.com/features/copilot +[copilot-chat-vscode]: https://code.visualstudio.com/docs/copilot/chat/copilot-chat +[agent-mode]: https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode +[awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/zh-cn/vscode/7-foundry-toolkit/1-project-and-model.md b/docs/zh-cn/vscode/7-foundry-toolkit/1-project-and-model.md new file mode 100644 index 00000000..58b7bcf4 --- /dev/null +++ b/docs/zh-cn/vscode/7-foundry-toolkit/1-project-and-model.md @@ -0,0 +1,144 @@ +--- +title: "准备项目和模型" +description: "导出 Tailspin 目录，并根据 Backer Concierge 的验收标准测试已部署的模型。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 可选：集成 Foundry][overview] | +|:--| + +第一个模块使用 VS Code 和 Microsoft Foundry Toolkit，为 Backer Concierge 准备数据和模型。在必修工作坊中创建的个人 Tailspin Toys 存储库中完成操作。 + +## 目标 + +- 导出目录并识别其信息边界。 +- 准备 Foundry 项目，并根据验收标准和配额选择模型。 +- 编写代理代码前，在 Model Playground 中验证回答是否以给定数据为依据。 + +## 场景 + +Tailspin 的支持者希望获得可信的推荐。解谜游戏爱好者期待的是真实的游戏名称和准确的评分，而不是虚构的筹款总额。推荐助手需要明确目录的信息边界，并养成提出一个有用问题的习惯，而不是猜测支持者的需求。 + +## 准备工作区 + +该工具包将模型发现、部署、提示工程、评估和代理部署带入 VS Code。Azure 访问权限和干净的功能分支为后续工作做好准备。 + +> [!IMPORTANT] +> Foundry Toolkit 和托管代理目前处于公共预览阶段。本模块会创建计费的 Azure 资源。批准创建前，确认订阅权限、区域、配额和预计费用。即使在构建代理前停止，也可以执行[清理][cleanup]。 + +1. 确认有权访问 Azure 订阅。可选方案包括[提供 200 美元额度的免费 Azure 账户][azure-free]和[提供 100 美元额度的 Azure for Students][azure-students]，但需满足各自的资格条件和服务限制。 +2. 在 VS Code 的活动栏中选择 **Extensions**，搜索 **Foundry Toolkit**，然后选择 **Install**。安装后，其图标会出现在活动栏中。 +3. 选择 **Azure** 图标，再选择 **Sign in to Azure…**，然后选择用于 Foundry 项目的订阅。工具包完成身份验证后，Copilot 可以使用 [Microsoft Foundry Skill][foundry-skill]，通过对话准备资源。 +4. 在 Tailspin Toys 工作区中，打开 **Terminal** > **New Terminal**，或按 Control+\`（Mac）或 Ctrl+\`（Windows/Linux）。确认之前的工作已提交并推送，然后创建功能分支： + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-vscode + ``` + +5. 以 **Agent** 模式打开新的 Copilot Chat，并提问： + + ```text + Show me the open issue about a Backer Concierge assistant and summarize its acceptance criteria. + ``` + +6. 确认 Copilot 找到了 **Add a Backer Concierge assistant for catalog questions**。验收标准要求回答有数据依据、不虚构筹款金额、提出一个澄清问题，并提供具有端到端测试覆盖的无障碍 UI。 + +## 生成目录导出文件 + +目录导出脚本为代理提供回答所依据的数据源。 + +1. 在 Tailspin Toys 存储库的终端中，执行迁移、填充初始数据并写入 `db/catalog.json`： + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + +2. 打开 `db/catalog.json`，确认其中包含二十一款游戏，每款都有名称、描述、类别、发行商和星级评分，另有一个 `note` 字段说明缺失的信息。目录不包含筹款总额、支持者人数、认捐档位和发布日期；代理必须遵守这一边界。 + +## 设置 Foundry 项目 + +项目用于容纳模型，以及之后的托管代理。继续本模块时，应使用同一个项目，而不是另建项目。 + +1. 在活动栏中选择 **Foundry Toolkit**，展开 **Help and Feedback**，然后选择 **Ask Copilot**。在下拉列表中确认所选模型，并发送生成的 `/foundrytk-quick-start` 提示。 + + ![Foundry Toolkit 快速入门操作流程截图。](../../../_images/vscode-foundry-setup.png) + +2. 在交互式工作流中，对 **Where are you starting from?** 选择 **Set up Foundry**，然后对 **What do you have already?** 选择 **I have an Azure subscription or Foundry resources**。 +3. 检查工具批准请求。如果建议的命令及其作用范围合适，为本会话选择 **Allow azmcp …**，以减少重复的批准提示。 +4. 在 **Microsoft Foundry: Create Project** 中，为 **Choose a resource group** 选择 **Create new resource group**，输入 `rg-tailspin-toys`，选择提供目标模型的区域，并在 **Enter project name** 中输入 `tailspin-toys`。`East US 2` 和 `Sweden Central` 支持的模型较多，可作为初始候选区域；实际选择取决于当前可用性和配额。如果是继续之前的工作，改为选择已有项目。 +5. 等待部署成功通知。在工具包中展开 **My Resources**，确认该项目为默认项目。 + +## 发现并部署模型 + +在这里，遵循规则并以数据为依据，比选择最大或最新的模型更重要。议题提供了具体标准，可用于比较速度、回答与数据的一致性、区域可用性和配额。 + +1. 在 Copilot Chat 中选择 **+**，再选择 **GitHub Issues**，并附加 **Add a Backer Concierge assistant for catalog questions**。发送： + + ```text + /microsoft-foundry recommend a model for the agent described in this issue. There's no math or multi-step planning here, so reasoning depth isn't a priority. Prioritize speed instead. Recommend 2-3 candidates available in my Azure region with the trade-offs between them, tell me which you'd pick and why, and check my quota. Avoid deprecated & older models according to the model retirement schedule + ``` + +2. 阅读建议，选择最符合需求和可用配额的模型。让 Copilot 部署该模型： + + ```text + /microsoft-foundry Deploy the model I selected to the tailspin-toys project and use the model name as the deployment name. Confirm the available quota and capacity with me before creating it. + ``` + +3. 批准前确认项目、部署、容量和费用。检查作用范围后，如果合适，为本会话选择 **Allow az …**，以减少重复提示。 +4. 选择 **Foundry Toolkit**，展开 **My Resources**，然后选择 **Models**。确认已部署的模型显示在 Foundry 下。截图仅为示例；所在区域可能提供不同模型。 + + ![Foundry Toolkit 中的模型部署示例截图。](../../../_images/vscode-model-deployed.png) + +## 测试已部署的模型 + +Model Playground 没有目录文件。在系统提示中提供精简的九款游戏子集，就足以测试模型是否遵守数据依据规则。 + +1. 在 **Models** 中选择已部署的模型名称，打开已预选该模型的 **Model Playground**。粘贴以下系统提示： + + ```text + You're the Backer Concierge for Tailspin Toys. Only recommend games from this catalog — never invent games, publishers, ratings, or any funding/price/date info. If a request is vague, ask one short question first. + + CATALOG + + | Title | Category | Publisher | Rating | + | --- | --- | --- | --- | + | Bug Buster Brainteaser | Puzzle | GitHub Games | 3.0 | + | Merge Conflict Mystery | Puzzle | DevMasters Inc. | 3.8 | + | Stack Trace Secrets | Puzzle | Ops Interactive | 3.6 | + | Deployment Dynasty | Simulation | Ops Interactive | 5.0 | + | Script Strike | Action | CodeForge Studios | 5.0 | + | Pipeline Conquest | Strategy | DevMasters Inc. | 3.9 | + | Repo Rulers | Strategy | Ops Interactive | 4.1 | + | Server Siege | Strategy | GitHub Games | 3.3 | + | Code Quest Odyssey | Adventure | CodeForge Studios | 4.8 | + ``` + +2. 使用 `I love puzzle games about tracking down bugs. What should I back?` 测试回答是否以数据为依据。预期结果是推荐列表中的真实游戏，并提供正确信息。 +3. 使用 `How much has Pipeline Conquest raised so far, and how many backers does it have?` 测试缺失数据。预期结果是明确拒绝提供这些信息，说明目录未记录筹款金额或支持者人数，然后给出已知信息。 +4. 使用 `I need something for four players, about an hour long.` 测试另一个边界。预期结果是说明无法获取玩家人数和游戏时长，然后提出一个有助于继续推荐的追问。 +5. 使用 `Do you have Wingspan? If not, what's the closest thing you've got?` 测试对目录外内容的应对。预期结果是不声称目录中有 Wingspan，不使用外部知识描述它，并转向推荐真实的 Tailspin 游戏。 +6. 使用 `Recommend me something good.` 测试模糊请求。预期结果是提出一个简短的澄清问题，在得知类别或主题前不作推荐。 +7. 使用 `What are your three highest rated games?` 测试排名。预期结果是评分为 5.0 的 Deployment Dynasty 和 Script Strike，然后是评分为 4.8 的 Code Quest Odyssey，顺序和数值均正确。 +8. 如果任何检查失败，与 Copilot 讨论失败的回答和对应规则，调整配置或模型选择，并在继续之前重复检查。 + +## 完成检查点 + +你已准备好 VS Code 工作区、导出目录、创建 Foundry 项目，并针对 Backer Concierge 的据实回答规则测试了已部署的模型。本模块的检查点是一个能推荐目录中真实游戏、且不会编造缺失信息的模型，此时尚未部署代理。 + +接下来，你将使用同一个 `tailspin-toys` 项目和所选的模型部署来构建并部署代理。如果在此停止，请[清理 Azure 资源][cleanup]，以免持续产生费用。 + +| [下一模块：构建并部署代理 →][next-lesson] | +|--:| + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#清理资源 +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[foundry-skill]: https://github.com/microsoft/azure-skills/blob/main/skills/microsoft-foundry/SKILL.md diff --git a/docs/zh-cn/vscode/7-foundry-toolkit/2-build-and-deploy.md b/docs/zh-cn/vscode/7-foundry-toolkit/2-build-and-deploy.md new file mode 100644 index 00000000..23f187df --- /dev/null +++ b/docs/zh-cn/vscode/7-foundry-toolkit/2-build-and-deploy.md @@ -0,0 +1,106 @@ +--- +title: "构建并部署代理" +description: "在 VS Code 中生成 Backer Concierge 框架并调试，然后将其部署为 Foundry 托管代理并测试。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 上一模块：准备项目和模型][previous-lesson] | +|:--| + +本模块使用[准备项目和模型][previous-lesson]中的目录和已测试模型。Microsoft Foundry Toolkit 及其 **AIAgentExpert** 自定义代理将在 VS Code 中引导本地构建和托管部署。 + +## 目标 + +- 在现有 Tailspin Toys 工作区中，生成以目录数据为依据的代理框架。 +- 使用 Agent Inspector 调试本地行为。 +- 部署到现有 Foundry 项目，并验证托管代理。 + +## 场景 + +可信的推荐不能只在一次对话中成立。当支持者提出模糊问题，或坚持索取缺失的筹款详情时，Tailspin Toys 需要推荐助手始终遵守目录的信息边界。托管的推荐助手应当与私下测试时一样可靠。 + +## 继续使用工作区 + +代理使用现有模型部署，无需新建 Foundry 项目。 + +1. 在 VS Code 中打开同一个 Tailspin Toys 存储库，切换到 `foundry-agent-vscode` 分支。确认 `db/catalog.json` 存在，且 **Foundry Toolkit** > **My Resources** 下显示 `tailspin-toys` 项目和已测试的模型部署。 +2. 确认已完成[上一个检查点][previous-lesson]。如果资源已清理，请先重新完成项目和模型的准备工作，再继续。 +3. 如果尚未安装 Azure Developer CLI（`azd`），先安装它。托管代理部署需要使用此工具；仅选择适合当前操作系统的命令： + + ```bash + # macOS / Linux + curl -fsSL https://aka.ms/install-azd.sh | bash + + # Windows (PowerShell) + winget install microsoft.azd + ``` + +4. 登录现有项目所用的订阅： + + ```bash + azd auth login + ``` + +> [!IMPORTANT] +> 托管代理和 Foundry Toolkit 目前处于公共预览阶段。部署会创建计费资源。批准命令前，确认订阅、权限、区域、配额和预计费用。 + +## 创建并调试代理 + +工具包会在当前存储库中生成代码框架，并打开专用的 Copilot Chat。Agent Inspector 可以在部署前展示本地请求、事件和工具调用。 + +1. 选择 **Foundry Toolkit**，展开 **Developer Tools**，再展开 **+ Build**，然后选择 **+ Create Agent**。在 **Create Agent** 上，选择 **Code an agent with Copilot**。 + + ![创建代理页面的截图。](../../../_images/vscode-create-agent.png) + +2. 在新聊天中，确认已切换为 **AIAgentExpert**。将生成的提示替换为以下定制提示并提交： + + ```text + /foundrytk-quick-start Create a backer concierge AI agent called 'Backer Concierge'. The agent should use the model I deployed to answer catalog questions and recommend games grounded strictly in db/catalog.json. Review the acceptance criteria in the issue titled 'Add a Backer Concierge assistant for catalog questions' and ensure the agent meets them. Generate the code into agent/backer-concierge in the current workspace and ask me if anything is unclear. + ``` + +3. 审阅 `agent/backer-concierge` 下生成的代码。确认可部署的代理中包含目录、针对性测试通过，且不会提交凭据或本地环境文件。 +4. 在活动栏中选择 **Run and Debug**，按 F5 启动调试器。确认 **Agent Inspector** 已加载并连接到代理服务器。 +5. 复用[测试已部署的模型][model-tests]中的全部六个提示。根据完整的 `db/catalog.json` 检查回答，不要将九款游戏子集的排名当作完整目录的排名。 +6. 在 **Input & Output**、**Events** 和 **Tools** 之间切换，检查请求与响应数据、会话事件和工具调用。如果行为违反验收标准，让 Copilot 修复，并在部署前重新运行针对性测试和 Inspector 检查。 + + ![本地代理调试工作流截图。](../../../_images/vscode-agent-debug.png) + +## 部署并测试托管代理 + +**Go production** 交接操作会将现有代理打包，以便部署到 Foundry。它不会使后续的网站代理服务成为可用于生产环境的公共服务。 + +1. 在创建代理的 Copilot Chat 中选择 **Go production**，将默认提示替换为以下内容并提交： + + ```text + /foundrytk-quick-start Review this agent for deployment readiness, run its tests, then deploy it to my existing tailspin-toys Foundry project. Show me the deployment status and test the deployed agent. + ``` + + ![AIAgentExpert 代理提供的交接选项截图。](../../../_images/vscode-go-production-handoff.png) + +2. 在聊天和终端中检查参数及命令批准请求。确认部署目标为现有的 `tailspin-toys` 项目，并在批准前检查计费资源。 +3. 如果 Copilot 提供评估套件，可以选择接受并执行，作为额外检查。 +4. 选择 **Foundry Toolkit**，展开 **My Resources**，再选择 **Agents**。在 **Agents** 选项卡中，切换到 **Hosted Agent**。 + + ![已部署的托管代理截图。](../../../_images/vscode-agent-deployed.png) + +5. 选择代理名称，确认部署状态为 **Running**。切换到 **Playground**，根据已部署的目录，重复检查回答的数据依据、缺失数据、目录外内容、模糊请求和排名。 + + ![已部署的托管代理返回回答的截图。](../../../_images/vscode-agent-response.png) + +6. 如果部署或回答未通过检查，与 Copilot 一起检查报告的状态和日志，在现有项目中修复问题，然后重复检查。不要在部署未经验证的情况下继续。 + +## 完成检查点 + +你已生成 Backer Concierge 的代码框架，在 Agent Inspector 中调试了它基于目录的回答，通过 **Go production** 交接将其部署到 Foundry，并在 Playground 中重新测试了托管版本。本模块的检查点是一个正在运行、遵守目录边界且不会编造缺失信息的托管代理。 + +接下来，你将使用同一个 `tailspin-toys` 项目、模型部署和托管代理，将代理连接到网站。如果在此停止，请[清理 Azure 资源][cleanup]，以免持续产生费用。 + +| [下一模块：将代理连接到网站 →][next-lesson] | +|--:| + +[previous-lesson]: ../1-project-and-model/ +[model-tests]: ../1-project-and-model/#测试已部署的模型 +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#清理资源 diff --git a/docs/zh-cn/vscode/7-foundry-toolkit/3-connect-to-site.md b/docs/zh-cn/vscode/7-foundry-toolkit/3-connect-to-site.md new file mode 100644 index 00000000..7f8f56e5 --- /dev/null +++ b/docs/zh-cn/vscode/7-foundry-toolkit/3-connect-to-site.md @@ -0,0 +1,83 @@ +--- +title: "将代理连接到网站" +description: "通过本地代理服务连接托管的 Backer Concierge，并测试无障碍聊天小组件。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +| [← 上一模块：构建并部署代理][previous-lesson] | +|:--| + +本模块将[构建并部署代理][previous-lesson]中的托管代理连接到 Tailspin Toys。VS Code 中的 Copilot Chat 会创建本地集成，而不是公共生产端点。 + +## 目标 + +- 将凭据和 Foundry 对话标识符保留在本地服务器端代理服务中。 +- 添加支持对话连续性的无障碍聊天小组件。 +- 清理资源前，验证后端和完整体验。 + +## 场景 + +支持者应当无需离开目录，就能向推荐助手咨询建议。对话需要保留上下文、支持键盘操作，并保护私密连接详情。信任不仅取决于诚实的推荐，也取决于安全、无障碍的体验。 + +## 继续使用工作区 + +本次集成的目标是现有托管代理。Tailspin Toys 是完全预渲染的静态网站，因此浏览器代码无法安全保存代理的凭据。 + +1. 在 VS Code 中打开同一个 Tailspin Toys 存储库，切换到 `foundry-agent-vscode` 分支。确认上一个检查点中的托管代理在现有 `tailspin-toys` 项目中仍处于 **Running** 状态，且本地 Azure 登录指向其订阅。 +2. 以普通 **Agent** 模式打开 Copilot Chat，而不是 **AIAgentExpert**。选择 **+**，再选择 **GitHub Issues**，然后选择 **Add a Backer Concierge assistant for catalog questions** 议题并附加。 + +## 构建并验证本地代理服务 + +`/api` 中的本地 Azure Functions 代理服务保存连接详情，并在网站本地运行时转发请求。Copilot 可以使用 **Azure skills** 准备和验证该服务。 + +> [!IMPORTANT] +> 本工作坊的代理服务仅用于本地开发。不要将其部署为允许匿名访问的公共端点。生产环境需要针对应用的身份验证和防滥用措施，包括速率限制或配额、CORS 限制、监控和成本控制。 + +1. 让 Copilot 创建代理服务： + + ```text + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge securely during development. Use my existing local Azure sign-in to call the hosted agent, keep all credentials out of the browser, protect conversation state with opaque handles, validate requests, sanitize errors, add focused tests, and configure the Astro dev server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +2. 接受更改前先审阅。确认凭据和 Foundry 对话标识符始终保留在服务器端、本地设置已排除在版本控制之外、请求设有边界限制，且针对性测试通过。 +3. 构建 UI 前，先证明后端可以正常工作： + + ```text + Start the local Functions host and test /api/concierge by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +4. 检查终端响应。预期结果是有效的 JSON，其中 `response` 属性包含回答，且不包含虚构的价格信息、凭据或内部对话标识符。如果检查失败，让 Copilot 修复，然后重复后端测试。 +5. 选择 **Keep** 保留更改，并使用 **/clear**，在同一个存储库和分支中为小组件开启全新聊天。保留本地代理服务配置和现有托管代理连接。 + +## 构建并测试小组件 + +UI 现在有了经过验证的后端。端到端测试将同时检查可用性和目录的信息边界。 + +1. 让 Copilot 添加小组件： + + ```text + Add an accessible Backer Concierge chat widget to the Astro site. Connect it to /api/concierge, preserve the conversation using the returned opaque handle, follow the existing design guidance, support keyboard use, and make it testable. + ``` + + ![Backer Concierge 聊天小组件运行中的截图](../../../_images/tailspin-toys-backer-concierge-agent.png) + +2. 保持 Function 和网站运行，然后验证完整体验： + + ```text + Use Playwright MCP to test the Backer Concierge widget end to end. Verify the core chat flow, conversation continuity, keyboard and accessibility behavior, grounding boundaries, and safe use of the local proxy. Report the results and fix any failures. + ``` + +3. 根据议题验收标准审阅测试结果和更改：回答有数据依据、不虚构筹款金额、提出一个澄清问题、提供无障碍 UI 和端到端测试覆盖。确认失败项已修复，并重新运行受影响的检查。 + +## 完成检查点 + +你已构建可安全保管凭据的本地代理服务，接入了无障碍聊天小组件，并针对托管的 Backer Concierge 验证了完整对话流程。本模块的检查点是一个在本地通过测试的网站集成，它遵守目录边界，并使凭据和 Foundry 内部标识符不会暴露给浏览器。这不是代理服务或网站的生产部署。 + +体验结束后，请停止本地服务并[清理 Azure 资源][cleanup]，以免持续产生费用。然后返回核心工作坊的 [VS Code 概述][vscode-overview]。 + +[previous-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#清理资源 +[vscode-overview]: ../../ diff --git a/docs/zh-cn/vscode/7-foundry-toolkit/README.md b/docs/zh-cn/vscode/7-foundry-toolkit/README.md new file mode 100644 index 00000000..47d5b771 --- /dev/null +++ b/docs/zh-cn/vscode/7-foundry-toolkit/README.md @@ -0,0 +1,97 @@ +--- +slug: zh-cn/vscode/7-foundry-toolkit +title: "可选：集成 Foundry" +description: "通过三个聚焦的模块，使用 VS Code 和 Microsoft Foundry Toolkit 构建基于目录数据的 Backer Concierge。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +| [← 上一课：迭代 GitHub Copilot 的工作][previous-lesson] | +|:--| + +完成练习 6 后，VS Code 学习路径的必修部分就结束了。本可选扩展使用 VS Code 中的 GitHub Copilot Chat 和 Microsoft Foundry Toolkit，将 Tailspin 目录转化为 Backer Concierge，将其部署为托管代理，并通过本地代理服务连接到网站。 + +## 场景 + +支持者提出的问题，往往不是筛选器能够回答的：哪款游戏适合喜欢 git 双关语的人？一款解谜游戏为什么比另一款更适合自己？Tailspin Toys 需要一位推荐助手，能够推荐目录中真实存在的游戏，在必要时提出澄清问题，并在缺少筹款金额或其他信息时坦诚说明，以此赢得信任。 + +## 模块 + +每个模块都以可运行的成果作为完成检查点。三个模块始终使用同一个学员存储库、功能分支和 Foundry 项目，模块之间无需重新创建项目。 + +| 模块 | 完成检查点 | +|--------|-----------------------| +| [1. 准备项目和模型][module-1] | 已导出目录，并根据数据依据规则测试已部署的模型 | +| [2. 构建并部署代理][module-2] | 已调试本地代理，并测试托管代理 | +| [3. 将代理连接到网站][module-3] | 已对本地代理服务和无障碍小组件进行端到端测试 | + +> [!IMPORTANT] +> Microsoft Foundry Toolkit 和托管代理目前处于公共预览阶段。这些模块会创建计费的 Azure 资源，包括模型部署和托管代理。订阅权限、区域可用性、配额和费用可能限制参与。 + +## 开始之前 + +本扩展基于学员的 Tailspin Toys 存储库，而不是工作坊文档存储库。 + +1. 开始可选功能前，确认必修工作坊中的工作已保存、提交并推送。 +2. 从[准备项目和模型][module-1]开始。如果是继续之前的工作，请在 `foundry-agent-vscode` 分支上重新打开 Tailspin Toys 存储库，并确认 **Foundry Toolkit** > **My Resources** 中仍有 `tailspin-toys` 项目及其模型部署。 +3. 完成任一模块后如果要停止，请执行[清理资源][cleanup]，除非决定为下一个模块保留资源，并接受持续产生的费用。 + +## 清理资源 + +在任一检查点结束练习后，请删除 Azure 资源，以免产生不必要的费用。清理会删除后续模块所需的资源，之后若要继续，需要重新创建。 + +> [!WARNING] +> 只有当 `rg-tailspin-toys` 专用于本练习，且不包含需要保留的资源时，才删除该资源组。删除共享资源组会连带移除无关资源。 +> +> 如果在模块 1 中批准了其他资源组名称，请在下面所有命令中将 `rg-tailspin-toys` 替换为该名称。 + +1. 在各自的终端中停止已启动的 Agent Inspector 调试会话、Azure Functions 主机和 Astro 开发服务器。 +2. 如果在模块 2 中部署了托管代理，请在包含 `azure.yaml` 的生成代理目录中打开终端，选择同一个 `azd` 环境，然后运行： + + ```bash + azd down --purge + ``` + +3. 检查所选订阅以及工作坊资源组是否仍然存在： + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + 如果命令返回 `false`，说明清理已完成。如果返回 `true`，请检查该资源组中的资源： + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 确认剩余资源全部属于本练习。如果在模块 1 后停止，即使没有部署 `azd` 服务，仍需要清理 Foundry 项目和模型。 + +4. 如果工作坊专用资源组仍然存在，且仅包含打算移除的资源，请运行： + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. 由于 `--no-wait` 会在删除完成前返回，请反复运行以下命令，直到返回 `false`： + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## 资源 + +- [适用于 Visual Studio Code 的 Foundry Toolkit][foundry-toolkit] +- [Microsoft Foundry 代理扩展概述][foundry-extension] + +| [下一模块：准备项目和模型 →][module-1] | +|--:| + +[previous-lesson]: ../6-iterating/ +[module-1]: 1-project-and-model/ +[module-2]: 2-build-and-deploy/ +[module-3]: 3-connect-to-site/ +[cleanup]: #清理资源 +[foundry-toolkit]: https://code.visualstudio.com/docs/intelligentapps/overview +[foundry-extension]: https://learn.microsoft.com/azure/developer/azure-developer-cli/extensions/azure-ai-foundry-extension diff --git a/docs/zh-cn/vscode/README.md b/docs/zh-cn/vscode/README.md new file mode 100644 index 00000000..61eed9cd --- /dev/null +++ b/docs/zh-cn/vscode/README.md @@ -0,0 +1,48 @@ +--- +slug: zh-cn/vscode +title: "VS Code" +authors: + - geektrainer +lastUpdated: 2026-06-30 +--- + +VS Code 中的 **[GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)** 将 GitHub Copilot 带入了日常使用的代码编辑器。在 Visual Studio Code（以及 GitHub Codespaces）中，可以使用代理模式操作 Copilot Chat，通过 MCP 连接外部工具，并使用自定义代理，全程无需离开 IDE。在这里，Copilot 可以完整查看文件、终端和问题。 + +首先添加自定义指令，观察 Copilot 如何遵循这些指令，然后使用代理模式构建涵盖 UI、数据层和测试的筛选功能。接下来，连接 Playwright MCP 服务器，让 Copilot 操作浏览器测试功能，再创建拉取请求。最后，审阅并使用自定义代理完成无障碍改进，然后监控、引导并迭代 Copilot 的更改，全程无需离开编辑器。 + +## 练习 + +| 练习 | 主题 | 说明 | +|----------|-------|-------------| +| [0. 先决条件][ex0] | 设置 | 创建存储库和 codespace | +| [1. 自定义指令][ex1] | 上下文 | 在 VS Code 中添加并验证自定义指令 | +| [2. 代理模式][ex2] | 代码生成 | 使用代理模式构建筛选功能 | +| [3. 结合 Playwright 使用 MCP][ex3] | 外部工具 | 使用 Playwright MCP 服务器在浏览器中测试功能 | +| [4. 自定义代理][ex4] | 专用代理 | 审阅并使用自定义代理 | +| [5. 管理代理][ex5] | 监控 | 监控并引导代理会话 | +| [6. 迭代][ex6] | 审阅 | 在本地审阅 Copilot 的工作并选择后续步骤 | +| [可选：集成 Foundry][foundry-toolkit] | AI 代理 | 通过三个模块，使用 VS Code 和 Foundry Toolkit 准备模型、部署代理并将其连接到网站 | + +## 先决条件 + +参加本工作坊前，需要具备： + +- [ ] 拥有有效 **Copilot Student、Pro、Pro+、Business 或 Enterprise** 计划的 GitHub 账户 +- [ ] GitHub Codespaces 访问权限 + +> [!TIP] +> 没有付费计划？通过验证的学生可以通过 [GitHub Education][callout-student-plan-education] 免费使用 GitHub Copilot。**Copilot Student** 计划包含本工作坊使用的代理、MCP、代码审查和 Copilot CLI 功能，因此可以用它完成所有学习路径。 + +[callout-student-plan-education]: https://github.com/education/students +## 开始学习 + +**[从练习 0：先决条件开始 →][ex0]** + +[ex0]: 0-prerequisites/ +[ex1]: 1-custom-instructions/ +[ex2]: 2-agent-mode/ +[ex3]: 3-mcp/ +[ex4]: 4-custom-agents/ +[ex5]: 5-managing-agents/ +[ex6]: 6-iterating/ +[foundry-toolkit]: 7-foundry-toolkit/ diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 000b7311..b72b4556 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -63,7 +63,52 @@ export default defineConfig({ { label: '4. Custom agents', link: '/vscode/4-custom-agents/' }, { label: '5. Managing agents', link: '/vscode/5-managing-agents/' }, { label: '6. Iterating', link: '/vscode/6-iterating/' }, - { label: '7. Create a Backer Concierge AI Agent (Optional)', link: '/vscode/7-foundry-toolkit/' }, + { + label: 'Optional: Incorporate Foundry', + translations: { + 'es-ES': 'Opcional: Incorporar Foundry', + 'ja-JP': '省略可能: Foundry を組み込む', + 'ko-KR': '선택 사항: Foundry 통합', + 'pt-BR': 'Opcional: Incorporar o Foundry', + 'zh-CN': '可选：集成 Foundry', + }, + items: [ + { label: 'Overview', link: '/vscode/7-foundry-toolkit/' }, + { + label: 'Prepare a project and model', + link: '/vscode/7-foundry-toolkit/1-project-and-model/', + translations: { + 'es-ES': 'Preparar un proyecto y un modelo', + 'ja-JP': 'プロジェクトとモデルを準備する', + 'ko-KR': '프로젝트 및 모델 준비', + 'pt-BR': 'Preparar um projeto e um modelo', + 'zh-CN': '准备项目和模型', + }, + }, + { + label: 'Build and deploy an agent', + link: '/vscode/7-foundry-toolkit/2-build-and-deploy/', + translations: { + 'es-ES': 'Crear e implementar un agente', + 'ja-JP': 'エージェントを構築してデプロイする', + 'ko-KR': '에이전트 빌드 및 배포', + 'pt-BR': 'Criar e implantar um agente', + 'zh-CN': '构建并部署代理', + }, + }, + { + label: 'Connect the agent to the site', + link: '/vscode/7-foundry-toolkit/3-connect-to-site/', + translations: { + 'es-ES': 'Conectar el agente al sitio', + 'ja-JP': 'エージェントをサイトに接続する', + 'ko-KR': '사이트에 에이전트 연결', + 'pt-BR': 'Conectar o agente ao site', + 'zh-CN': '将代理连接到网站', + }, + }, + ], + }, ], }, {