diff --git a/AUTHORING.md b/AUTHORING.md index fd226b81..1096e5dc 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -31,7 +31,7 @@ copilot-workshops/ ### Add a new lesson -1. **Pick a path and number.** Lessons live under `docs/{cli,vscode,app,cloud}/N-name.md`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/3-generating-code/`). +1. **Pick a path and number.** Lessons live under `docs/{cli,vscode,app,cloud}/N-name.md`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/3-generating-code/`). A longer optional exercise can use `N-name/README.md` for its overview and numbered modules inside that folder. Preserve the entry URL with the overview's `slug`, keep the core review as the default next destination, and place the optional sidebar group after it. 2. **Create the file** with frontmatter: ```markdown --- @@ -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/`). +- `docs/app/8-foundry-canvas/README.md` → `slug: app/8-foundry-canvas`; its localized overview uses `slug: /app/8-foundry-canvas`. 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/docs/app/7-canvases.md b/docs/app/7-canvases.md index c381fd41..e9844a3a 100644 --- a/docs/app/7-canvases.md +++ b/docs/app/7-canvases.md @@ -4,6 +4,9 @@ description: "Create a shared, agent-driven canvas in the GitHub Copilot app to authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/app/9-review/ + label: "Review and next steps" --- So far you've directed agents through chat. But a lot of work doesn't live in a conversation — it lives on a board, in a document, or on a checklist. **Canvases** give you and the agent a shared surface for exactly that kind of work, right inside the app. In this lesson you'll create a simple canvas to plan and track the backlog you've been working through. @@ -113,7 +116,7 @@ You created a shared surface where you and the agent can collaborate! You: - saved and merged the canvas to your repository with Agent Merge. - opened the canvas in a new session and used it to start work. -With your backlog tracked, you're ready to wrap up — or go further. If you want to build a hosted AI agent from the Tailspin catalog, continue to the [optional Backer Concierge lesson][next-lesson]. Otherwise, skip ahead to [reviewing what you've built][review-lesson]. +With your backlog tracked, continue to [reviewing what you've built][next-lesson]. For an optional extension using Microsoft Foundry Canvas, explore [Optional: Incorporate Foundry][foundry-canvas]. ## Resources @@ -121,8 +124,8 @@ With your backlog tracked, you're ready to wrap up — or go further. If you wan - [Canvases on Awesome Copilot][awesome-copilot-canvases] - [About the GitHub Copilot app][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/docs/app/8-foundry-canvas.md b/docs/app/8-foundry-canvas.md deleted file mode 100644 index f12177ab..00000000 --- a/docs/app/8-foundry-canvas.md +++ /dev/null @@ -1,405 +0,0 @@ ---- -title: "Lesson 8 - (Optional) Build a Backer Concierge Agent" -description: "Use Microsoft Foundry Canvas in the GitHub Copilot app to create, test, deploy, and integrate a catalog-grounded hosted agent." -authors: - - juliamuiruri4 -lastUpdated: 2026-09-10 ---- - -In this optional lesson, you'll take the Tailspin catalog and build an AI agent on top of it. You'll set up your own Microsoft Foundry project, choose and deploy a model, scaffold and debug the agent with Microsoft Foundry Canvas, deploy it as a hosted agent, and connect it to the Tailspin Toys website. - -In this lesson, you will: - -- set up the Azure tools and Microsoft Foundry Canvas. -- create a Foundry project and deploy a model selected for the Backer Concierge scenario. -- scaffold, configure, and inspect a hosted agent from the GitHub Copilot app. -- deploy the agent to Microsoft Foundry. -- connect the hosted agent to the Tailspin Toys website. - -> [!IMPORTANT] -> Microsoft Foundry Canvas 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. - -## Prerequisites and setup - -1. An Azure Subscription - - - [Free Azure subscription with $200 credit][azure-free] - - [Azure for Students with $100 credits][azure-students] - -2. Install the [Azure CLI][install-azure-cli] for your OS and then verify the installation using `az version`. - -3. Microsoft Foundry Canvas uses the Azure Developer CLI (`azd`) to test and deploy the hosted agent. Install the [Azure Developer CLI][install-azd] before continuing. - - - **Verify that `azd` version 1.27.1 or later is installed:** - - ```bash - azd version - ``` - -4. Install Microsoft Foundry plugin that bundles the canvas and foundry skills - - - Open the GitHub Copilot app. - - Open **Customize**, then select **Plugins**. - - Search for `microsoft-foundry`. - - Select **Install** for the Microsoft Foundry plugin. - ![Install Microsoft Foundry plugin](../_images/app-8-install-foundry-plugin.png) - - The plugin adds Microsoft Foundry Canvas to the app. - -5. Install the Azure plugin - - - Open the GitHub Copilot app. - - Open **Customize**, then select **Plugins**. - - Search for `azure` or alternatively select it from the **Featured** list. - - Select **Install** for the Azure plugin. - -6. Confirm the installation of both plugins: - - - Create a new session in your Tailspin Toys repository - - Type `/microsoft-foundry`, then `/azure` to confirm the skills are installed and available. Don't send any prompts yet. - - Restart the app if the plugin does not appear immediately. - -## Scenario - -In a previous lesson, you added filtering by category and publisher. Filtering helps backers who already know what they want, but other backers ask questions such as *Which games would suit someone who loves Git puns?* Those questions don't have dropdown answers. - -In this lesson, you build a **Backer Concierge** that answers catalog questions while staying grounded in Tailspin Toys data. The agent should recommend only games in the Tailspin catalog and never invent games, publishers, ratings, funding totals, backer counts, prices, player counts, play times, or release dates. - -1. On the **My work** tab, find and open the issue titled **Add a Backer Concierge assistant for catalog questions**. -2. Select **New session** to start a session from the issue. - -## Generate the catalog export - -The agent needs the catalog as a file it can read. The sample repository includes an export script for this purpose. - -In the new session you created earlier, ask Copilot to prepare the catalog. Ensure you're running in a new worktree *(replace the default `/fix-issue` prompt in the prompt box)*: - - ```plaintext - Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. - ``` - -Copilot should run the equivalent of: - -```bash -npm install -npm run db:setup -npm run db:export -``` - -![Generate catalog export](../_images/app-8-generate-catalog-export.png) - -Open `db/catalog.json`. It should contain 21 games with a title, description, category, publisher, and star rating. Its `note` field states that the catalog doesn't contain funding totals, backer counts, pledge tiers, or release dates. Those omissions define the boundary your agent must respect. - -![Catalog export open in the Copilot app](../_images/app-8-view-catalog.png) - -## Set up a Foundry project and model - -Create the project and model deployment in chat before opening Canvas, so Canvas only ever connects to resources that already exist. - -1. Sign in to the Azure CLI and Azure Developer CLI. Select **+**, select **Terminal**, and run: - - ```bash - az login - ``` - - ensure you select the right subscription. Then run: - - ```bash - azd auth login - ``` - - and complete authentication in the browser when prompted. - - > [!TIP] - >Run `azd config show` to verify your Azure subscription. If it is empty or incorrect, update it with `azd config set defaults.subscription `, and re-run `azd config show` to confirm the change. - -2. In the same session, enter the following prompt: - - ```plaintext - Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. - ``` - - ![Create Foundry project](../_images/app-8-foundry-project-created.png) - -3. Ask Copilot to recommend a model. The issue is already in this session's context because you started from it: - - ```plaintext - Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. - ``` - - You should see Copilot load the `microsoft-foundry` skill as it recommends models. - -4. Choose one of the available models. The Microsoft Foundry hosted-agent quickstart currently uses `gpt-5.4-mini`, but availability and quota vary by region. - - ![Select model](../_images/app-8-select-model.png) - -5. Ask Copilot to deploy your selection: - - ```plaintext - Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. - ``` - -> [!TIP] -> Model availability changes over time. Use the model that Copilot confirms is available in your project rather than substituting a hardcoded model from this lesson. - -## Validate the project and model in Canvas - -Open Microsoft Foundry Canvas next to confirm the project and model you just created, before any agent code exists. - -1. Select **+** > **Canvas**, then select **Microsoft Foundry (Preview)**. -2. Open the **More options** menu in the top-right corner of the Canvas interface, then select **Sign in**. -3. Select the **tailspin-toys** Foundry project. -4. Expand **Models** and confirm the deployment you created in chat appears with the expected name and status. - - ![Validate project and model in Canvas](../_images/app-8-validate-project-model.png) - -Canvas remembers the selected project when you reopen it. Confirm the project before making each cost-bearing change. - -The Canvas guides you through three stages: - -- **Create new hosted agents** scaffolds the agent in your workspace. -- **Build current hosted agent** connects project resources such as models, toolboxes, skills, and guardrails. -- **Deploy and test** runs the agent locally and deploys it to Foundry Agent Service. - -## Scaffold the Backer Concierge Agent - -With Canvas connected to the right project and model, ask it to scaffold the agent itself: the code, folder structure, and `azure.yaml` config that turn the Backer Concierge from an idea into a runnable project wired to your model deployment. - -1. In **Create new hosted agents** preview, enter the following prompt: - - ```plaintext - Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. - ``` - - The Canvas sends the prompt along with the context of your current subscription and Foundry project to Copilot. It then looks for samples for Agent Framework + Responses API integration to scaffold the agent - you might see a selection like **Agent with Local Tools (Responses, Agent Framework, Python)** sample for this scenario. - - ![Scaffold Backer Concierge agent in Canvas](../_images/app-8-scaffold-backer-concierge.png) - -2. Review Copilot's changes by checking the **Files** tab. Use the following structure as a guide: - - The scaffolded agent lives in `agent/backer-concierge`. - - A single `azure.yaml` at the repository root contains a service with `host: azure.ai.agent`. - - The deployable agent includes its own generated copy of the catalog. - - Focused tests cover the catalog grounding requirements. - - No credentials or local environment files are included. - - Use the following structure as the checkpoint after scaffolding. Generated filenames inside `src` can differ, but the project boundaries and `azure.yaml` location should match: - - ```text - tailspin-toys/ - ├── azure.yaml - ├── agent/ - │ └── backer-concierge/ - │ └── requirements.txt - ├── db/ - │ └── catalog.json - └── src/ - ``` - -3. Ask Copilot to run the focused tests and fix any failures before continuing. - -With the agent scaffolded, connected, and grounded, move to **Deploy and test** to run it. - -## Inspect the agent locally - -In **Deploy and test**, select **Inspect Locally**. - -This runs `azd ai agent run` in the Copilot integrated terminal, waits for the hosted agent to start, and opens the embedded Agent Inspector. - -> [!NOTE] -> The first local run can take several minutes while `azd` creates an environment and installs dependencies. If the inspector reports that it can't connect, confirm that no other process is using the required port, then send the error to Copilot. - -Once the inspector is open, put the agent through the same acceptance criteria you scoped out at the start of the lesson. - -Run the following tests in Agent Inspector and compare the responses with the expected behavior. - -1. **Grounded recommendation** - - Prompt: - - ```text - I love puzzle games about tracking down bugs. What should I back? - ``` - - Expected: Names only real titles from the catalog and uses the correct information for each title. - - ![Grounded recommendation in Agent Inspector](../_images/app-8-grounded-recommendation.png) - -2. **Hallucination trap** - - Prompt: - - ```text - How much has Pipeline Conquest raised so far, and how many backers does it have? - ``` - - Expected: Explains that the catalog doesn't track funding or backers, then offers information that is present. - -3. **Out-of-catalog pressure** - - Prompt: - - ```text - Do you have Wingspan? If not, what's the closest thing you've got? - ``` - - Expected: Says that Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to real Tailspin titles. - -4. **Vague request** - - Prompt: - - ```text - Recommend me something good. - ``` - - Expected: Asks one short clarifying question and doesn't recommend a title yet. - -5. **Ranking accuracy** - - Prompt: - - ```text - What are your three highest rated games? - ``` - - Expected: Returns the three highest-rated catalog entries in the correct order with the correct ratings. - -6. **Conversation continuity** - - Send these prompts in the same conversation: - - ```text - Show me two highly rated strategy games. - ``` - - ```text - Which of those has the higher rating? - ``` - - Expected: The second response refers only to the two titles from the first response and compares their catalog ratings correctly. - -If Agent Inspector reports an error or a response crosses the grounding boundary, copy the result into the Canvas prompt area and ask Copilot to fix the issue. Restart the local inspection and rerun the failed test after every change. - -## Deploy the hosted agent - -You've confirmed that your hosted agent is running correctly and passing all local inspection tests. Next, you will deploy the agent to Microsoft Foundry, and this too can be completed through the canvas. - -On the canvas, in **Deploy and test**, select **Deploy to Foundry**. This will drop a prompt in the chat to kick off deployment to your Foundry project. Canvas uses `azd` for this deployment. Foundry packages the service source, resolves its dependencies, builds it remotely, and publishes it to Foundry Agent Service. - - ![Deploy to Foundry prompt on the canvas](../_images/app-8-deploy-to-foundry.png) - -The agent will be deployed to your Foundry project, and you should see a confirmation message, agent version, status and a link to the agent playground on Foundry. - -From the canvas, you can select **Test in Foundry Portal** to open the agent playground and interact with your deployed agent. - -## Connect the agent to the static site - -Tailspin Toys is fully pre-rendered. Browser code must never call the hosted agent directly or receive Foundry credentials. Add a local Azure Functions **server-side credential boundary** that authenticates to Foundry and returns only the agent response to the browser. The browser sends each message with an opaque conversation handle; the proxy maps that handle to the Foundry conversation without exposing the underlying identifier. - -### Build the server-side proxy - -The proxy is the only piece of code allowed to access the learner's Azure credentials, so build it first and keep everything else behind it. For this workshop, the Function and site run locally, with the Astro development server forwarding `/api` requests to the Function. - -> [!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 the same Copilot session, enter: - - ```plaintext - Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. - ``` - -2. Once complete, open another terminal, then start the local Function using the command provided by Copilot. Leave the Function running. - -3. Return to the chat and ask Copilot to test the local proxy: - - ```plaintext - Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. - ``` - -The response should explain that the catalog doesn't contain prices. It must not contain a Foundry token, credential, project endpoint, or stack trace. - -![Local proxy test](../_images/app-8-local-proxy-test.png) - -### Build the chat widget - -With the proxy running, add the visible piece backers will actually use directly on the site. - -1. Ask Copilot to create the site integration: - - ```plaintext - 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. - ``` - -2. Start the Astro development server in another terminal using the command provided by Copilot. Keep both the site and the local Function running. - -3. Before moving on, confirm the widget actually behaves as expected. Paste in the following prompt to have Copilot run the end-to-end tests for the Backer Concierge widget: - - ```plaintext - Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. - ``` - - Review the report from Copilot. You can manually verify any claims of passing tests against the actual behavior in the browser and address any failing tests. - - ![End-to-end test results for the Backer Concierge widget](../_images/app-8-e2e-test-results.png) - -## Create and merge the pull request - -With the agent built, deployed, and connected to the site, wrap up the same way you have in earlier lessons. - -1. Review all changed files in the session. -2. Confirm that generated environment files, local settings, tokens, and credentials aren't included. -3. Select the dropdown next to **Create PR**, then select **Agent merge**. -4. Select **Agent merge** to create the pull request and monitor its checks. - -## Clean up your resources - -When you're done experimenting, remove the resources to avoid unwanted costs. - -1. Open a new terminal and run: - - ```bash - azd down --purge - ``` - -2. After azd down, if the dedicated workshop resource group still exists, verify its name and contents before running: - - ```bash - az group delete --name rg-tailspin-toys --yes --no-wait - ``` - -## Summary and next steps - -You took a feature brief from an idea to a deployed, product-integrated AI agent. You: - -- created a Foundry project and selected a model from the feature requirements, availability, quota, and cost. -- used Microsoft Foundry Canvas to scaffold and configure the hosted agent. -- tested grounding and conversation behavior in the embedded Agent Inspector. -- deployed and retested the agent in Foundry Agent Service. -- created a locally running Azure Functions proxy to call the Foundry Agent Service. -- added and verified an accessible chat widget in Tailspin Toys. - -Continue to [Lesson 9 - Review and next steps][next-lesson]. - -## Resources - -- [What is Microsoft Foundry Canvas?][foundry-canvas] -- [Deploy your first hosted agent with Foundry Canvas][hosted-agent-quickstart] -- [Hosted agent permissions][hosted-agent-permissions] - ---- - -| [← Previous lesson: Planning with canvases][previous-lesson] | [Next lesson: Review and next steps →][next-lesson] | -| :-- | --: | - -[previous-lesson]: ../7-canvases/ -[next-lesson]: ../9-review/ -[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account -[azure-students]: https://azure.microsoft.com/free/students -[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli -[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd -[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas -[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas -[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/app/8-foundry-canvas/1-project-and-model.md b/docs/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..bf26fbf3 --- /dev/null +++ b/docs/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "Prepare project and model" +description: "Export the Tailspin catalog, create a Foundry project and model deployment, and validate them in Canvas." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/app/8-foundry-canvas/ + label: "Optional: Incorporate Foundry" +next: + link: /copilot-workshops/app/8-foundry-canvas/2-build-and-deploy/ + label: Build and deploy the agent +--- + +This first module establishes the data and Azure resources for the Backer Concierge. No agent code or hosted deployment is needed yet. + +By the end, you will have: + +- A catalog export with explicit grounding limits. +- A Foundry project and a model deployment chosen for the feature requirements. +- A Canvas-validated deployment and a simple catalog-bounded model smoke check. + +## Scenario + +Tailspin Toys backers can filter games by category and publisher, but questions such as *Which games would suit someone who loves Git puns?* don't have dropdown answers. A Backer Concierge should recommend only games in the Tailspin catalog and never invent games, publishers, ratings, funding totals, backer counts, prices, player counts, play times, or release dates. A reliable catalog and a suitable model are the foundation for those answers. + +## Prepare your tools and issue session + +The setup connects the GitHub Copilot app to Azure while keeping all feature work together. + +1. Confirm that you have an Azure subscription. If you need one, the available options include a [free Azure subscription with $200 credit][azure-free] or [Azure for Students with $100 credit][azure-students]. +2. Install the [Azure CLI][install-azure-cli] for your OS, then verify the installation using `az version`. +3. Install the [Azure Developer CLI][install-azd], then verify that version 1.27.1 or later is installed using `azd version`. +4. Open the GitHub Copilot app, open **Customize**, then select **Plugins**. Search for `microsoft-foundry` and select **Install** for the Microsoft Foundry plugin, which bundles Canvas and the Foundry skills. + + ![Install Microsoft Foundry plugin](../../_images/app-8-install-foundry-plugin.png) + +5. In **Customize**, select **Plugins**, search for `azure` or select it from the **Featured** list, then select **Install** for the Azure plugin. +6. On the **My work** tab, find and open the issue titled **Add a Backer Concierge assistant for catalog questions** in your Tailspin Toys repository. Select **New session** to start an issue-linked session in a new worktree. Keep this repository, worktree branch, and issue session for all three modules. +7. Type `/microsoft-foundry`, then `/azure` to confirm both skills are installed and available; don't send any prompts yet. If a plugin does not appear immediately, restart the app, return to this same issue session, and check again. + +## Generate the catalog export + +The sample repository includes an export script that gives the agent a file it can read. + +8. In this issue-linked worktree session, replace the default `/fix-issue` prompt in the prompt box with: + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. Review the command output. Copilot should run the equivalent of: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![Generate catalog export](../../_images/app-8-generate-catalog-export.png) + +10. Open `db/catalog.json` and confirm it contains 21 games with a title, description, category, publisher, and star rating. Check its `note` field: the catalog doesn't contain funding totals, backer counts, pledge tiers, or release dates. Treat missing prices, player counts, and play times as unavailable too, rather than filling gaps from outside knowledge. If the export fails or differs, ask Copilot to investigate and rerun it before continuing. + + ![Catalog export open in the Copilot app](../../_images/app-8-view-catalog.png) + +## Set up a Foundry project and model + +Creating the project and deployment in chat first means Canvas connects only to resources that already exist. + +11. Select **+**, select **Terminal**, and sign in to Azure: + + ```bash + az login + ``` + +12. Check the selected subscription and list its resource groups: + + ```bash + az account show --output table + az group list --output table + ``` + + If the subscription is incorrect, run `az account set --subscription `, then repeat both commands. + + If `rg-tailspin-toys` appears, inspect its resources: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + If the group contains unrelated or shared resources, stop and choose a dedicated name before using the following prompt. Replace the example names in every later prompt and command with the names you approve. +13. In the same issue session, enter: + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![Create Foundry project](../../_images/app-8-foundry-project-created.png) + +14. Ask Copilot to recommend a model. The issue's acceptance criteria are already in context because the session started from the issue: + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. Confirm Copilot loads the `microsoft-foundry` skill, then choose an available model based on its tradeoffs. The Microsoft Foundry hosted-agent quickstart currently uses `gpt-5.4-mini`, but availability and quota vary by region. + + ![Select model](../../_images/app-8-select-model.png) + +16. Ask Copilot to deploy your selection, reviewing the target project and cost before approval: + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> Model availability changes over time. The model Copilot confirms is available in your project is the appropriate choice, rather than a hardcoded model from this module. + +## Validate and smoke-test the model in Canvas + +This check verifies the project and model before any agent code exists. A model smoke check is not a substitute for the hosted agent's grounding tests in module 2. + +17. Select **+**, then **Canvas**, then **Microsoft Foundry (Preview)**. +18. Open the **More options** menu in the top-right corner of Canvas, then select **Sign in**. +19. Select the **tailspin-toys** Foundry project. Expand **Models** and confirm your deployment appears with the expected name and status. + + ![Validate project and model in Canvas](../../_images/app-8-validate-project-model.png) + +20. In the same session, enter: + + ```plaintext + Use the Microsoft Foundry skill to test my deployed model directly in the tailspin-toys project without creating an agent. Ground it with content from @db/catalog.json and ask: "I love puzzle games about tracking down bugs. What should I back, and how much funding has it raised?" Show me the response and useful metadata such as tokens used and response time, only if available. Use my existing Azure sign-in. Do not display credentials, change files, or create resources. + ``` + +21. Review the response. It should recommend only a real game from `db/catalog.json`, use the correct title, publisher, and rating, and explain that funding information is unavailable. If the model invents a game, catalog details, or a funding total, compare another recommended model before continuing. + +> [!NOTE] +> Canvas remembers the selected project when reopened. Its stages are **Create new hosted agents** for scaffolding, **Build current hosted agent** for connecting models, toolboxes, skills, and guardrails, and **Deploy and test** for local runs and deployment to Microsoft Foundry. + +## Checkpoint and next steps + +You prepared the Azure tools, exported the catalog, 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. + +Next, you'll use the same Tailspin Toys repository, worktree branch, issue-linked session, Foundry project, and selected model deployment to [build and deploy the agent][next-module]. If you're stopping here, [clean up your Azure resources][cleanup] to avoid ongoing costs. + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#clean-up-your-resources diff --git a/docs/app/8-foundry-canvas/2-build-and-deploy.md b/docs/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..12716333 --- /dev/null +++ b/docs/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,161 @@ +--- +title: "Build and deploy the agent" +description: "Scaffold the Backer Concierge in Canvas, inspect it locally, and deploy and retest it in Foundry." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/app/8-foundry-canvas/1-project-and-model/ + label: Prepare project and model +next: + link: /copilot-workshops/app/8-foundry-canvas/3-connect-to-site/ + label: Connect the agent to the site +--- + +This module turns the project, model deployment, and catalog from [Prepare project and model][previous-module] into a hosted Backer Concierge through Microsoft Foundry Canvas. + +By the end, you will have: + +- A scaffolded agent with packaged catalog data and focused tests. +- Local evidence for each catalog and conversation acceptance criterion. +- A deployed agent version retested in Foundry. + +## Scenario + +Tailspin Toys needs a concierge that can answer real catalog questions, admit when information is missing, and remember the games discussed in a conversation. The service must earn that trust before it becomes part of the storefront. + +## Prepare deployment tools + +Hosted-agent inspection and deployment use Azure Developer CLI through Canvas; the existing Foundry project and model are reused. + +1. Resume the same session linked to the **Add a Backer Concierge assistant for catalog questions** issue from module 1. Confirm `db/catalog.json` is intact, you're connected to the correct subscription and Foundry project, and your model deployment is still in place. If resources were cleaned up, repeat the relevant [project-and-model setup][previous-module] first. + +2. Select **+**, select **Terminal**, and sign in to Azure Developer CLI, completing authentication in the browser when prompted: + + ```bash + azd auth login + ``` + +3. Run `azd config show` to verify your Azure subscription. If it is empty or incorrect, update it with `azd config set defaults.subscription `, and rerun `azd config show` to confirm the change. + +## Scaffold the Backer Concierge + +Canvas scaffolds the code, folder structure, and root `azure.yaml` that connect the Backer Concierge to your existing model deployment. + +4. In **Create new hosted agents** preview, enter: + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + Canvas sends the prompt and current subscription and Foundry project context to Copilot. It looks for Agent Framework + Responses API samples; a selection such as **Agent with Local Tools (Responses, Agent Framework, Python)** may appear. + + ![Scaffold Backer Concierge agent in Canvas](../../_images/app-8-scaffold-backer-concierge.png) + +5. Review Copilot's changes in the **Files** tab against this checkpoint. Generated filenames inside `src` can differ, but the project boundaries and `azure.yaml` location should match: + + - The agent lives in `agent/backer-concierge`. + - A single `azure.yaml` at the repository root contains a service with `host: azure.ai.agent`. + - The deployable agent includes its own generated copy of the catalog. + - Focused tests cover catalog grounding requirements. + - No credentials or local environment files are included. + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. Ask Copilot to run the focused tests and fix any failures before continuing to **Deploy and test**. + +## Inspect the agent locally + +**Inspect Locally** runs `azd ai agent run` in the Copilot integrated terminal, waits for the hosted agent to start, and opens the embedded Agent Inspector. + +7. In **Deploy and test**, select **Inspect Locally** and wait for Agent Inspector to open. + +> [!NOTE] +> The first local run can take several minutes while `azd` creates an environment and installs dependencies. + +8. If the inspector cannot connect, confirm that no other process is using the required port, send the error to Copilot, and retry after the issue is fixed. +9. Test a **grounded recommendation** in Agent Inspector: + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + Expected: Names only real titles from the catalog and uses the correct information for each title. + + ![Grounded recommendation in Agent Inspector](../../_images/app-8-grounded-recommendation.png) + +10. Test a **hallucination trap**: + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + Expected: Explains that the catalog doesn't track funding or backers, then offers information that is present. + +11. Test **out-of-catalog pressure**: + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + Expected: Says that Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to real Tailspin titles. + +12. Test a **vague request**: + + ```text + Recommend me something good. + ``` + + Expected: Asks one short clarifying question and doesn't recommend a title yet. + +13. Test **ranking accuracy**: + + ```text + What are your three highest rated games? + ``` + + Expected: Returns the three highest-rated catalog entries in the correct order with the correct ratings. + +14. Test **conversation continuity** by sending these prompts in the same conversation: + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + Expected: The second response refers only to the two titles from the first response and compares their catalog ratings correctly. + +15. Compare every response with `db/catalog.json` and the issue's acceptance criteria. Confirm the agent never invents games, publishers, ratings, funding totals, backer counts, prices, player counts, play times, or release dates. If Agent Inspector reports an error or a response crosses the grounding boundary, copy the result into the Canvas prompt area and ask Copilot to fix it. Restart local inspection and rerun the failed test after every change, then confirm all six checks pass before deploying. + +## Deploy and retest the hosted agent + +Canvas uses `azd` to deploy the tested agent. Foundry packages the service source, resolves dependencies, builds it remotely, and publishes it to Microsoft Foundry. + +16. On Canvas, in **Deploy and test**, select **Deploy to Foundry**. Review the prompt it drops into chat. + + ![Deploy to Foundry prompt on the canvas](../../_images/app-8-deploy-to-foundry.png) + +17. Check for a deployment confirmation, agent version, status, and link to the agent playground in Foundry. If deployment fails, send the error to Copilot and resolve it in the same project before retrying through Canvas. +18. Select **Test in Foundry Portal** from Canvas to open the deployed agent playground. Rerun all six acceptance checks from steps 9–14 against this deployed version, retaining the paired prompts in one conversation for continuity. Compare its responses with the catalog; if any check fails, ask Copilot to fix it, rerun local tests, redeploy through Canvas, and retest the hosted version. + +## Checkpoint and next steps + +You scaffolded the Backer Concierge, tested its catalog grounding and conversation behavior locally, deployed it to Microsoft Foundry, and retested the hosted version. The checkpoint for this module is a hosted agent that passes all six acceptance checks without inventing missing information. + +Next, you'll use the same Tailspin Toys repository, worktree branch, issue-linked session, Foundry project, selected model deployment, and hosted agent to [connect the agent to the site][next-module]. If you're stopping here, [clean up your Azure resources][cleanup] to avoid ongoing costs. + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#clean-up-your-resources diff --git a/docs/app/8-foundry-canvas/3-connect-to-site.md b/docs/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..33ce7cd5 --- /dev/null +++ b/docs/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "Connect the agent to the site" +description: "Integrate the hosted Backer Concierge through a local credential-safe proxy and test the widget end to end." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/app/8-foundry-canvas/2-build-and-deploy/ + label: Build and deploy the agent +next: + link: /copilot-workshops/app/9-review/ + label: Review and next steps +--- + +This final module connects the tested hosted agent from [Build and deploy the agent][previous-module] to the locally running Tailspin Toys website. + +By the end, you will have: + +- A local Azure Functions proxy that protects Foundry credentials and conversation identifiers. +- An accessible chat widget with verified end-to-end behavior. +- A locally verified integration and a resource cleanup checkpoint. + +## Scenario + +Tailspin Toys backers need catalog advice where they browse games. The Backer Concierge should preserve the conversation, work with keyboard navigation, and handle unavailable information and errors clearly. That convenience must not expose service credentials or internal conversation details to the browser. + +## Resume the hosted-agent checkpoint + +The integration uses the existing hosted agent rather than creating new Foundry resources. + +1. Resume the same Tailspin Toys repository, worktree branch, and **Add a Backer Concierge assistant for catalog questions** issue session from the earlier modules. Confirm the root `azure.yaml`, agent source, and catalog are present, and check the recorded subscription, dedicated resource group, Foundry project, model deployment, and tested hosted-agent version. +2. If resources were cleaned up, restore the relevant [project and model][project-module] and [tested hosted deployment][previous-module] before integration. + +## Build the server-side proxy + +Tailspin Toys is fully pre-rendered. Browser code must never call the hosted agent directly or receive Foundry credentials. A local Azure Functions **server-side credential boundary** authenticates to Foundry and returns only the agent response to the browser. The browser sends each message with an opaque conversation handle; the proxy maps that handle to the Foundry conversation without exposing the underlying identifier. + +The proxy is the only piece of code allowed to access your Azure credentials. For this workshop, the Function and site run locally, with the Astro development server forwarding `/api` requests to the Function. + +> [!IMPORTANT] +> This workshop proxy is for local development only. It must not be deployed 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. + +3. In the same Copilot session, enter: + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. Review the generated proxy and focused tests for request validation, sanitized errors, opaque conversation handles, and the server-only credential boundary. Ask Copilot to run the focused tests and fix any failures. +5. Open another terminal, start the local Function using the command provided by Copilot, and leave it running. +6. Return to chat and ask Copilot to test the local proxy: + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. Inspect the response: it should explain that the catalog doesn't contain prices. Confirm it contains no Foundry token, credential, internal conversation identifier, project endpoint, or stack trace. If the Function cannot be reached or the response leaks details or invents prices, send the sanitized failure to Copilot, fix it, and rerun the proxy tests before continuing. + + ![Local proxy test](../../_images/app-8-local-proxy-test.png) + +## Build and test the chat widget + +With the proxy running, the widget provides the visible conversation on the site without exposing Foundry details. + +8. Ask Copilot to create the site integration: + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. Start the Astro development server in another terminal using the command provided by Copilot. Keep both the site and the local Function running. +10. Ask Copilot to run the end-to-end tests: + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. Review the report and verify the claimed behavior in the browser, including keyboard use and the two-turn conversation from the [hosted-agent acceptance checks][agent-checks]. Confirm browser requests go through `/api/concierge` with an opaque handle, not directly to Foundry, and responses expose no credentials or internal Foundry identifiers. Check that recommendations and missing-data answers stay within the catalog boundary. Address failing tests with Copilot, restart the affected local service if needed, and rerun the tests. + + ![End-to-end test results for the Backer Concierge widget](../../_images/app-8-e2e-test-results.png) + +## Checkpoint and next steps + +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 website 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 both local services and [clean up your Azure resources][cleanup]. Then continue to [Review and next steps][core-review] on the core workshop route. + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#inspect-the-agent-locally +[cleanup]: ../#clean-up-your-resources +[core-review]: ../../9-review/ diff --git a/docs/app/8-foundry-canvas/README.md b/docs/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..849725c9 --- /dev/null +++ b/docs/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "Optional: Incorporate Foundry" +slug: app/8-foundry-canvas +description: "Build a catalog-grounded Backer Concierge with Microsoft Foundry Canvas, with safe stopping points along the way." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/app/9-review/ + label: Review and next steps +next: + link: /copilot-workshops/app/8-foundry-canvas/1-project-and-model/ + label: Prepare project and model +--- + +This optional journey adds a **Backer Concierge** to Tailspin Toys using Microsoft Foundry Canvas in the GitHub Copilot app. It moves from a catalog-grounded model experiment to a hosted agent and then a local website integration. + +## The journey + +Each module ends with a checkpoint and a safe stopping point. The same Tailspin Toys repository, worktree branch, issue-linked session, Foundry project, and model deployment carry through the journey. + +- [Prepare project and model][module-1] establishes the catalog boundary, creates the project and model deployment, and checks them in Canvas. +- [Build and deploy the agent][module-2] scaffolds the Backer Concierge, tests it locally, and deploys and retests the hosted agent. +- [Connect the agent to the site][module-3] adds a local credential-safe proxy, an accessible chat widget, and end-to-end tests. + +> [!IMPORTANT] +> Microsoft Foundry Canvas and hosted agents are in public preview. +> +> This journey creates billable Azure resources, including a model deployment and, from module 2, a hosted agent. Subscription, region, quota, and estimated cost need approval before resource creation. Cleanup applies even when stopping after only the project and model. + +1. Begin with [Prepare project and model][module-1], keeping the work in your Tailspin Toys repository rather than this workshop content repository. +2. If you'd rather finish the core workshop, continue to [Review and next steps][core-review]. + +## 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, Azure Function, or Astro development server you started in its terminal. +2. If you deployed the hosted agent in module 2 or 3, open a terminal in the same Tailspin Toys worktree and use 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 + +The Microsoft documentation describes Canvas, hosted deployments, and their permissions. + +- [What is Microsoft Foundry Canvas?][foundry-canvas] +- [Deploy your first hosted agent with Foundry Canvas][hosted-agent-quickstart] +- [Hosted agent permissions][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/app/9-review.md b/docs/app/9-review.md index ea75d153..ad6ec0b5 100644 --- a/docs/app/9-review.md +++ b/docs/app/9-review.md @@ -4,6 +4,7 @@ description: "Recap the GitHub Copilot app harness, automate recurring work, and authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- Over the last several lessons, you took a feature from idea to merge with the GitHub Copilot app, including: @@ -62,6 +63,8 @@ The best way to improve with any tool is to keep using it! Use it for production If you'd like to explore more of the GitHub Copilot ecosystem, check out the [VS Code harness](../../vscode/), the [Copilot CLI harness](../../cli/), or the [Cloud agent harness](../../cloud/). +For an optional extension using Microsoft Foundry Canvas, explore [Optional: Incorporate Foundry][foundry-canvas]. + ## Resources - [About the GitHub Copilot app][about-copilot-app] @@ -81,3 +84,4 @@ If you'd like to explore more of the GitHub Copilot ecosystem, check out the [VS [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models [deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ diff --git a/docs/app/README.md b/docs/app/README.md index c5c15025..ba58de46 100644 --- a/docs/app/README.md +++ b/docs/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 The **[GitHub Copilot app](https://docs.github.com/copilot/concepts/agents/github-copilot-app)** is a desktop application built on Copilot CLI that brings agent-driven development into a single, focused workspace. It adds parallel agent sessions, switchable session modes, shared canvases, and native GitHub issue and pull request management — including **Agent Merge**, which shepherds a pull request through rebases, review feedback, CI fixes, and merge. -Across these lessons you'll install the app and set up your project, then get oriented in the app's workspace and the backlog the template seeded for you. You'll start with a small change — adding a star rating — then add a custom instructions standard from an issue, build a filtering feature in an isolated agent session, and verify it with a reusable skill. You'll add the Playwright MCP server to explore the feature in a real browser, then climb a ladder of merge automation that ends with **Agent Merge** landing your pull request. Finally you'll collaborate on a shared canvas, optionally build a hosted agent with Microsoft Foundry Canvas, and automate recurring work — a complete loop from idea to merged feature. +Across these lessons you'll install the app and set up your project, then get oriented in the app's workspace and the backlog the template seeded for you. You'll start with a small change — adding a star rating — then add a custom instructions standard from an issue, build a filtering feature in an isolated agent session, and verify it with a reusable skill. You'll add the Playwright MCP server to explore the feature in a real browser, then climb a ladder of merge automation that ends with **Agent Merge** landing your pull request. Finally you'll collaborate on a shared canvas and automate recurring work — a complete loop from idea to merged feature. An optional three-module extension uses Microsoft Foundry Canvas to prepare a project and model, build and deploy an agent, and connect it to the site. ## Lessons @@ -22,8 +22,8 @@ Across these lessons you'll install the app and set up your project, then get or | [5. Testing with Playwright MCP][ex5] | External Tools | Add the Playwright MCP server and explore your feature in a browser | | [6. Merging with Agent Merge][ex6] | Merge | Let Agent Merge fix and land your filtering pull request | | [7. Planning with canvases][ex7] | Collaboration | Create a shared canvas to plan and track your work | -| [8. Build a Backer Concierge Agent (Optional)][foundry-canvas] | AI agents | Build, test, deploy, and integrate a catalog-grounded hosted agent | | [9. Review and next steps][ex9] | Summary | Automate recurring tasks and explore what's next | +| [Optional: Incorporate Foundry][foundry-canvas] | AI agents | Prepare a project and model, build and deploy a grounded agent, and connect it to the site | ## Prerequisites diff --git a/docs/es-es/app/7-canvases.md b/docs/es-es/app/7-canvases.md index c14ba706..693e1c2b 100644 --- a/docs/es-es/app/7-canvases.md +++ b/docs/es-es/app/7-canvases.md @@ -4,6 +4,9 @@ description: "Crea un lienzo compartido y dirigido por agentes en la aplicación authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/es-es/app/9-review/ + label: "Repaso y pasos siguientes" --- Hasta ahora has dirigido a los agentes mediante el chat. Sin embargo, gran parte del trabajo no reside en una conversación, sino en un tablero, un documento o una lista de comprobación. Los **lienzos** ofrecen al agente y a ti una superficie compartida para ese tipo de trabajo, directamente en la aplicación. En esta lección crearás un lienzo sencillo para planificar y realizar el seguimiento de la lista de trabajo pendiente que has estado abordando. @@ -113,7 +116,7 @@ Has creado una superficie compartida en la que puedes colaborar con el agente. E - has guardado y combinado el lienzo con el repositorio mediante Agent Merge. - has abierto el lienzo en una sesión nueva y lo has utilizado para empezar a trabajar. -Con la lista de trabajo pendiente organizada, puedes terminar aquí o continuar. Si quieres crear un agente de IA hospedado a partir del catálogo de Tailspin Toys, continúa con la [lección opcional sobre Backer Concierge][next-lesson]. De lo contrario, pasa a la [Lección 9 - Repaso y pasos siguientes][review-lesson]. +Con la lista de trabajo pendiente organizada, continúa con el [repaso de lo que has creado][next-lesson]. Si quieres realizar una ampliación opcional con Microsoft Foundry Canvas, explora [Opcional: Incorporar Foundry][foundry-canvas]. ## Recursos @@ -121,8 +124,8 @@ Con la lista de trabajo pendiente organizada, puedes terminar aquí o continuar. - [Lienzos en Awesome Copilot][awesome-copilot-canvases] - [Acerca de la aplicación GitHub Copilot][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/es-es/app/8-foundry-canvas/1-project-and-model.md b/docs/es-es/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..9b4908ab --- /dev/null +++ b/docs/es-es/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "Preparar el proyecto y el modelo" +description: "Exporta el catálogo de Tailspin, crea un proyecto de Foundry y una implementación de modelo, y valídalos en Canvas." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/es-es/app/8-foundry-canvas/ + label: "Opcional: Incorporar Foundry" +next: + link: /copilot-workshops/es-es/app/8-foundry-canvas/2-build-and-deploy/ + label: Crear e implementar el agente +--- + +Este primer módulo prepara los datos y los recursos de Azure para Backer Concierge. Todavía no se necesita código del agente ni una implementación hospedada. + +Al terminar, tendrás: + +- Una exportación del catálogo con límites explícitos sobre la información en la que se pueden basar las respuestas. +- Un proyecto de Foundry y una implementación de modelo elegida según los requisitos de la funcionalidad. +- Una implementación validada en Canvas y una comprobación básica del modelo limitada al catálogo. + +## Escenario + +Quienes apoyan los juegos de Tailspin Toys pueden filtrarlos por categoría y editor, pero preguntas como *¿Qué juegos serían adecuados para alguien a quien le encantan los juegos de palabras sobre Git?* no se responden con un menú desplegable. Backer Concierge debe recomendar solo juegos del catálogo de Tailspin y nunca inventar juegos, editores, valoraciones, importes recaudados, cifras de patrocinadores, precios, números de jugadores, duraciones de partida ni fechas de lanzamiento. Un catálogo fiable y un modelo adecuado son la base de esas respuestas. + +## Preparar las herramientas y la sesión de la incidencia + +La configuración conecta la aplicación GitHub Copilot con Azure y mantiene unido todo el trabajo de la funcionalidad. + +1. Confirma que tienes una suscripción de Azure. Si necesitas una, las opciones disponibles incluyen una [suscripción gratuita de Azure con 200 $ de crédito][azure-free] o [Azure for Students con 100 $ de crédito][azure-students]. +2. Instala la [CLI de Azure][install-azure-cli] para tu sistema operativo y verifica la instalación con `az version`. +3. Instala [Azure Developer CLI][install-azd] y verifica con `azd version` que esté instalada la versión 1.27.1 o posterior. +4. Abre la aplicación GitHub Copilot, abre **Customize** y selecciona **Plugins**. Busca `microsoft-foundry` y selecciona **Install** para el complemento Microsoft Foundry, que incluye Canvas y las habilidades de Foundry. + + ![Instalar el complemento Microsoft Foundry](../../../_images/app-8-install-foundry-plugin.png) + +5. En **Customize**, selecciona **Plugins**, busca `azure` o selecciónalo en la lista **Featured** y, después, selecciona **Install** para el complemento Azure. +6. En la pestaña **My work**, busca y abre la incidencia titulada **Add a Backer Concierge assistant for catalog questions** en el repositorio de Tailspin Toys. Selecciona **New session** para iniciar una sesión vinculada a la incidencia en un worktree nuevo. Conserva este repositorio, esta rama del worktree y esta sesión de la incidencia durante los tres módulos. +7. Escribe `/microsoft-foundry` y, después, `/azure` para confirmar que ambas habilidades están instaladas y disponibles; no envíes ninguna indicación todavía. Si un complemento no aparece de inmediato, reinicia la aplicación, vuelve a esta misma sesión de la incidencia y compruébalo de nuevo. + +## Generar la exportación del catálogo + +El repositorio de ejemplo incluye un script de exportación que proporciona al agente un archivo que puede leer. + +8. En esta sesión del worktree vinculada a la incidencia, sustituye la indicación predeterminada `/fix-issue` del cuadro de indicaciones por: + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. Revisa la salida de los comandos. Copilot debería ejecutar el equivalente a: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![Generar la exportación del catálogo](../../../_images/app-8-generate-catalog-export.png) + +10. Abre `db/catalog.json` y confirma que contiene 21 juegos con título, descripción, categoría, editor y valoración por estrellas. Comprueba el campo `note`: el catálogo no contiene importes recaudados, cifras de patrocinadores, niveles de aportación ni fechas de lanzamiento. Considera también como no disponibles los precios, números de jugadores y duraciones de partida que falten, en lugar de rellenar los huecos con conocimientos externos. Si la exportación falla o es distinta, pide a Copilot que lo investigue y vuelva a ejecutarla antes de continuar. + + ![Exportación del catálogo abierta en la aplicación Copilot](../../../_images/app-8-view-catalog.png) + +## Configurar un proyecto de Foundry y un modelo + +Crear primero el proyecto y la implementación en el chat permite que Canvas se conecte solo a recursos que ya existen. + +11. Selecciona **+**, selecciona **Terminal** e inicia sesión en Azure: + + ```bash + az login + ``` + +12. Comprueba la suscripción seleccionada y enumera sus grupos de recursos: + + ```bash + az account show --output table + az group list --output table + ``` + + Si la suscripción no es correcta, ejecuta `az account set --subscription ` y repite ambos comandos. + + Si aparece `rg-tailspin-toys`, examina sus recursos: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Si el grupo contiene recursos ajenos o compartidos, detente y elige un nombre dedicado antes de utilizar la indicación siguiente. Sustituye los nombres de ejemplo de todas las indicaciones y comandos posteriores por los nombres que apruebes. +13. En la misma sesión de la incidencia, introduce: + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![Crear un proyecto de Foundry](../../../_images/app-8-foundry-project-created.png) + +14. Pide a Copilot que recomiende un modelo. Los criterios de aceptación de la incidencia ya están en el contexto porque la sesión se inició desde ella: + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. Confirma que Copilot carga la habilidad `microsoft-foundry` y elige un modelo disponible según sus ventajas e inconvenientes. La guía de inicio rápido de agentes hospedados de Microsoft Foundry utiliza actualmente `gpt-5.4-mini`, pero la disponibilidad y la cuota varían según la región. + + ![Seleccionar un modelo](../../../_images/app-8-select-model.png) + +16. Pide a Copilot que implemente el modelo elegido y revisa el proyecto de destino y el coste antes de aprobarlo: + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> La disponibilidad de los modelos cambia con el tiempo. La opción adecuada es el modelo que Copilot confirme que está disponible en tu proyecto, no un modelo fijado de antemano en este módulo. + +## Validar el modelo y realizar una comprobación básica en Canvas + +Esta comprobación verifica el proyecto y el modelo antes de que exista código del agente. Una comprobación básica del modelo no sustituye las pruebas del módulo 2 que verifican que el agente hospedado se basa en el catálogo. + +17. Selecciona **+**, después **Canvas** y, a continuación, **Microsoft Foundry (Preview)**. +18. Abre el menú **More options** en la esquina superior derecha de Canvas y selecciona **Sign in**. +19. Selecciona el proyecto de Foundry **tailspin-toys**. Expande **Models** y confirma que la implementación aparece con el nombre y el estado esperados. + + ![Validar el proyecto y el modelo en Canvas](../../../_images/app-8-validate-project-model.png) + +20. En la misma sesión, escribe: + + ```plaintext + Usa la habilidad de Microsoft Foundry para probar directamente el modelo que he implementado en el proyecto tailspin-toys sin crear un agente. Basa la respuesta en el contenido de @db/catalog.json y pregunta: «Me encantan los juegos de rompecabezas sobre la búsqueda de errores. ¿Qué debería apoyar y cuánto dinero ha recaudado?». Muéstrame la respuesta y metadatos útiles, como los tokens utilizados y el tiempo de respuesta, solo si están disponibles. Usa mi sesión de Azure existente. No muestres credenciales, modifiques archivos ni crees recursos. + ``` + +21. Revisa la respuesta. Debe recomendar únicamente un juego real de `db/catalog.json`, usar el título, el editor y la valoración correctos, y explicar que la información de financiación no está disponible. Si el modelo inventa un juego, datos del catálogo o una cantidad de financiación, compara otro modelo recomendado antes de continuar. + +> [!NOTE] +> Canvas recuerda el proyecto seleccionado cuando se vuelve a abrir. Sus etapas son **Create new hosted agents** para generar la estructura inicial, **Build current hosted agent** para conectar modelos, conjuntos de herramientas, habilidades y medidas de protección, y **Deploy and test** para las ejecuciones locales y la implementación en Microsoft Foundry. + +## Punto de control y pasos siguientes + +Has preparado las herramientas de Azure, exportado el catálogo y probado un modelo implementado con las reglas de fundamentación de Backer Concierge. El punto de control de este módulo es un modelo que recomienda juegos reales del catálogo sin inventar información que no está disponible. + +A continuación, usarás el mismo repositorio de Tailspin Toys, la misma rama del worktree, la misma sesión vinculada a la incidencia, el mismo proyecto de Foundry y la implementación del modelo seleccionada para [crear e implementar el agente][next-module]. Si te detienes aquí, [limpia los recursos de Azure][cleanup] para evitar costes continuos. + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#limpiar-los-recursos diff --git a/docs/es-es/app/8-foundry-canvas/2-build-and-deploy.md b/docs/es-es/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..a2c83233 --- /dev/null +++ b/docs/es-es/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,160 @@ +--- +title: "Crear e implementar el agente" +description: "Genera la estructura inicial de Backer Concierge en Canvas, inspecciónalo en local e impleméntalo y vuelve a probarlo en Foundry." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/es-es/app/8-foundry-canvas/1-project-and-model/ + label: Preparar el proyecto y el modelo +next: + link: /copilot-workshops/es-es/app/8-foundry-canvas/3-connect-to-site/ + label: Conectar el agente al sitio +--- + +Este módulo convierte el proyecto, la implementación del modelo y el catálogo de [Preparar el proyecto y el modelo][previous-module] en un Backer Concierge hospedado mediante Microsoft Foundry Canvas. + +Al terminar, tendrás: + +- La estructura inicial de un agente con los datos del catálogo empaquetados y pruebas específicas. +- Evidencias locales para cada criterio de aceptación del catálogo y de la conversación. +- Una versión del agente implementada y probada de nuevo en Foundry. + +## Escenario + +Tailspin Toys necesita un asistente que pueda responder a preguntas reales sobre el catálogo, reconocer cuándo falta información y recordar los juegos mencionados en una conversación. El servicio debe ganarse esa confianza antes de formar parte del sitio de la tienda. + +## Preparar las herramientas de implementación + +La inspección y la implementación del agente hospedado utilizan Azure Developer CLI a través de Canvas; se reutilizan el proyecto y el modelo de Foundry existentes. + +1. Retoma la misma sesión vinculada a la incidencia **Add a Backer Concierge assistant for catalog questions** del módulo 1. Confirma que `db/catalog.json` está intacto, que estás conectado a la suscripción y al proyecto de Foundry correctos, y que la implementación del modelo sigue disponible. Si se eliminaron los recursos, repite primero la [configuración del proyecto y del modelo][previous-module] que corresponda. + +2. Selecciona **+**, selecciona **Terminal** e inicia sesión en Azure Developer CLI; completa la autenticación en el navegador cuando se te solicite: + + ```bash + azd auth login + ``` + +3. Ejecuta `azd config show` para verificar la suscripción de Azure. Si está vacía o es incorrecta, actualízala con `azd config set defaults.subscription ` y vuelve a ejecutar `azd config show` para confirmar el cambio. +## Generar la estructura inicial de Backer Concierge + +Canvas genera el código, la estructura de carpetas y el archivo `azure.yaml` de la raíz que conectan Backer Concierge con la implementación del modelo existente. + +4. En la versión preliminar de **Create new hosted agents**, introduce: + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + Canvas envía a Copilot la indicación y el contexto de la suscripción actual y del proyecto de Foundry. Busca ejemplos de Agent Framework + Responses API; puede aparecer una opción como **Agent with Local Tools (Responses, Agent Framework, Python)**. + + ![Generar la estructura inicial del agente Backer Concierge en Canvas](../../../_images/app-8-scaffold-backer-concierge.png) + +5. Revisa los cambios de Copilot en la pestaña **Files** y compáralos con este punto de control. Los nombres de los archivos generados dentro de `src` pueden variar, pero los límites del proyecto y la ubicación de `azure.yaml` deberían coincidir: + + - El agente reside en `agent/backer-concierge`. + - Un único archivo `azure.yaml` en la raíz del repositorio contiene un servicio con `host: azure.ai.agent`. + - El agente que se va a implementar incluye su propia copia generada del catálogo. + - Las pruebas específicas cubren los requisitos para que las respuestas se basen en el catálogo. + - No se incluyen credenciales ni archivos de entorno locales. + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. Pide a Copilot que ejecute las pruebas específicas y corrija cualquier fallo antes de continuar con **Deploy and test**. + +## Inspeccionar el agente en local + +**Inspect Locally** ejecuta `azd ai agent run` en el terminal integrado de Copilot, espera a que se inicie el agente hospedado y abre Agent Inspector integrado. + +7. En **Deploy and test**, selecciona **Inspect Locally** y espera a que se abra Agent Inspector. + +> [!NOTE] +> La primera ejecución local puede tardar varios minutos mientras `azd` crea un entorno e instala las dependencias. + +8. Si el inspector no puede conectarse, confirma que ningún otro proceso esté utilizando el puerto necesario, envía el error a Copilot y vuelve a intentarlo cuando se haya solucionado el problema. +9. Prueba una **recomendación basada en el catálogo** en Agent Inspector: + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + Resultado esperado: menciona solo títulos reales del catálogo y utiliza la información correcta de cada título. + + ![Recomendación basada en el catálogo en Agent Inspector](../../../_images/app-8-grounded-recommendation.png) + +10. Prueba una **pregunta trampa para detectar alucinaciones**: + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + Resultado esperado: explica que el catálogo no registra la financiación ni los patrocinadores y, después, ofrece información que sí está disponible. + +11. Prueba la **presión para responder sobre juegos ajenos al catálogo**: + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + Resultado esperado: indica que Wingspan no está en el catálogo, no lo describe con conocimientos externos y redirige la respuesta hacia títulos reales de Tailspin. + +12. Prueba una **petición imprecisa**: + + ```text + Recommend me something good. + ``` + + Resultado esperado: hace una pregunta breve para aclarar la petición y todavía no recomienda ningún título. + +13. Prueba la **exactitud de la clasificación**: + + ```text + What are your three highest rated games? + ``` + + Resultado esperado: devuelve las tres entradas del catálogo mejor valoradas en el orden correcto y con las valoraciones correctas. + +14. Prueba la **continuidad de la conversación** enviando estas indicaciones en la misma conversación: + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + Resultado esperado: la segunda respuesta se refiere solo a los dos títulos de la primera respuesta y compara correctamente sus valoraciones del catálogo. + +15. Compara cada respuesta con `db/catalog.json` y con los criterios de aceptación de la incidencia. Confirma que el agente nunca inventa juegos, editores, valoraciones, importes recaudados, cifras de patrocinadores, precios, números de jugadores, duraciones de partida ni fechas de lanzamiento. Si Agent Inspector comunica un error o una respuesta rebasa los límites de la información del catálogo, copia el resultado en el área de indicaciones de Canvas y pide a Copilot que lo corrija. Reinicia la inspección local y vuelve a ejecutar la prueba fallida después de cada cambio; después, confirma que las seis comprobaciones se superan antes de implementar. + +## Implementar el agente hospedado y volver a probarlo + +Canvas utiliza `azd` para implementar el agente probado. Foundry empaqueta el código fuente del servicio, resuelve las dependencias, lo compila de forma remota y lo publica en Microsoft Foundry. + +16. En Canvas, en **Deploy and test**, selecciona **Deploy to Foundry**. Revisa la indicación que inserta en el chat. + + ![Indicación Deploy to Foundry en el lienzo](../../../_images/app-8-deploy-to-foundry.png) + +17. Comprueba que aparezcan una confirmación de la implementación, la versión del agente, el estado y un enlace al área de pruebas del agente en Foundry. Si la implementación falla, envía el error a Copilot y resuélvelo en el mismo proyecto antes de volver a intentarlo a través de Canvas. +18. Selecciona **Test in Foundry Portal** desde Canvas para abrir el área de pruebas del agente implementado. Vuelve a ejecutar las seis comprobaciones de aceptación de los pasos 9–14 con esta versión implementada; mantén las dos indicaciones enlazadas en una misma conversación para comprobar la continuidad. Compara las respuestas con el catálogo; si falla alguna comprobación, pide a Copilot que lo corrija, vuelve a ejecutar las pruebas locales, implementa de nuevo a través de Canvas y vuelve a probar la versión hospedada. + +## Punto de control y pasos siguientes + +Has generado la estructura inicial de Backer Concierge, probado en local su fundamentación en el catálogo y su comportamiento durante la conversación, lo has implementado en Microsoft Foundry y has vuelto a probar la versión hospedada. El punto de control de este módulo es un agente hospedado que supera las seis comprobaciones de aceptación sin inventar información que no está disponible. + +A continuación, usarás el mismo repositorio de Tailspin Toys, la misma rama del worktree, la misma sesión vinculada a la incidencia, el mismo proyecto de Foundry, la implementación del modelo seleccionada y el agente hospedado para [conectar el agente al sitio][next-module]. Si te detienes aquí, [limpia los recursos de Azure][cleanup] para evitar costes continuos. + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#limpiar-los-recursos diff --git a/docs/es-es/app/8-foundry-canvas/3-connect-to-site.md b/docs/es-es/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..401c65e8 --- /dev/null +++ b/docs/es-es/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "Conectar el agente al sitio" +description: "Integra el Backer Concierge hospedado mediante un proxy local que protege las credenciales y prueba el widget de extremo a extremo." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/es-es/app/8-foundry-canvas/2-build-and-deploy/ + label: Crear e implementar el agente +next: + link: /copilot-workshops/es-es/app/9-review/ + label: Repaso y pasos siguientes +--- + +Este último módulo conecta el agente hospedado probado en [Crear e implementar el agente][previous-module] con el sitio web de Tailspin Toys que se ejecuta en local. + +Al terminar, tendrás: + +- Un proxy local de Azure Functions que protege las credenciales de Foundry y los identificadores de conversación. +- Un widget de chat accesible con un comportamiento verificado de extremo a extremo. +- Una integración verificada en local y un punto de control de limpieza de recursos. + +## Escenario + +Quienes apoyan los juegos de Tailspin Toys necesitan asesoramiento sobre el catálogo donde consultan los juegos. Backer Concierge debe conservar la conversación, funcionar con la navegación por teclado y gestionar de forma clara los errores y la información no disponible. Esa comodidad no debe exponer al navegador las credenciales del servicio ni los detalles internos de la conversación. + +## Retomar el punto de control del agente hospedado + +La integración utiliza el agente hospedado existente en lugar de crear nuevos recursos de Foundry. + +1. Retoma el mismo repositorio de Tailspin Toys, la misma rama del worktree y la misma sesión de la incidencia **Add a Backer Concierge assistant for catalog questions** de los módulos anteriores. Confirma que estén presentes el archivo `azure.yaml` de la raíz, el código fuente del agente y el catálogo, y comprueba la suscripción registrada, el grupo de recursos dedicado, el proyecto de Foundry, la implementación del modelo y la versión probada del agente hospedado. +2. Si se eliminaron los recursos, restaura el [proyecto y el modelo][project-module] y la [implementación hospedada probada][previous-module] que correspondan antes de realizar la integración. + +## Crear el proxy del lado del servidor + +Tailspin Toys está completamente prerrenderizado. El código del navegador nunca debe llamar directamente al agente hospedado ni recibir credenciales de Foundry. Un **límite de protección de credenciales del lado del servidor**, implementado con Azure Functions en local, se autentica en Foundry y devuelve al navegador solo la respuesta del agente. El navegador envía cada mensaje con una referencia opaca a la conversación; el proxy asocia esa referencia con la conversación de Foundry sin exponer el identificador subyacente. + +El proxy es la única parte del código que puede acceder a las credenciales de Azure. En este taller, la función y el sitio se ejecutan en local, y el servidor de desarrollo de Astro reenvía las solicitudes de `/api` a la función. + +> [!IMPORTANT] +> Este proxy del taller es solo para desarrollo local. No debe implementarse como un punto de conexión público anónimo. Una integración de producción necesita un diseño de autenticación y control de abusos específico de la aplicación que incluya límites de frecuencia o cuotas adecuados, restricciones de CORS, supervisión y controles de costes. + +3. En la misma sesión de Copilot, introduce: + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. Revisa el proxy generado y las pruebas específicas para comprobar la validación de solicitudes, los errores sin datos sensibles, las referencias opacas a las conversaciones y el límite de protección de credenciales exclusivo del servidor. Pide a Copilot que ejecute las pruebas específicas y corrija cualquier fallo. +5. Abre otro terminal, inicia la función local con el comando proporcionado por Copilot y déjala en ejecución. +6. Vuelve al chat y pide a Copilot que pruebe el proxy local: + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. Inspecciona la respuesta: debería explicar que el catálogo no contiene precios. Confirma que no contiene ningún token de Foundry, credencial, identificador interno de conversación, punto de conexión del proyecto ni traza de la pila. Si no se puede acceder a la función, o la respuesta filtra detalles o inventa precios, envía el fallo sin datos sensibles a Copilot, corrígelo y vuelve a ejecutar las pruebas del proxy antes de continuar. + + ![Prueba del proxy local](../../../_images/app-8-local-proxy-test.png) + +## Crear y probar el widget de chat + +Con el proxy en ejecución, el widget muestra la conversación en el sitio sin exponer detalles de Foundry. + +8. Pide a Copilot que cree la integración del sitio: + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. Inicia el servidor de desarrollo de Astro en otro terminal con el comando proporcionado por Copilot. Mantén en ejecución tanto el sitio como la función local. +10. Pide a Copilot que ejecute las pruebas de extremo a extremo: + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. Revisa el informe y verifica en el navegador el comportamiento que describe, incluido el uso del teclado y la conversación de dos turnos de las [comprobaciones de aceptación del agente hospedado][agent-checks]. Confirma que las solicitudes del navegador pasan por `/api/concierge` con una referencia opaca, no directamente a Foundry, y que las respuestas no exponen credenciales ni identificadores internos de Foundry. Comprueba que las recomendaciones y las respuestas sobre datos ausentes se mantengan dentro de los límites del catálogo. Resuelve las pruebas fallidas con Copilot, reinicia el servicio local afectado si es necesario y vuelve a ejecutar las pruebas. + + ![Resultados de las pruebas de extremo a extremo del widget Backer Concierge](../../../_images/app-8-e2e-test-results.png) + +## Punto de control y pasos siguientes + +Has creado un proxy local que protege las credenciales, conectado un widget de chat accesible y verificado el flujo completo de la conversación con el Backer Concierge hospedado. El punto de control de este módulo es una integración del sitio web probada en local que conserva 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 ambos servicios locales y [limpia los recursos de Azure][cleanup]. Después, continúa con [Repaso y pasos siguientes][core-review] en la ruta principal del taller. + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#inspeccionar-el-agente-en-local +[cleanup]: ../#limpiar-los-recursos +[core-review]: ../../9-review/ diff --git a/docs/es-es/app/8-foundry-canvas/README.md b/docs/es-es/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..4888bf7c --- /dev/null +++ b/docs/es-es/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "Opcional: Incorporar Foundry" +slug: es-es/app/8-foundry-canvas +description: "Crea un Backer Concierge basado en el catálogo con Microsoft Foundry Canvas, con puntos seguros para detenerte durante el recorrido." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/es-es/app/9-review/ + label: Repaso y pasos siguientes +next: + link: /copilot-workshops/es-es/app/8-foundry-canvas/1-project-and-model/ + label: Preparar el proyecto y el modelo +--- + +Este recorrido opcional añade un **Backer Concierge** a Tailspin Toys mediante Microsoft Foundry Canvas en la aplicación GitHub Copilot. Parte de un experimento con un modelo basado en el catálogo, continúa con un agente hospedado y termina con una integración local en el sitio web. + +## El recorrido + +Cada módulo termina con un punto de control y un punto seguro para detenerte. Durante todo el recorrido se mantienen el mismo repositorio de Tailspin Toys, la misma rama del worktree, la misma sesión vinculada a la incidencia, el mismo proyecto de Foundry y la misma implementación del modelo. + +- [Preparar el proyecto y el modelo][module-1] establece los límites del catálogo, crea el proyecto y la implementación del modelo, y los comprueba en Canvas. +- [Crear e implementar el agente][module-2] genera la estructura inicial de Backer Concierge, lo prueba en local, e implementa y vuelve a probar el agente hospedado. +- [Conectar el agente al sitio][module-3] añade un proxy local que protege las credenciales, un widget de chat accesible y pruebas de extremo a extremo. + +> [!IMPORTANT] +> Microsoft Foundry Canvas y los agentes hospedados están en versión preliminar pública. +> +> Este recorrido crea recursos de Azure que generan costes, incluida una implementación de modelo y, a partir del módulo 2, un agente hospedado. Antes de crear recursos, es necesario aprobar la suscripción, la región, la cuota y el coste estimado. La limpieza también se aplica si te detienes tras crear únicamente el proyecto y el modelo. + +1. Empieza por [Preparar el proyecto y el modelo][module-1] y realiza el trabajo en el repositorio de Tailspin Toys, no en este repositorio de contenido del taller. +2. Si prefieres terminar el taller principal, continúa con [Revisión y pasos siguientes][core-review]. + +## Limpiar los recursos + +Cuando termines de experimentar en cualquier punto de control, elimina los recursos de Azure para evitar costes no deseados. La limpieza elimina recursos necesarios para módulos posteriores, por lo que tendrás que volver a crearlos si quieres continuar después. + +> [!WARNING] +> Elimina `rg-tailspin-toys` únicamente si está dedicado a este ejercicio y no contiene ningún recurso que necesites conservar. Si eliminas un grupo de recursos compartido, también se eliminarán recursos que no pertenecen al ejercicio. +> +> Si aprobaste otro nombre para el grupo de recursos en el módulo 1, sustituye `rg-tailspin-toys` por ese nombre en todos los comandos siguientes. + +1. Detén desde sus terminales cualquier proceso local de Agent Inspector, Azure Function o servidor de desarrollo de Astro que hayas iniciado. +2. Si has implementado el agente hospedado en el módulo 2 o 3, abre un terminal en el mismo worktree de Tailspin Toys, usa el mismo entorno de `azd` y ejecuta: + + ```bash + azd down --purge + ``` + +3. Comprueba la suscripción seleccionada y si todavía existe el grupo de recursos del taller: + + ```bash + az account show --output table + az group exists --name rg-tailspin-toys + ``` + + Si el comando devuelve `false`, la limpieza ha terminado. Si devuelve `true`, examina los recursos del grupo: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Verifica que todos los recursos restantes pertenezcan a este ejercicio. Si te has detenido después del módulo 1, aún debes limpiar el proyecto de Foundry y el modelo aunque no hayas implementado un servicio de `azd`. +4. Si el grupo de recursos dedicado del taller todavía existe 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 comando siguiente hasta que devuelva `false`: + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## Recursos + +La documentación de Microsoft describe Canvas, las implementaciones hospedadas y sus permisos. + +- [¿Qué es Microsoft Foundry Canvas?][foundry-canvas] +- [Implementar el primer agente hospedado con Foundry Canvas][hosted-agent-quickstart] +- [Permisos de los agentes hospedados][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/es-es/app/9-review.md b/docs/es-es/app/9-review.md index 3ca0fa27..dfcce14a 100644 --- a/docs/es-es/app/9-review.md +++ b/docs/es-es/app/9-review.md @@ -4,6 +4,7 @@ description: "Repasa el recorrido de la aplicación GitHub Copilot, automatiza e authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- Durante las últimas lecciones, has llevado una funcionalidad desde la idea hasta la combinación mediante la aplicación GitHub Copilot. Entre otras cosas, has aprendido a: @@ -62,6 +63,8 @@ La mejor forma de mejorar con cualquier herramienta es seguir utilizándola. Ús Para explorar más elementos del ecosistema de GitHub Copilot, consulta el [recorrido de VS Code](../../vscode/), el [recorrido de Copilot CLI](../../cli/) o el [recorrido del agente en la nube](../../cloud/). +Si quieres realizar una ampliación opcional con Microsoft Foundry Canvas, explora [Opcional: Incorporar Foundry][foundry-canvas]. + ## Recursos - [Acerca de la aplicación GitHub Copilot][about-copilot-app] @@ -80,4 +83,5 @@ Para explorar más elementos del ecosistema de GitHub Copilot, consulta el [reco [chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models -[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ \ No newline at end of file diff --git a/docs/es-es/app/README.md b/docs/es-es/app/README.md index b5ba3e49..56ea701e 100644 --- a/docs/es-es/app/README.md +++ b/docs/es-es/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 La [**aplicación GitHub Copilot**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) es una aplicación de escritorio basada en Copilot CLI que reúne el desarrollo dirigido por agentes en un único espacio de trabajo específico. Añade sesiones de agente en paralelo, modos de sesión intercambiables, lienzos compartidos y gestión nativa de incidencias y solicitudes de incorporación de cambios de GitHub, incluido **Agent Merge**, que guía una solicitud durante reorganizaciones de base, comentarios de revisión, correcciones de CI y la combinación. -A lo largo de estas lecciones instalarás la aplicación y configurarás el proyecto. Después, conocerás el espacio de trabajo de la aplicación y la lista de trabajo pendiente que la plantilla ha creado para ti. Empezarás con un cambio pequeño, añadir una valoración por estrellas, y luego añadirás desde una incidencia un estándar de instrucciones personalizadas, crearás una funcionalidad de filtrado en una sesión de agente aislada y la verificarás con una habilidad reutilizable. Añadirás el servidor MCP de Playwright para explorar la funcionalidad en un navegador real y avanzarás por niveles crecientes de automatización de combinaciones hasta que **Agent Merge** incorpore la solicitud. Por último, colaborarás en un lienzo compartido, podrás crear opcionalmente un agente hospedado con Microsoft Foundry Canvas y automatizarás el trabajo recurrente: un ciclo completo desde la idea hasta una funcionalidad combinada. +A lo largo de estas lecciones instalarás la aplicación y configurarás el proyecto. Después, conocerás el espacio de trabajo de la aplicación y la lista de trabajo pendiente que la plantilla ha creado para ti. Empezarás con un cambio pequeño, añadir una valoración por estrellas, y luego añadirás desde una incidencia un estándar de instrucciones personalizadas, crearás una funcionalidad de filtrado en una sesión de agente aislada y la verificarás con una habilidad reutilizable. Añadirás el servidor MCP de Playwright para explorar la funcionalidad en un navegador real y avanzarás por niveles crecientes de automatización de combinaciones hasta que **Agent Merge** incorpore la solicitud. Por último, colaborarás en un lienzo compartido y automatizarás el trabajo recurrente: un ciclo completo desde la idea hasta una funcionalidad combinada. Una ampliación opcional de tres módulos utiliza Microsoft Foundry Canvas para preparar un proyecto y un modelo, crear e implementar un agente y conectarlo al sitio. ## Lecciones @@ -22,8 +22,8 @@ A lo largo de estas lecciones instalarás la aplicación y configurarás el proy | [5. Realizar pruebas con MCP de Playwright][ex5] | Herramientas externas | Añade el servidor MCP de Playwright y explora la funcionalidad en un navegador | | [6. Combinar cambios con Agent Merge][ex6] | Combinación | Deja que Agent Merge corrija e incorpore la solicitud de filtrado | | [7. Planificar con lienzos][ex7] | Colaboración | Crea un lienzo compartido para planificar y realizar el seguimiento del trabajo | -| [8. Crear un agente Backer Concierge (opcional)][foundry-canvas] | Agentes de IA | Crea, prueba, implementa e integra un agente hospedado basado en el catálogo | | [9. Repaso y pasos siguientes][ex9] | Resumen | Automatiza tareas recurrentes y descubre cómo continuar | +| [Opcional: Incorporar Foundry][foundry-canvas] | Agentes de IA | Prepara un proyecto y un modelo, crea e implementa un agente basado en el catálogo y conéctalo al sitio | ## Requisitos previos diff --git a/docs/ja-jp/app/7-canvases.md b/docs/ja-jp/app/7-canvases.md index b88ee1ca..301cbc03 100644 --- a/docs/ja-jp/app/7-canvases.md +++ b/docs/ja-jp/app/7-canvases.md @@ -4,6 +4,9 @@ description: "GitHub Copilot app でエージェント主導の共有キャン authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/ja-jp/app/9-review/ + label: "振り返りと次のステップ" --- ここまでは、チャットを通じてエージェントを指示してきました。しかし、多くの作業は会話の中ではなく、ボード、ドキュメント、チェックリスト上で行われます。**キャンバス**は、まさにそのような作業のために、アプリ内でユーザーとエージェントが共有できる領域です。このレッスンでは、ここまで取り組んできたバックログの計画と追跡に使用する、シンプルなキャンバスを作成します。 @@ -113,7 +116,7 @@ Copilot app が PR の作成と管理を開始します。最初にプロジェ - Agent Merge を使ってキャンバスをリポジトリに保存し、マージした。 - 新しいセッションでキャンバスを開き、そこから作業を開始した。 -バックログを追跡できるようになったので、ここで終了することも、さらに学習を続けることもできます。Tailspin Toys のカタログからホステッド AI エージェントを作成する場合は、[Backer Concierge のオプション レッスン][next-lesson]に進みます。それ以外の場合は、[レッスン 9「振り返りと次のステップ」][review-lesson]に進みます。 +バックログを追跡できるようになったので、[ここまでの成果を振り返るレッスン][next-lesson]に進みます。Microsoft Foundry Canvas を使った追加の学習に取り組む場合は、[オプション: Foundry を組み込む][foundry-canvas]を確認してください。 ## リソース @@ -121,8 +124,8 @@ Copilot app が PR の作成と管理を開始します。最初にプロジェ - [Awesome Copilot の Canvases][awesome-copilot-canvases] - [GitHub Copilot app について][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/ja-jp/app/8-foundry-canvas/1-project-and-model.md b/docs/ja-jp/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..5400d446 --- /dev/null +++ b/docs/ja-jp/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "プロジェクトとモデルを準備する" +description: "Tailspin のカタログをエクスポートし、Foundry プロジェクトとモデルデプロイを作成して、Canvas で検証します。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/ + label: "オプション: Foundry を組み込む" +next: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/2-build-and-deploy/ + label: エージェントを構築してデプロイする +--- + +最初のモジュールでは、Backer Concierge に必要なデータと Azure リソースを準備します。この段階では、エージェントのコードやホステッド エージェントのデプロイは必要ありません。 + +このモジュールを終えると、次のものが揃います。 + +- グラウンディングの制約を明示したカタログのエクスポート。 +- 機能要件に合わせて選んだ Foundry プロジェクトとモデルデプロイ。 +- Canvas で検証済みのデプロイと、カタログの範囲に限定したモデルの簡単なスモークチェックの結果。 + +## シナリオ + +Tailspin Toys の支援者は、カテゴリやパブリッシャーでゲームを絞り込めます。しかし、*Git の言葉遊びが好きな人には、どのゲームが合いますか?* といった質問には、ドロップダウンでは答えられません。Backer Concierge は Tailspin のカタログにあるゲームだけを勧め、ゲーム、パブリッシャー、評価、資金調達総額、支援者数、価格、プレイヤー数、プレイ時間、発売日を捏造してはいけません。信頼できるカタログと適切なモデルが、こうした回答の基盤になります。 + +## ツールと Issue セッションを準備する + +このセットアップでは、GitHub Copilot app を Azure に接続し、機能に関するすべての作業をまとめて進められるようにします。 + +1. Azure サブスクリプションがあることを確認します。必要な場合は、[200 ドルのクレジット付き無料 Azure サブスクリプション][azure-free]または[100 ドルのクレジット付き Azure for Students][azure-students]を利用できます。 +2. 使用する OS に対応した [Azure CLI][install-azure-cli] をインストールし、`az version` でインストールを確認します。 +3. [Azure Developer CLI][install-azd] をインストールし、`azd version` でバージョン 1.27.1 以降がインストールされていることを確認します。 +4. GitHub Copilot app を開き、**Customize** を開いてから **Plugins** を選択します。`microsoft-foundry` を検索し、Canvas と Foundry スキルを含む Microsoft Foundry プラグインの **Install** を選択します。 + + ![Microsoft Foundry プラグインのインストール](../../../_images/app-8-install-foundry-plugin.png) + +5. **Customize** で **Plugins** を選択し、`azure` を検索するか、**Featured** 一覧から選択します。次に、Azure プラグインの **Install** を選択します。 +6. **My work** タブで、Tailspin Toys リポジトリの **Add a Backer Concierge assistant for catalog questions** というタイトルの Issue を探して開きます。**New session** を選択し、新しい worktree で Issue にリンクされたセッションを開始します。3 つのモジュールすべてで、このリポジトリ、worktree ブランチ、Issue セッションを使い続けてください。 +7. `/microsoft-foundry`、続いて `/azure` と入力し、両方のスキルがインストールされ、利用可能であることを確認します。まだプロンプトは送信しないでください。プラグインがすぐに表示されない場合は、アプリを再起動し、同じ Issue セッションに戻って再確認します。 + +## カタログをエクスポートする + +サンプルリポジトリには、エージェントが読み込めるファイルを生成するエクスポートスクリプトが含まれています。 + +8. この Issue にリンクされた worktree セッションで、プロンプトボックスの既定の `/fix-issue` プロンプトを次に置き換えます。 + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. コマンド出力を確認します。Copilot は次に相当するコマンドを実行するはずです。 + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![カタログのエクスポートの生成](../../../_images/app-8-generate-catalog-export.png) + +10. `db/catalog.json` を開き、タイトル、説明、カテゴリ、パブリッシャー、星評価を持つ 21 個のゲームが含まれていることを確認します。`note` フィールドも確認してください。カタログには資金調達総額、支援者数、支援プラン、発売日は含まれていません。価格、プレイヤー数、プレイ時間も、記載がなければ外部知識で補わず、情報がないものとして扱います。エクスポートが失敗した場合や内容が異なる場合は、先に進む前に Copilot に調査と再実行を依頼します。 + + ![Copilot app で開いたカタログのエクスポート](../../../_images/app-8-view-catalog.png) + +## Foundry プロジェクトとモデルを設定する + +先にチャットでプロジェクトとデプロイを作成しておくことで、Canvas は既存のリソースだけに接続します。 + +11. **+**、**Terminal** の順に選択し、Azure にサインインします。 + + ```bash + az login + ``` + +12. 選択したサブスクリプションを確認し、そのリソースグループを一覧表示します。 + + ```bash + az account show --output table + az group list --output table + ``` + + サブスクリプションが正しくない場合は、`az account set --subscription ` を実行してから、両方のコマンドを再実行します。 + + `rg-tailspin-toys` が表示された場合は、そのリソースを確認します。 + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 無関係のリソースや共有リソースが含まれている場合は、いったん中断し、専用の名前を決めてから次のプロンプトを使用してください。以降のすべてのプロンプトとコマンドにある例の名前を、承認した名前に置き換えます。 +13. 同じ Issue セッションで、次を入力します。 + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![Foundry プロジェクトの作成](../../../_images/app-8-foundry-project-created.png) + +14. Copilot にモデルの推奨を依頼します。Issue からセッションを開始したため、Issue の受け入れ条件はすでにコンテキストに含まれています。 + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. Copilot が `microsoft-foundry` スキルを読み込んだことを確認し、トレードオフを踏まえて利用可能なモデルを選びます。Microsoft Foundry のホステッド エージェントのクイックスタートでは、現在 `gpt-5.4-mini` を使用していますが、利用可否とクォータはリージョンによって異なります。 + + ![モデルの選択](../../../_images/app-8-select-model.png) + +16. 選んだモデルのデプロイを Copilot に依頼し、承認前に対象プロジェクトとコストを確認します。 + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> モデルの利用可否は変わります。このモジュールに固定で記載されたモデルではなく、Copilot がプロジェクトで利用可能と確認したモデルを選ぶのが適切です。 + +## Canvas でモデルを検証してスモークテストする + +この確認では、エージェントのコードを作成する前にプロジェクトとモデルを検証します。モデルのスモークチェックは、モジュール 2 で実施するホステッド エージェントのグラウンディングテストの代わりにはなりません。 + +17. **+**、**Canvas**、**Microsoft Foundry (Preview)** の順に選択します。 +18. Canvas の右上隅にある **More options** メニューを開き、**Sign in** を選択します。 +19. **tailspin-toys** Foundry プロジェクトを選択します。**Models** を展開し、デプロイが想定どおりの名前とステータスで表示されることを確認します。 + + ![Canvas でのプロジェクトとモデルの検証](../../../_images/app-8-validate-project-model.png) + +20. 同じセッションで、次のプロンプトを入力します。 + + ```plaintext + Microsoft Foundry スキルを使用して、エージェントを作成せずに、tailspin-toys プロジェクトにデプロイしたモデルを直接テストしてください。@db/catalog.json の内容に基づいて、「バグを追跡するパズルゲームが大好きです。どのゲームを支援すべきですか。また、どれくらいの資金を調達していますか」と質問してください。応答と、取得できる場合に限り、使用したトークン数や応答時間などの有用なメタデータを表示してください。既存の Azure サインインを使用してください。資格情報を表示したり、ファイルを変更したり、リソースを作成したりしないでください。 + ``` + +21. 応答を確認します。`db/catalog.json` に実在するゲームだけを推奨し、正しいタイトル、パブリッシャー、評価を使用し、資金調達の情報がないことを説明する必要があります。モデルがゲーム、カタログの詳細、資金調達額を捏造した場合は、続行する前に別の推奨モデルと比較します。 + +> [!NOTE] +> Canvas は再度開いたときも、選択したプロジェクトを記憶しています。各ステージには、ひな形を作成する **Create new hosted agents**、モデル、ツールボックス、スキル、ガードレールを接続する **Build current hosted agent**、ローカル実行と Microsoft Foundry へのデプロイを行う **Deploy and test** があります。 + +## チェックポイントと次のステップ + +Azure ツールを準備し、カタログをエクスポートして、デプロイしたモデルを Backer Concierge のグラウンディングルールに照らしてテストしました。このモジュールのチェックポイントは、不足している情報を捏造せず、カタログに実在するゲームを推奨するモデルです。 + +次は、同じ Tailspin Toys リポジトリ、worktree ブランチ、Issue にリンクされたセッション、Foundry プロジェクト、選択したモデルデプロイを使用して、[エージェントを構築してデプロイします][next-module]。ここで中断する場合は、継続的なコストを避けるために[Azure リソースをクリーンアップしてください][cleanup]。 + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#リソースをクリーンアップする diff --git a/docs/ja-jp/app/8-foundry-canvas/2-build-and-deploy.md b/docs/ja-jp/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..abf2e34f --- /dev/null +++ b/docs/ja-jp/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,160 @@ +--- +title: "エージェントを構築してデプロイする" +description: "Canvas で Backer Concierge のひな形を作成し、ローカルで検証してから、Foundry にデプロイして再テストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/1-project-and-model/ + label: プロジェクトとモデルを準備する +next: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/3-connect-to-site/ + label: エージェントをサイトに接続する +--- + +このモジュールでは、[プロジェクトとモデルを準備する][previous-module]で用意したプロジェクト、モデルデプロイ、カタログを使い、Microsoft Foundry Canvas でホステッド エージェントの Backer Concierge を構築します。 + +このモジュールを終えると、次のものが揃います。 + +- カタログデータをパッケージに含み、対象を絞ったテストを備えたエージェントのひな形。 +- カタログと会話に関する各受け入れ条件を満たす、ローカルでの検証の証拠。 +- Foundry にデプロイして再テストしたエージェントのバージョン。 + +## シナリオ + +Tailspin Toys には、実際のカタログに関する質問に答え、情報が不足していればそれを認め、会話で取り上げたゲームを覚えているコンシェルジュが必要です。サイトに組み込む前に、サービスが信頼できることを確かめる必要があります。 + +## デプロイ用ツールを準備する + +ホステッド エージェントの検証とデプロイでは、Canvas を通じて Azure Developer CLI を使用します。既存の Foundry プロジェクトとモデルを再利用します。 + +1. モジュール 1 の **Add a Backer Concierge assistant for catalog questions** Issue にリンクされた同じセッションを再開します。`db/catalog.json` が維持され、正しいサブスクリプションと Foundry プロジェクトに接続し、モデルデプロイが残っていることを確認します。リソースをクリーンアップした場合は、まず該当する[プロジェクトとモデルのセットアップ][previous-module]を繰り返してください。 + +2. **+**、**Terminal** の順に選択し、Azure Developer CLI にサインインします。求められたら、ブラウザーで認証を完了します。 + + ```bash + azd auth login + ``` + +3. `azd config show` を実行し、Azure サブスクリプションを確認します。空の場合や誤っている場合は、`azd config set defaults.subscription ` で更新し、`azd config show` を再実行して変更を確認します。 +## Backer Concierge のひな形を作成する + +Canvas は、Backer Concierge を既存のモデルデプロイに接続するためのコード、フォルダー構造、ルートの `azure.yaml` のひな形を作成します。 + +4. **Create new hosted agents** プレビューで、次を入力します。 + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + Canvas は、プロンプトと現在のサブスクリプションおよび Foundry プロジェクトのコンテキストを Copilot に送信します。Agent Framework + Responses API のサンプルを探すため、**Agent with Local Tools (Responses, Agent Framework, Python)** などの選択肢が表示される場合があります。 + + ![Canvas での Backer Concierge エージェントのひな形作成](../../../_images/app-8-scaffold-backer-concierge.png) + +5. **Files** タブで Copilot の変更を確認し、次のチェックポイントと照合します。`src` 内に生成されるファイル名は異なる場合がありますが、プロジェクトの構成範囲と `azure.yaml` の場所は一致するはずです。 + + - エージェントが `agent/backer-concierge` にあります。 + - リポジトリのルートに `azure.yaml` が 1 つあり、`host: azure.ai.agent` を指定したサービスが含まれています。 + - デプロイ可能なエージェントに、生成された専用のカタログのコピーが含まれています。 + - 対象を絞ったテストで、カタログのグラウンディング要件を検証します。 + - 資格情報やローカル環境ファイルは含まれていません。 + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. Copilot に対象を絞ったテストの実行と、失敗した箇所の修正を依頼してから、**Deploy and test** に進みます。 + +## エージェントをローカルで検証する + +**Inspect Locally** は、Copilot の統合ターミナルで `azd ai agent run` を実行し、ホステッド エージェントの起動を待って、埋め込みの Agent Inspector を開きます。 + +7. **Deploy and test** で **Inspect Locally** を選択し、Agent Inspector が開くまで待ちます。 + +> [!NOTE] +> 初回のローカル実行では、`azd` が環境を作成して依存関係をインストールするため、数分かかる場合があります。 + +8. Inspector が接続できない場合は、必要なポートをほかのプロセスが使用していないことを確認し、エラーを Copilot に送ります。問題を修正したら再試行します。 +9. Agent Inspector で、**カタログに基づく推奨**をテストします。 + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + 期待される結果: カタログに実在するタイトルだけを挙げ、それぞれの正しい情報を使用します。 + + ![Agent Inspector でのカタログに基づく推奨](../../../_images/app-8-grounded-recommendation.png) + +10. **ハルシネーションを誘う質問**をテストします。 + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + 期待される結果: カタログには資金調達額や支援者数が記録されていないと説明し、代わりに記載されている情報を提供します。 + +11. **カタログ外の情報を求める質問**をテストします。 + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + 期待される結果: Wingspan はカタログにないと伝え、外部知識からその説明をせず、実在する Tailspin のタイトルの案内に切り替えます。 + +12. **曖昧な依頼**をテストします。 + + ```text + Recommend me something good. + ``` + + 期待される結果: 確認のための短い質問を 1 つ返し、まだタイトルを勧めません。 + +13. **ランキングの正確性**をテストします。 + + ```text + What are your three highest rated games? + ``` + + 期待される結果: カタログで評価が最も高い 3 つのエントリを、正しい順序と評価で返します。 + +14. 同じ会話で次のプロンプトを送信し、**会話の継続性**をテストします。 + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + 期待される結果: 2 回目の応答では、最初の応答にあった 2 つのタイトルだけを参照し、カタログの評価を正しく比較します。 + +15. すべての応答を `db/catalog.json` と Issue の受け入れ条件に照らして確認します。エージェントがゲーム、パブリッシャー、評価、資金調達総額、支援者数、価格、プレイヤー数、プレイ時間、発売日を一切捏造しないことを確認してください。Agent Inspector がエラーを報告した場合や、応答がグラウンディングの範囲を超えた場合は、結果を Canvas のプロンプト領域にコピーし、Copilot に修正を依頼します。変更するたびにローカル検証を再起動して失敗したテストを再実行し、デプロイ前に 6 つのチェックすべてに合格することを確認します。 + +## ホステッド エージェントをデプロイして再テストする + +Canvas は `azd` を使ってテスト済みのエージェントをデプロイします。Foundry はサービスのソースをパッケージ化し、依存関係を解決してリモートでビルドし、Microsoft Foundry に公開します。 + +16. Canvas の **Deploy and test** で **Deploy to Foundry** を選択します。チャットに挿入されるプロンプトを確認します。 + + ![Canvas の Deploy to Foundry プロンプト](../../../_images/app-8-deploy-to-foundry.png) + +17. デプロイの完了通知、エージェントのバージョン、ステータス、Foundry のエージェントプレイグラウンドへのリンクを確認します。デプロイが失敗した場合は、エラーを Copilot に送り、同じプロジェクトで解決してから Canvas で再試行します。 +18. Canvas で **Test in Foundry Portal** を選択し、デプロイしたエージェントのプレイグラウンドを開きます。このデプロイ済みバージョンに対して、手順 9～14 の 6 つの受け入れチェックをすべて再実行します。継続性を確認する 2 つのプロンプトは、同じ会話で送信してください。応答をカタログと照合し、いずれかのチェックに失敗した場合は、Copilot に修正を依頼してローカルテストを再実行し、Canvas で再デプロイして、ホストされたバージョンを再テストします。 + +## チェックポイントと次のステップ + +Backer Concierge のひな形を作成し、カタログのグラウンディングと会話の動作をローカルでテストして、Microsoft Foundry にデプロイし、ホステッド バージョンを再テストしました。このモジュールのチェックポイントは、不足している情報を捏造せず、6 つの受け入れチェックすべてに合格するホステッド エージェントです。 + +次は、同じ Tailspin Toys リポジトリ、worktree ブランチ、Issue にリンクされたセッション、Foundry プロジェクト、選択したモデルデプロイ、ホステッド エージェントを使用して、[エージェントをサイトに接続します][next-module]。ここで中断する場合は、継続的なコストを避けるために[Azure リソースをクリーンアップしてください][cleanup]。 + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#リソースをクリーンアップする diff --git a/docs/ja-jp/app/8-foundry-canvas/3-connect-to-site.md b/docs/ja-jp/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..69bf712e --- /dev/null +++ b/docs/ja-jp/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "エージェントをサイトに接続する" +description: "資格情報を保護するローカルプロキシを介してホステッド エージェントの Backer Concierge を統合し、ウィジェットをエンドツーエンドでテストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/2-build-and-deploy/ + label: エージェントを構築してデプロイする +next: + link: /copilot-workshops/ja-jp/app/9-review/ + label: 振り返りと次のステップ +--- + +最後のモジュールでは、[エージェントを構築してデプロイする][previous-module]でテストしたホステッド エージェントを、ローカルで実行する Tailspin Toys Web サイトに接続します。 + +このモジュールを終えると、次のものが揃います。 + +- Foundry の資格情報と会話識別子を保護するローカルの Azure Functions プロキシ。 +- エンドツーエンドの動作を検証済みの、アクセシビリティに配慮したチャットウィジェット。 +- ローカルで検証済みの統合と、リソースのクリーンアップのチェックポイント。 + +## シナリオ + +Tailspin Toys の支援者は、ゲームを閲覧する場所でカタログについてのアドバイスを必要としています。Backer Concierge は会話を維持し、キーボード操作に対応し、情報がない場合やエラーが発生した場合に明確に対処する必要があります。この利便性のために、サービスの資格情報や内部の会話情報をブラウザーに公開してはいけません。 + +## ホステッド エージェントのチェックポイントから再開する + +統合では新しい Foundry リソースを作成せず、既存のホステッド エージェントを使用します。 + +1. 前のモジュールと同じ Tailspin Toys リポジトリ、worktree ブランチ、**Add a Backer Concierge assistant for catalog questions** の Issue セッションを再開します。ルートの `azure.yaml`、エージェントのソース、カタログが揃っていることを確認し、記録したサブスクリプション、専用リソースグループ、Foundry プロジェクト、モデルデプロイ、テスト済みのホステッド エージェントのバージョンを確認します。 +2. リソースをクリーンアップした場合は、統合する前に、該当する[プロジェクトとモデル][project-module]および[テスト済みのホステッド エージェントのデプロイ][previous-module]を復元します。 + +## サーバー側のプロキシを構築する + +Tailspin Toys は全体が事前レンダリングされています。ブラウザーのコードは、ホステッド エージェントを直接呼び出したり、Foundry の資格情報を受け取ったりしてはいけません。ローカルの Azure Functions による**サーバー側の資格情報保護境界**が Foundry に対して認証し、エージェントの応答だけをブラウザーに返します。ブラウザーは各メッセージとともに、不透明な会話ハンドルを送信します。プロキシは内部の識別子を公開せずに、そのハンドルを Foundry の会話に対応付けます。 + +Azure の資格情報にアクセスできるコードは、プロキシだけです。このワークショップでは、Function とサイトをローカルで実行し、Astro 開発サーバーが `/api` リクエストを Function に転送します。 + +> [!IMPORTANT] +> このワークショップのプロキシは、ローカル開発専用です。匿名でアクセスできる公開エンドポイントとしてデプロイしてはいけません。本番環境に統合するには、適切なレート制限やクォータ、CORS 制限、監視、コスト管理など、アプリケーションに合わせた認証と不正利用防止の設計が必要です。 + +3. 同じ Copilot セッションで、次を入力します。 + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. 生成されたプロキシと対象を絞ったテストを確認し、リクエストの検証、エラーからの機密情報の除去、不透明な会話ハンドル、サーバー側だけに資格情報を留める境界を点検します。Copilot に対象を絞ったテストの実行と、失敗した箇所の修正を依頼します。 +5. 別のターミナルを開き、Copilot が提示したコマンドでローカルの Function を起動し、そのまま実行しておきます。 +6. チャットに戻り、Copilot にローカルプロキシのテストを依頼します。 + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. 応答を確認します。カタログに価格が含まれていないことを説明するはずです。Foundry のトークン、資格情報、内部の会話識別子、プロジェクトのエンドポイント、スタックトレースが含まれていないことを確認します。Function に接続できない場合や、応答に内部情報の漏洩や価格の捏造がある場合は、機密情報を除去した失敗の内容を Copilot に送り、修正してプロキシのテストを再実行してから先に進みます。 + + ![ローカルプロキシのテスト](../../../_images/app-8-local-proxy-test.png) + +## チャットウィジェットを構築してテストする + +プロキシを実行した状態で、ウィジェットが Foundry の内部情報を公開せずに、サイト上で会話を表示します。 + +8. Copilot にサイトへの統合を依頼します。 + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. Copilot が提示したコマンドを使い、別のターミナルで Astro 開発サーバーを起動します。サイトとローカルの Function の両方を実行したままにします。 +10. Copilot にエンドツーエンドテストの実行を依頼します。 + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. レポートを確認し、キーボード操作や[ホステッド エージェントの受け入れチェック][agent-checks]の 2 ターンの会話など、報告された動作をブラウザーで検証します。ブラウザーのリクエストが Foundry に直接送られず、不透明なハンドルとともに `/api/concierge` を経由し、応答に資格情報や Foundry の内部識別子が公開されていないことを確認します。推奨や情報不足への回答がカタログの範囲内に収まっていることも確認してください。Copilot とともに失敗したテストに対処し、必要に応じて影響のあるローカルサービスを再起動して、テストを再実行します。 + + ![Backer Concierge ウィジェットのエンドツーエンドテスト結果](../../../_images/app-8-e2e-test-results.png) + +## チェックポイントと次のステップ + +資格情報を保護するローカルプロキシを構築し、アクセシビリティに配慮したチャットウィジェットを接続して、ホステッド Backer Concierge との会話フロー全体を検証しました。このモジュールのチェックポイントは、カタログの境界を維持し、資格情報と Foundry の内部識別子をブラウザーに公開しない、ローカルでテスト済みの Web サイト統合です。プロキシやサイトを本番環境にデプロイしたものではありません。 + +実験を終えたら、両方のローカルサービスを停止して、[Azure リソースをクリーンアップしてください][cleanup]。その後、コアワークショップのルートにある[振り返りと次のステップ][core-review]に進みます。 + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#エージェントをローカルで検証する +[cleanup]: ../#リソースをクリーンアップする +[core-review]: ../../9-review/ diff --git a/docs/ja-jp/app/8-foundry-canvas/README.md b/docs/ja-jp/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..184456cd --- /dev/null +++ b/docs/ja-jp/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "オプション: Foundry を組み込む" +slug: ja-jp/app/8-foundry-canvas +description: "Microsoft Foundry Canvas を使ってカタログに基づく Backer Concierge を構築します。各段階で安全に中断できます。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ja-jp/app/9-review/ + label: 振り返りと次のステップ +next: + link: /copilot-workshops/ja-jp/app/8-foundry-canvas/1-project-and-model/ + label: プロジェクトとモデルを準備する +--- + +このオプションの学習では、GitHub Copilot app の Microsoft Foundry Canvas を使い、Tailspin Toys に **Backer Concierge** を追加します。カタログに基づくモデルの実験から始め、ホステッド エージェントの構築、ローカル Web サイトへの統合へと進みます。 + +## 学習の流れ + +各モジュールの最後にはチェックポイントがあり、安全に中断できます。学習全体を通じて、同じ Tailspin Toys リポジトリ、worktree ブランチ、Issue にリンクされたセッション、Foundry プロジェクト、モデルデプロイを使用します。 + +- [プロジェクトとモデルを準備する][module-1]では、カタログで扱える情報の範囲を定め、プロジェクトとモデルデプロイを作成し、Canvas で確認します。 +- [エージェントを構築してデプロイする][module-2]では、Backer Concierge のひな形を作成してローカルでテストし、ホステッド エージェントをデプロイして再テストします。 +- [エージェントをサイトに接続する][module-3]では、資格情報を保護するローカルプロキシ、アクセシビリティに配慮したチャットウィジェット、エンドツーエンドテストを追加します。 + +> [!IMPORTANT] +> Microsoft Foundry Canvas とホステッド エージェントはパブリックプレビュー段階です。 +> +> この学習では、モデルデプロイや、モジュール 2 以降のホステッド エージェントなど、課金対象の Azure リソースを作成します。リソースを作成する前に、サブスクリプション、リージョン、クォータ、推定コストの承認が必要です。プロジェクトとモデルの作成だけで中断する場合も、クリーンアップが必要です。 + +1. [プロジェクトとモデルを準備する][module-1]から始めます。作業は、このワークショップのコンテンツリポジトリではなく、Tailspin Toys リポジトリで進めてください。 +2. コアワークショップを完了する場合は、[レビューと次のステップ][core-review]に進んでください。 + +## リソースをクリーンアップする + +どのチェックポイントで実験を終える場合も、不要なコストを避けるために Azure リソースを削除します。クリーンアップすると後続のモジュールに必要なリソースも削除されるため、後で続行するには再作成が必要です。 + +> [!WARNING] +> `rg-tailspin-toys` がこの演習専用で、保持する必要があるリソースを含んでいない場合にのみ削除してください。共有リソースグループを削除すると、関係のないリソースも削除されます。 +> +> モジュール 1 で別のリソースグループ名を承認した場合は、以下のすべてのコマンドで `rg-tailspin-toys` をその名前に置き換えてください。 + +1. 起動したローカルの Agent Inspector、Azure Function、Astro 開発サーバーを、それぞれのターミナルで停止します。 +2. モジュール 2 または 3 でホステッド エージェントをデプロイした場合は、同じ Tailspin Toys worktree でターミナルを開き、同じ `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 + ``` + +## リソース + +Microsoft のドキュメントで、Canvas、ホステッド エージェントのデプロイ、およびそれらのアクセス許可について説明されています。 + +- [Microsoft Foundry Canvas とは][foundry-canvas] +- [Foundry Canvas で最初のホステッド エージェントをデプロイする][hosted-agent-quickstart] +- [ホステッド エージェントのアクセス許可][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/ja-jp/app/9-review.md b/docs/ja-jp/app/9-review.md index a3ad30c9..9bf2cf4e 100644 --- a/docs/ja-jp/app/9-review.md +++ b/docs/ja-jp/app/9-review.md @@ -4,6 +4,7 @@ description: "GitHub Copilot app のハーネスを振り返り、繰り返し authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- ここ数回のレッスンでは、GitHub Copilot app を使い、アイデアから機能のマージまでを実践しました。取り組んだ内容は次のとおりです。 @@ -62,6 +63,8 @@ AI ツールを使用するときは、その周辺の基盤が出力の品質 GitHub Copilot エコシステムをさらに学ぶには、[VS Code ハーネス](../../vscode/)、[Copilot CLI ハーネス](../../cli/)、[Cloud agent ハーネス](../../cloud/)を確認してください。 +Microsoft Foundry Canvas を使った追加の学習に取り組む場合は、[オプション: Foundry を組み込む][foundry-canvas]を確認してください。 + ## リソース - [GitHub Copilot app について][about-copilot-app] @@ -80,4 +83,5 @@ GitHub Copilot エコシステムをさらに学ぶには、[VS Code ハーネ [chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models -[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ \ No newline at end of file diff --git a/docs/ja-jp/app/README.md b/docs/ja-jp/app/README.md index a078cbb7..2608dc21 100644 --- a/docs/ja-jp/app/README.md +++ b/docs/ja-jp/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 [**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) は Copilot CLI を基盤とするデスクトップアプリケーションで、エージェント主導の開発を単一の作業用ワークスペースで実現します。並列エージェントセッション、切り替え可能なセッションモード、共有キャンバス、GitHub Issue と pull request のネイティブ管理機能を備えています。さらに、リベース、レビューのフィードバック、CI の修正、マージまで pull request を導く **Agent Merge** も利用できます。 -一連のレッスンでは、アプリをインストールしてプロジェクトを設定した後、アプリのワークスペースと、テンプレートによって用意されたバックログを確認します。まず、星評価を追加する小さな変更に取り組みます。次に、Issue に基づいてカスタム指示の標準を追加し、分離されたエージェントセッションでフィルター機能を構築して、再利用可能なスキルで検証します。Playwright MCP server を追加して実際のブラウザーで機能を確認した後、段階的にマージの自動化を進め、最後は **Agent Merge** で pull request をマージします。最後に、共有キャンバスで共同作業し、必要に応じて Microsoft Foundry Canvas でホステッド エージェントを構築して、繰り返し発生する作業を自動化します。アイデアから機能のマージまで、開発の一連の流れを体験できます。 +一連のレッスンでは、アプリをインストールしてプロジェクトを設定した後、アプリのワークスペースと、テンプレートによって用意されたバックログを確認します。まず、星評価を追加する小さな変更に取り組みます。次に、Issue に基づいてカスタム指示の標準を追加し、分離されたエージェントセッションでフィルター機能を構築して、再利用可能なスキルで検証します。Playwright MCP server を追加して実際のブラウザーで機能を確認した後、段階的にマージの自動化を進め、最後は **Agent Merge** で pull request をマージします。最後に、共有キャンバスで共同作業し、繰り返し発生する作業を自動化します。アイデアから機能のマージまで、開発の一連の流れを体験できます。追加のオプションとして、3 つのモジュールで Microsoft Foundry Canvas を使い、プロジェクトとモデルの準備、エージェントの構築とデプロイ、サイトへの接続に取り組めます。 ## レッスン @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. Playwright MCP によるテスト][ex5] | 外部ツール | Playwright MCP server を追加し、ブラウザーで機能を確認します | | [6. Agent Merge によるマージ][ex6] | マージ | Agent Merge でフィルター機能の pull request を修正してマージします | | [7. キャンバスを使った計画][ex7] | コラボレーション | 共有キャンバスを作成し、作業の計画と追跡に使用します | -| [8. Backer Concierge エージェントの構築 (オプション)][foundry-canvas] | AI エージェント | カタログに基づくホステッド エージェントを構築、テスト、デプロイ、統合します | | [9. 振り返りと次のステップ][ex9] | まとめ | 繰り返し発生するタスクを自動化し、次に学ぶ内容を確認します | +| [オプション: Foundry を組み込む][foundry-canvas] | AI エージェント | プロジェクトとモデルを準備し、データに基づくエージェントを構築してデプロイし、サイトに接続します | ## 前提条件 diff --git a/docs/ko-kr/app/7-canvases.md b/docs/ko-kr/app/7-canvases.md index 6abe7be9..599052db 100644 --- a/docs/ko-kr/app/7-canvases.md +++ b/docs/ko-kr/app/7-canvases.md @@ -4,6 +4,9 @@ description: "GitHub Copilot app에서 공유 에이전트 기반 캔버스를 authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/ko-kr/app/9-review/ + label: "검토 및 다음 단계" --- 지금까지 채팅을 통해 에이전트를 지시했습니다. 하지만 많은 작업은 대화가 아니라 보드, 문서, 검사 목록에서 이루어집니다. **캔버스**는 바로 이러한 작업을 위해 앱 안에서 사용자와 에이전트가 함께 사용하는 화면을 제공합니다. 이 레슨에서는 지금까지 처리한 백로그를 계획하고 추적하는 간단한 캔버스를 만듭니다. @@ -113,7 +116,7 @@ Copilot app이 PR을 만들고 관리하는 프로세스를 시작합니다. 먼 - Agent Merge를 사용하여 캔버스를 리포지토리에 저장하고 병합했습니다. - 새 세션에서 캔버스를 열고 캔버스를 사용하여 작업을 시작했습니다. -백로그 추적을 설정했으므로 여기서 마치거나 계속 진행할 수 있습니다. Tailspin Toys 카탈로그를 기반으로 호스팅 AI 에이전트를 만들려면 [Backer Concierge 선택 레슨][next-lesson]으로 이동합니다. 그렇지 않으면 [레슨 9 - 검토 및 다음 단계][review-lesson]로 이동합니다. +백로그 추적을 설정했으므로 [지금까지 만든 내용을 검토하는 단계][next-lesson]로 계속 진행합니다. Microsoft Foundry Canvas를 사용하는 선택 확장 과정을 살펴보려면 [선택 사항: Foundry 통합][foundry-canvas]으로 이동합니다. ## 리소스 @@ -121,8 +124,8 @@ Copilot app이 PR을 만들고 관리하는 프로세스를 시작합니다. 먼 - [Awesome Copilot의 캔버스][awesome-copilot-canvases] - [GitHub Copilot app 정보][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/ko-kr/app/8-foundry-canvas/1-project-and-model.md b/docs/ko-kr/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..7ef87d0c --- /dev/null +++ b/docs/ko-kr/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "프로젝트와 모델 준비" +description: "Tailspin 카탈로그를 내보내고, Foundry 프로젝트와 모델 배포를 만든 다음 Canvas에서 검증합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/ + label: "선택 사항: Foundry 통합" +next: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/2-build-and-deploy/ + label: 에이전트 빌드 및 배포 +--- + +첫 번째 모듈에서는 Backer Concierge에 필요한 데이터와 Azure 리소스를 준비합니다. 아직 에이전트 코드나 호스팅 배포는 필요하지 않습니다. + +이 모듈을 마치면 다음을 갖추게 됩니다. + +- 그라운딩(Grounding)에 사용할 수 있는 정보의 한계를 명시한 카탈로그 내보내기 파일 +- 기능 요구 사항에 맞게 선택한 Foundry 프로젝트와 모델 배포 +- Canvas에서 검증한 배포와 카탈로그 범위 내에서 수행한 간단한 모델 스모크 테스트(Smoke test) 결과 + +## 시나리오 + +Tailspin Toys 후원자는 카테고리와 퍼블리셔로 게임을 필터링할 수 있지만, *Git 말장난을 좋아하는 사람에게는 어떤 게임이 어울립니까?* 같은 질문에는 드롭다운만으로 답할 수 없습니다. Backer Concierge는 Tailspin 카탈로그에 있는 게임만 추천해야 하며 게임, 퍼블리셔, 평점, 펀딩 총액, 후원자 수, 가격, 플레이어 수, 플레이 시간, 출시일을 지어내서는 안 됩니다. 신뢰할 수 있는 카탈로그와 적합한 모델이 이러한 답변의 기반이 됩니다. + +## 도구와 이슈 세션 준비 + +모든 기능 작업을 한곳에서 진행할 수 있도록 GitHub Copilot app을 Azure에 연결합니다. + +1. Azure 구독이 있는지 확인합니다. 구독이 필요하다면 [$200 크레딧이 제공되는 무료 Azure 구독][azure-free] 또는 [$100 크레딧이 제공되는 Azure for Students][azure-students]를 사용할 수 있습니다. +2. 운영 체제에 맞는 [Azure CLI][install-azure-cli]를 설치한 다음 `az version`으로 설치를 확인합니다. +3. [Azure Developer CLI][install-azd]를 설치한 다음 `azd version`으로 1.27.1 이상 버전이 설치되었는지 확인합니다. +4. GitHub Copilot app에서 **Customize**를 연 다음 **Plugins**를 선택합니다. `microsoft-foundry`를 검색하고 Canvas와 Foundry 스킬이 포함된 Microsoft Foundry 플러그인의 **Install**을 선택합니다. + + ![Microsoft Foundry 플러그인 설치](../../../_images/app-8-install-foundry-plugin.png) + +5. **Customize**에서 **Plugins**를 선택하고 `azure`를 검색하거나 **Featured** 목록에서 선택한 다음, Azure 플러그인의 **Install**을 선택합니다. +6. **My work** 탭에서 Tailspin Toys 리포지토리의 **Add a Backer Concierge assistant for catalog questions** 이슈를 찾아 엽니다. **New session**을 선택하여 새 워크트리(Worktree)에서 이슈에 연결된 세션을 시작합니다. 세 모듈 모두에서 이 리포지토리, 워크트리 브랜치, 이슈 세션을 유지합니다. +7. `/microsoft-foundry`를 입력한 다음 `/azure`를 입력하여 두 스킬이 모두 설치되어 사용할 수 있는지 확인합니다. 아직 프롬프트를 보내지는 않습니다. 플러그인이 바로 나타나지 않으면 앱을 다시 시작하고 동일한 이슈 세션으로 돌아와 다시 확인합니다. + +## 카탈로그 내보내기 파일 생성 + +샘플 리포지토리에는 에이전트가 읽을 수 있는 파일을 생성하는 내보내기 스크립트가 포함되어 있습니다. + +8. 이슈에 연결된 이 워크트리 세션의 프롬프트 상자에서 기본 `/fix-issue` 프롬프트를 다음으로 바꿉니다. + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. 명령 출력을 검토합니다. Copilot은 다음과 같은 명령을 실행해야 합니다. + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![카탈로그 내보내기 파일 생성](../../../_images/app-8-generate-catalog-export.png) + +10. `db/catalog.json`을 열고 제목, 설명, 카테고리, 퍼블리셔, 별점을 포함한 게임 21개가 있는지 확인합니다. `note` 필드를 확인합니다. 카탈로그에는 펀딩 총액, 후원자 수, 후원 등급, 출시일이 없습니다. 가격, 플레이어 수, 플레이 시간도 누락되어 있다면 외부 지식으로 채우지 말고 제공되지 않는 정보로 취급합니다. 내보내기가 실패하거나 내용이 다르면 계속하기 전에 Copilot에 원인을 조사하고 다시 실행하도록 요청합니다. + + ![Copilot app에서 연 카탈로그 내보내기 파일](../../../_images/app-8-view-catalog.png) + +## Foundry 프로젝트와 모델 설정 + +먼저 채팅에서 프로젝트와 배포를 만들면 Canvas는 이미 존재하는 리소스에만 연결합니다. + +11. **+**를 선택하고 **Terminal**을 선택한 다음 Azure에 로그인합니다. + + ```bash + az login + ``` + +12. 선택한 구독을 확인하고 해당 리소스 그룹을 나열합니다. + + ```bash + az account show --output table + az group list --output table + ``` + + 구독이 올바르지 않다면 `az account set --subscription `를 실행한 다음 두 명령을 다시 실행합니다. + + `rg-tailspin-toys`가 표시되면 해당 리소스를 검사합니다. + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 관련 없는 리소스나 공유 리소스가 포함되어 있다면 중단하고 전용 이름을 정한 후에 다음 프롬프트를 사용합니다. 이후 모든 프롬프트와 명령의 예시 이름을 승인한 이름으로 바꿉니다. +13. 동일한 이슈 세션에서 다음을 입력합니다. + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![Foundry 프로젝트 생성](../../../_images/app-8-foundry-project-created.png) + +14. Copilot에 모델을 추천하도록 요청합니다. 이슈에서 시작한 세션이므로 이슈의 승인 기준이 이미 컨텍스트에 포함되어 있습니다. + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. Copilot이 `microsoft-foundry` 스킬을 로드하는지 확인한 다음, 장단점을 고려하여 사용 가능한 모델을 선택합니다. Microsoft Foundry 호스팅 에이전트 빠른 시작에서는 현재 `gpt-5.4-mini`를 사용하지만, 가용성과 할당량은 지역에 따라 다릅니다. + + ![모델 선택](../../../_images/app-8-select-model.png) + +16. Copilot에 선택한 모델을 배포하도록 요청하고, 승인하기 전에 대상 프로젝트와 비용을 검토합니다. + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> 모델 가용성은 시간이 지나면서 달라집니다. 이 모듈에 고정된 모델보다는 Copilot이 프로젝트에서 사용할 수 있다고 확인한 모델을 선택하는 것이 적절합니다. + +## Canvas에서 모델 검증 및 스모크 테스트 + +에이전트 코드를 작성하기 전에 프로젝트와 모델을 확인합니다. 모델 스모크 테스트는 모듈 2의 호스팅 에이전트 그라운딩 테스트를 대체하지 않습니다. + +17. **+**, **Canvas**, **Microsoft Foundry (Preview)**를 차례로 선택합니다. +18. Canvas 오른쪽 위의 **More options** 메뉴를 연 다음 **Sign in**을 선택합니다. +19. **tailspin-toys** Foundry 프로젝트를 선택합니다. **Models**를 펼치고 배포가 예상한 이름과 상태로 표시되는지 확인합니다. + + ![Canvas에서 프로젝트와 모델 검증](../../../_images/app-8-validate-project-model.png) + +20. 동일한 세션에 다음 프롬프트를 입력합니다. + + ```plaintext + Microsoft Foundry 스킬을 사용하여 에이전트를 만들지 않고 tailspin-toys 프로젝트에 배포한 모델을 직접 테스트합니다. @db/catalog.json의 콘텐츠를 근거로 "버그를 추적하는 퍼즐 게임을 좋아합니다. 어떤 게임을 후원해야 하며, 얼마나 많은 자금을 모았나요?"라고 질문합니다. 응답과 사용한 토큰 수, 응답 시간 등의 유용한 메타데이터를 확인할 수 있는 경우에만 표시합니다. 기존 Azure 로그인을 사용합니다. 자격 증명을 표시하거나 파일을 변경하거나 리소스를 만들지 않습니다. + ``` + +21. 응답을 검토합니다. `db/catalog.json`에 실제로 있는 게임만 추천하고 올바른 제목, 퍼블리셔, 평점을 사용하며 자금 조달 정보가 없다고 설명해야 합니다. 모델이 게임, 카탈로그 세부 정보 또는 자금 조달 금액을 지어내면 계속하기 전에 다른 추천 모델과 비교합니다. + +> [!NOTE] +> Canvas는 다시 열어도 선택한 프로젝트를 기억합니다. Canvas의 단계는 기본 구조를 생성하는 **Create new hosted agents**, 모델, 도구 상자, 스킬, 가드레일(Guardrail)을 연결하는 **Build current hosted agent**, 로컬 실행과 Microsoft Foundry 배포를 수행하는 **Deploy and test**로 구성됩니다. + +## 체크포인트 및 다음 단계 + +Azure 도구를 준비하고 카탈로그를 내보낸 다음 배포된 모델이 Backer Concierge의 그라운딩 규칙을 따르는지 테스트했습니다. 이 모듈의 체크포인트는 누락된 정보를 지어내지 않고 실제 카탈로그 게임을 추천하는 모델입니다. + +다음에는 동일한 Tailspin Toys 리포지토리, 워크트리 브랜치, 이슈에 연결된 세션, Foundry 프로젝트, 선택한 모델 배포를 사용하여 [에이전트를 빌드하고 배포합니다][next-module]. 여기서 중단한다면 지속적인 비용을 방지하도록 [Azure 리소스를 정리합니다][cleanup]. + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#리소스-정리 diff --git a/docs/ko-kr/app/8-foundry-canvas/2-build-and-deploy.md b/docs/ko-kr/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..8c14d4e4 --- /dev/null +++ b/docs/ko-kr/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,160 @@ +--- +title: "에이전트 빌드 및 배포" +description: "Canvas에서 Backer Concierge의 기본 구조를 생성하고 로컬에서 검사한 다음, Foundry에 배포하고 다시 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/1-project-and-model/ + label: 프로젝트와 모델 준비 +next: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/3-connect-to-site/ + label: 에이전트를 사이트에 연결 +--- + +이 모듈에서는 [프로젝트와 모델 준비][previous-module]에서 마련한 프로젝트, 모델 배포, 카탈로그를 사용하여 Microsoft Foundry Canvas로 호스팅 Backer Concierge를 구축합니다. + +이 모듈을 마치면 다음을 갖추게 됩니다. + +- 패키징한 카탈로그 데이터와 집중 테스트를 포함하는 에이전트 기본 구조 +- 카탈로그 및 대화의 각 승인 기준에 대한 로컬 검증 증거 +- 배포 후 Foundry에서 다시 테스트한 에이전트 버전 + +## 시나리오 + +Tailspin Toys에는 실제 카탈로그 질문에 답하고, 정보가 없으면 이를 인정하며, 대화에서 다룬 게임을 기억하는 도우미가 필요합니다. 이 서비스는 상점 사이트의 일부가 되기 전에 신뢰성을 입증해야 합니다. + +## 배포 도구 준비 + +호스팅 에이전트를 검사하고 배포할 때는 Canvas를 통해 Azure Developer CLI를 사용하며, 기존 Foundry 프로젝트와 모델을 재사용합니다. + +1. 모듈 1의 **Add a Backer Concierge assistant for catalog questions** 이슈에 연결된 동일한 세션을 다시 시작합니다. `db/catalog.json`이 그대로 있고 올바른 구독과 Foundry 프로젝트에 연결되어 있으며 모델 배포가 유지되는지 확인합니다. 리소스를 정리했다면 먼저 관련 [프로젝트와 모델 설정][previous-module]을 다시 수행합니다. + +2. **+**를 선택하고 **Terminal**을 선택한 다음 Azure Developer CLI에 로그인합니다. 메시지가 표시되면 브라우저에서 인증을 완료합니다. + + ```bash + azd auth login + ``` + +3. `azd config show`를 실행하여 Azure 구독을 확인합니다. 비어 있거나 올바르지 않으면 `azd config set defaults.subscription `로 업데이트한 후 `azd config show`를 다시 실행하여 변경 내용을 확인합니다. +## Backer Concierge 기본 구조 생성 + +Canvas는 Backer Concierge를 기존 모델 배포에 연결하는 코드, 폴더 구조, 루트 `azure.yaml`을 생성합니다. + +4. **Create new hosted agents** 미리 보기에서 다음을 입력합니다. + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + Canvas는 프롬프트와 현재 구독 및 Foundry 프로젝트 컨텍스트를 Copilot에 전달합니다. Agent Framework + Responses API 샘플을 검색하며, **Agent with Local Tools (Responses, Agent Framework, Python)** 같은 선택 항목이 나타날 수 있습니다. + + ![Canvas에서 Backer Concierge 에이전트 기본 구조 생성](../../../_images/app-8-scaffold-backer-concierge.png) + +5. **Files** 탭에서 다음 체크포인트를 기준으로 Copilot의 변경 내용을 검토합니다. `src` 안에 생성된 파일 이름은 다를 수 있지만 프로젝트 경계와 `azure.yaml` 위치는 일치해야 합니다. + + - 에이전트는 `agent/backer-concierge`에 있습니다. + - 리포지토리 루트의 단일 `azure.yaml`에 `host: azure.ai.agent`를 사용하는 서비스가 포함되어 있습니다. + - 배포 가능한 에이전트에 자체적으로 생성한 카탈로그 복사본이 포함되어 있습니다. + - 집중 테스트가 카탈로그 그라운딩(Grounding) 요구 사항을 검증합니다. + - 자격 증명이나 로컬 환경 파일이 포함되어 있지 않습니다. + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. **Deploy and test**로 진행하기 전에 Copilot에 집중 테스트를 실행하고 실패한 부분을 수정하도록 요청합니다. + +## 로컬에서 에이전트 검사 + +**Inspect Locally**는 Copilot 통합 터미널에서 `azd ai agent run`을 실행하고 호스팅 에이전트가 시작될 때까지 기다린 다음, 내장 Agent Inspector를 엽니다. + +7. **Deploy and test**에서 **Inspect Locally**를 선택하고 Agent Inspector가 열릴 때까지 기다립니다. + +> [!NOTE] +> 처음 로컬에서 실행할 때는 `azd`가 환경을 만들고 종속성을 설치하므로 몇 분 정도 걸릴 수 있습니다. + +8. 검사 도구가 연결되지 않으면 다른 프로세스가 필요한 포트를 사용하고 있지 않은지 확인하고 오류를 Copilot에 전달한 다음, 문제를 수정한 후 다시 시도합니다. +9. Agent Inspector에서 **카탈로그에 근거한 추천**을 테스트합니다. + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + 예상 결과: 카탈로그에 실제로 존재하는 게임만 언급하고 각 게임에 대해 올바른 정보를 사용합니다. + + ![Agent Inspector에서 카탈로그에 근거한 추천](../../../_images/app-8-grounded-recommendation.png) + +10. **환각(Hallucination) 유도 질문**을 테스트합니다. + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + 예상 결과: 카탈로그에는 펀딩이나 후원자 정보가 없음을 설명하고, 대신 카탈로그에 있는 정보를 제공합니다. + +11. **카탈로그 외 게임 요청에 대한 대응**을 테스트합니다. + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + 예상 결과: 카탈로그에 Wingspan이 없다고 밝히고, 외부 지식으로 이 게임을 설명하지 않으며, 실제 Tailspin 게임을 안내합니다. + +12. **모호한 요청**을 테스트합니다. + + ```text + Recommend me something good. + ``` + + 예상 결과: 짧은 확인 질문을 하나 하고 아직 게임을 추천하지 않습니다. + +13. **순위 정확성**을 테스트합니다. + + ```text + What are your three highest rated games? + ``` + + 예상 결과: 카탈로그에서 평점이 가장 높은 게임 세 개를 올바른 순서와 평점으로 반환합니다. + +14. 동일한 대화에서 다음 프롬프트를 보내 **대화 연속성**을 테스트합니다. + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + 예상 결과: 두 번째 응답은 첫 번째 응답의 두 게임만 언급하고 카탈로그 평점을 올바르게 비교합니다. + +15. 모든 응답을 `db/catalog.json` 및 이슈의 승인 기준과 비교합니다. 에이전트가 게임, 퍼블리셔, 평점, 펀딩 총액, 후원자 수, 가격, 플레이어 수, 플레이 시간, 출시일을 절대 지어내지 않는지 확인합니다. Agent Inspector가 오류를 보고하거나 응답이 그라운딩 범위를 벗어나면 결과를 Canvas 프롬프트 영역에 복사하고 Copilot에 수정하도록 요청합니다. 변경할 때마다 로컬 검사를 다시 시작하고 실패한 테스트를 다시 실행한 다음, 배포하기 전에 여섯 가지 검사를 모두 통과하는지 확인합니다. + +## 호스팅 에이전트 배포 및 재테스트 + +Canvas는 `azd`로 테스트를 마친 에이전트를 배포합니다. Foundry는 서비스 소스를 패키징하고 종속성을 해결한 다음 원격으로 빌드하여 Microsoft Foundry에 게시합니다. + +16. Canvas의 **Deploy and test**에서 **Deploy to Foundry**를 선택합니다. 채팅에 삽입된 프롬프트를 검토합니다. + + ![Canvas의 Deploy to Foundry 프롬프트](../../../_images/app-8-deploy-to-foundry.png) + +17. 배포 확인 메시지, 에이전트 버전, 상태, Foundry 에이전트 플레이그라운드(Playground) 링크를 확인합니다. 배포에 실패하면 오류를 Copilot에 전달하고 동일한 프로젝트에서 문제를 해결한 다음 Canvas를 통해 다시 시도합니다. +18. Canvas에서 **Test in Foundry Portal**을 선택하여 배포된 에이전트 플레이그라운드를 엽니다. 이 배포 버전에 대해 9~14단계의 승인 검사 여섯 가지를 모두 다시 실행합니다. 연속성을 확인하는 두 프롬프트는 하나의 대화에서 유지합니다. 응답을 카탈로그와 비교합니다. 실패한 검사가 있으면 Copilot에 수정하도록 요청하고 로컬 테스트를 다시 실행한 다음, Canvas로 다시 배포하고 호스팅 버전을 다시 테스트합니다. + +## 체크포인트 및 다음 단계 + +Backer Concierge의 기본 구조를 생성하고 카탈로그 그라운딩과 대화 동작을 로컬에서 테스트한 다음 Microsoft Foundry에 배포하고 호스팅 버전을 다시 테스트했습니다. 이 모듈의 체크포인트는 누락된 정보를 지어내지 않고 여섯 가지 승인 검사를 모두 통과하는 호스팅 에이전트입니다. + +다음에는 동일한 Tailspin Toys 리포지토리, 워크트리 브랜치, 이슈에 연결된 세션, Foundry 프로젝트, 선택한 모델 배포, 호스팅 에이전트를 사용하여 [에이전트를 사이트에 연결합니다][next-module]. 여기서 중단한다면 지속적인 비용을 방지하도록 [Azure 리소스를 정리합니다][cleanup]. + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#리소스-정리 diff --git a/docs/ko-kr/app/8-foundry-canvas/3-connect-to-site.md b/docs/ko-kr/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..e30472f8 --- /dev/null +++ b/docs/ko-kr/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "에이전트를 사이트에 연결" +description: "자격 증명을 안전하게 보호하는 로컬 프록시로 호스팅 Backer Concierge를 통합하고 위젯을 엔드투엔드로 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/2-build-and-deploy/ + label: 에이전트 빌드 및 배포 +next: + link: /copilot-workshops/ko-kr/app/9-review/ + label: 검토 및 다음 단계 +--- + +마지막 모듈에서는 [에이전트 빌드 및 배포][previous-module]에서 테스트한 호스팅 에이전트를 로컬에서 실행하는 Tailspin Toys 웹사이트에 연결합니다. + +이 모듈을 마치면 다음을 갖추게 됩니다. + +- Foundry 자격 증명과 대화 식별자를 보호하는 로컬 Azure Functions 프록시(Proxy) +- 엔드투엔드(End-to-end) 동작을 검증한 접근성 있는 채팅 위젯 +- 로컬에서 검증한 통합과 리소스 정리 체크포인트 + +## 시나리오 + +Tailspin Toys 후원자는 게임을 둘러보는 곳에서 카탈로그 관련 안내를 받아야 합니다. Backer Concierge는 대화를 유지하고 키보드 탐색을 지원하며, 제공되지 않는 정보와 오류를 명확하게 처리해야 합니다. 이러한 편의성을 제공하더라도 서비스 자격 증명이나 내부 대화 세부 정보를 브라우저에 노출해서는 안 됩니다. + +## 호스팅 에이전트 체크포인트에서 재개 + +통합할 때는 새 Foundry 리소스를 만드는 대신 기존 호스팅 에이전트를 사용합니다. + +1. 이전 모듈의 동일한 Tailspin Toys 리포지토리, 워크트리(Worktree) 브랜치, **Add a Backer Concierge assistant for catalog questions** 이슈 세션으로 돌아갑니다. 루트 `azure.yaml`, 에이전트 소스, 카탈로그가 있는지 확인하고, 기록해 둔 구독, 전용 리소스 그룹, Foundry 프로젝트, 모델 배포, 테스트한 호스팅 에이전트 버전을 확인합니다. +2. 리소스를 정리했다면 통합하기 전에 관련 [프로젝트와 모델][project-module] 및 [테스트한 호스팅 배포][previous-module]를 복원합니다. + +## 서버 측 프록시 빌드 + +Tailspin Toys는 전체를 사전 렌더링합니다. 브라우저 코드는 호스팅 에이전트를 직접 호출하거나 Foundry 자격 증명을 받아서는 절대 안 됩니다. 로컬 Azure Functions의 **서버 측 자격 증명 경계**에서 Foundry 인증을 처리하고 브라우저에는 에이전트 응답만 반환합니다. 브라우저는 각 메시지를 불투명한 대화 핸들(Opaque conversation handle)과 함께 전송합니다. 프록시는 내부 식별자를 노출하지 않고 해당 핸들을 Foundry 대화에 매핑합니다. + +Azure 자격 증명에 액세스할 수 있는 코드는 프록시뿐입니다. 이 워크숍에서는 Function과 사이트를 로컬에서 실행하며, Astro 개발 서버가 `/api` 요청을 Function으로 전달합니다. + +> [!IMPORTANT] +> 이 워크숍 프록시는 로컬 개발 전용입니다. 익명 공개 엔드포인트로 배포해서는 안 됩니다. 프로덕션 통합에는 적절한 속도 제한 또는 할당량, CORS 제한, 모니터링, 비용 제어를 포함하여 애플리케이션에 맞게 설계한 인증 및 악용 방지 방안이 필요합니다. + +3. 동일한 Copilot 세션에서 다음을 입력합니다. + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. 생성된 프록시와 집중 테스트를 검토하여 요청 유효성 검사, 민감한 정보를 제거한 오류, 불투명한 대화 핸들, 서버 전용 자격 증명 경계를 확인합니다. Copilot에 집중 테스트를 실행하고 실패한 부분을 수정하도록 요청합니다. +5. 다른 터미널을 열고 Copilot이 제공한 명령으로 로컬 Function을 시작한 다음 실행 상태로 둡니다. +6. 채팅으로 돌아가 Copilot에 로컬 프록시를 테스트하도록 요청합니다. + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. 응답을 검사합니다. 카탈로그에 가격 정보가 없음을 설명해야 합니다. Foundry 토큰, 자격 증명, 내부 대화 식별자, 프로젝트 엔드포인트, 스택 추적이 포함되어 있지 않은지 확인합니다. Function에 연결할 수 없거나 응답이 세부 정보를 유출하거나 가격을 지어내면, 민감한 정보를 제거한 실패 내용을 Copilot에 전달하고 수정한 다음, 계속하기 전에 프록시 테스트를 다시 실행합니다. + + ![로컬 프록시 테스트](../../../_images/app-8-local-proxy-test.png) + +## 채팅 위젯 빌드 및 테스트 + +프록시가 실행 중인 상태에서 위젯은 Foundry 세부 정보를 노출하지 않고 사이트에 대화 화면을 제공합니다. + +8. Copilot에 사이트 통합을 구현하도록 요청합니다. + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. 다른 터미널에서 Copilot이 제공한 명령으로 Astro 개발 서버를 시작합니다. 사이트와 로컬 Function을 모두 실행 상태로 유지합니다. +10. Copilot에 엔드투엔드 테스트를 실행하도록 요청합니다. + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. 보고서를 검토하고 키보드 사용과 [호스팅 에이전트 승인 검사][agent-checks]의 두 턴 대화를 포함하여 보고된 동작을 브라우저에서 검증합니다. 브라우저 요청이 Foundry로 직접 전송되지 않고 불투명한 핸들과 함께 `/api/concierge`를 거치는지, 응답에 자격 증명이나 내부 Foundry 식별자가 노출되지 않는지 확인합니다. 추천과 누락된 정보에 대한 답변이 카탈로그 범위 안에 머무르는지 확인합니다. 실패한 테스트를 Copilot과 함께 해결하고 필요한 경우 영향을 받는 로컬 서비스를 다시 시작한 다음 테스트를 다시 실행합니다. + + ![Backer Concierge 위젯의 엔드투엔드 테스트 결과](../../../_images/app-8-e2e-test-results.png) + +## 체크포인트 및 다음 단계 + +자격 증명을 안전하게 보호하는 로컬 프록시를 빌드하고 접근성 있는 채팅 위젯을 연결한 다음, 호스팅 Backer Concierge를 대상으로 전체 대화 흐름을 검증했습니다. 이 모듈의 체크포인트는 카탈로그 범위를 유지하고 자격 증명과 내부 Foundry 식별자를 브라우저에 노출하지 않는, 로컬에서 테스트한 웹사이트 통합입니다. 프록시나 사이트를 프로덕션에 배포한 것은 아닙니다. + +실험을 마치면 두 로컬 서비스를 모두 중지하고 [Azure 리소스를 정리합니다][cleanup]. 그런 다음 핵심 워크숍 경로의 [검토 및 다음 단계][core-review]로 계속 진행합니다. + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#로컬에서-에이전트-검사 +[cleanup]: ../#리소스-정리 +[core-review]: ../../9-review/ diff --git a/docs/ko-kr/app/8-foundry-canvas/README.md b/docs/ko-kr/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..ee90a70b --- /dev/null +++ b/docs/ko-kr/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "선택 사항: Foundry 통합" +slug: ko-kr/app/8-foundry-canvas +description: "Microsoft Foundry Canvas로 카탈로그에 근거한 Backer Concierge를 구축하고, 각 단계에서 안전하게 작업을 마치는 방법을 알아봅니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/ko-kr/app/9-review/ + label: 검토 및 다음 단계 +next: + link: /copilot-workshops/ko-kr/app/8-foundry-canvas/1-project-and-model/ + label: 프로젝트와 모델 준비 +--- + +이 선택 실습 과정에서는 GitHub Copilot app의 Microsoft Foundry Canvas를 사용하여 Tailspin Toys에 **Backer Concierge**를 추가합니다. 카탈로그에 근거한 모델 실험으로 시작하여 호스팅 에이전트를 구축한 다음 로컬 웹사이트에 통합합니다. + +## 실습 과정 + +각 모듈은 체크포인트와 안전하게 작업을 마칠 수 있는 지점으로 끝납니다. 전체 과정에서 동일한 Tailspin Toys 리포지토리, 워크트리(Worktree) 브랜치, 이슈에 연결된 세션, Foundry 프로젝트, 모델 배포를 계속 사용합니다. + +- [프로젝트와 모델 준비][module-1]에서는 카탈로그 정보의 범위를 정하고, 프로젝트와 모델 배포를 만든 다음 Canvas에서 확인합니다. +- [에이전트 빌드 및 배포][module-2]에서는 Backer Concierge의 기본 구조를 생성하고 로컬에서 테스트한 다음, 호스팅 에이전트를 배포하고 다시 테스트합니다. +- [에이전트를 사이트에 연결][module-3]에서는 자격 증명을 안전하게 보호하는 로컬 프록시, 접근성을 갖춘 채팅 위젯, 엔드투엔드(End-to-end) 테스트를 추가합니다. + +> [!IMPORTANT] +> Microsoft Foundry Canvas와 호스팅 에이전트는 공개 미리 보기 상태입니다. +> +> 이 과정에서는 모델 배포와 모듈 2부터 사용하는 호스팅 에이전트 등 요금이 발생하는 Azure 리소스를 만듭니다. 리소스를 만들기 전에 구독, 지역, 할당량, 예상 비용을 승인해야 합니다. 프로젝트와 모델까지만 준비하고 중단하더라도 리소스를 정리해야 합니다. + +1. [프로젝트와 모델 준비][module-1]부터 시작합니다. 이 워크숍 콘텐츠 리포지토리가 아니라 Tailspin Toys 리포지토리에서 작업합니다. +2. 핵심 워크숍을 마치려면 [검토 및 다음 단계][core-review]로 이동합니다. + +## 리소스 정리 + +어느 체크포인트에서 실험을 마치든 원치 않는 비용을 방지하려면 Azure 리소스를 삭제합니다. 정리하면 이후 모듈에 필요한 리소스도 삭제되므로 나중에 계속하려면 다시 만들어야 합니다. + +> [!WARNING] +> `rg-tailspin-toys`가 이 실습 전용이고 유지해야 하는 리소스를 포함하지 않는 경우에만 삭제합니다. 공유 리소스 그룹을 삭제하면 관련 없는 리소스도 삭제됩니다. +> +> 모듈 1에서 다른 리소스 그룹 이름을 승인했다면 아래 모든 명령에서 `rg-tailspin-toys`를 해당 이름으로 바꿉니다. + +1. 시작한 로컬 Agent Inspector, Azure Function 또는 Astro 개발 서버를 각각의 터미널에서 중지합니다. +2. 모듈 2 또는 3에서 호스팅 에이전트를 배포했다면 동일한 Tailspin Toys 워크트리에서 터미널을 열고 같은 `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 + ``` + +## 리소스 + +Microsoft 문서에서는 Canvas, 호스팅 배포, 관련 권한을 설명합니다. + +- [Microsoft Foundry Canvas란?][foundry-canvas] +- [Foundry Canvas로 첫 번째 호스팅 에이전트 배포][hosted-agent-quickstart] +- [호스팅 에이전트 권한][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/ko-kr/app/9-review.md b/docs/ko-kr/app/9-review.md index af5579b6..0aa6d58d 100644 --- a/docs/ko-kr/app/9-review.md +++ b/docs/ko-kr/app/9-review.md @@ -4,6 +4,7 @@ description: "GitHub Copilot app 실습 과정을 되짚어 보고, 반복 작 authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- 지난 여러 레슨에서 GitHub Copilot app으로 아이디어를 기능으로 만들고 병합하기까지 다음 작업을 수행했습니다. @@ -62,6 +63,8 @@ AI 도구를 사용할 때는 도구를 둘러싼 인프라가 결과의 품질 GitHub Copilot 생태계를 더 살펴보려면 [VS Code 실습 과정](../../vscode/), [Copilot CLI 실습 과정](../../cli/), [Cloud agent 실습 과정](../../cloud/)을 확인합니다. +Microsoft Foundry Canvas를 사용하는 선택 확장 과정을 살펴보려면 [선택 사항: Foundry 통합][foundry-canvas]으로 이동합니다. + ## 리소스 - [GitHub Copilot app 정보][about-copilot-app] @@ -80,4 +83,5 @@ GitHub Copilot 생태계를 더 살펴보려면 [VS Code 실습 과정](../../vs [chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models -[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ \ No newline at end of file diff --git a/docs/ko-kr/app/README.md b/docs/ko-kr/app/README.md index f59f1f62..f8b5a50a 100644 --- a/docs/ko-kr/app/README.md +++ b/docs/ko-kr/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 [**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app)은 Copilot CLI를 기반으로 구축된 데스크톱 애플리케이션으로, 에이전트 기반 개발을 하나의 집중된 워크스페이스에서 수행할 수 있게 해 줍니다. 병렬 에이전트 세션, 전환 가능한 세션 모드, 공유 캔버스, GitHub 이슈 및 끌어오기 요청 기본 관리 기능을 제공합니다. 여기에는 끌어오기 요청의 리베이스, 검토 피드백, CI 수정, 병합 과정을 관리하는 **Agent Merge**도 포함됩니다. -이 레슨에서는 앱을 설치하고 프로젝트를 설정한 다음, 앱 워크스페이스와 템플릿에서 미리 생성한 백로그를 살펴봅니다. 별점을 추가하는 작은 변경으로 시작한 뒤, 이슈를 바탕으로 사용자 지정 지침 표준을 추가하고, 격리된 에이전트 세션에서 필터링 기능을 구축하고, 재사용 가능한 스킬로 검증합니다. Playwright MCP 서버를 추가하여 실제 브라우저에서 기능을 살펴본 다음, **Agent Merge**가 끌어오기 요청을 병합하는 단계까지 병합 자동화 수준을 높입니다. 마지막으로 공유 캔버스에서 협업하고, 선택적으로 Microsoft Foundry Canvas를 사용해 호스팅 에이전트를 구축하고, 반복 작업을 자동화하여 아이디어를 병합된 기능으로 완성하는 전체 과정을 경험합니다. +이 레슨에서는 앱을 설치하고 프로젝트를 설정한 다음, 앱 워크스페이스와 템플릿에서 미리 생성한 백로그를 살펴봅니다. 별점을 추가하는 작은 변경으로 시작한 뒤, 이슈를 바탕으로 사용자 지정 지침 표준을 추가하고, 격리된 에이전트 세션에서 필터링 기능을 구축하고, 재사용 가능한 스킬로 검증합니다. Playwright MCP 서버를 추가하여 실제 브라우저에서 기능을 살펴본 다음, **Agent Merge**가 끌어오기 요청을 병합하는 단계까지 병합 자동화 수준을 높입니다. 마지막으로 공유 캔버스에서 협업하고 반복 작업을 자동화하여 아이디어를 병합된 기능으로 완성하는 전체 과정을 경험합니다. 세 모듈로 구성된 선택 확장 과정에서는 Microsoft Foundry Canvas로 프로젝트와 모델을 준비하고, 에이전트를 빌드하여 배포한 다음, 사이트에 연결합니다. ## 레슨 @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. Playwright MCP로 테스트][ex5] | 외부 도구 | Playwright MCP 서버를 추가하고 브라우저에서 기능 살펴보기 | | [6. Agent Merge로 병합][ex6] | 병합 | Agent Merge가 필터링 끌어오기 요청을 수정하고 병합하도록 하기 | | [7. 캔버스로 계획 수립][ex7] | 협업 | 작업을 계획하고 추적하는 공유 캔버스 만들기 | -| [8. Backer Concierge 에이전트 빌드(선택 사항)][foundry-canvas] | AI 에이전트 | 카탈로그 기반 호스팅 에이전트를 빌드, 테스트, 배포 및 통합하기 | | [9. 검토 및 다음 단계][ex9] | 요약 | 반복 작업을 자동화하고 다음에 살펴볼 내용 알아보기 | +| [선택 사항: Foundry 통합][foundry-canvas] | AI 에이전트 | 프로젝트와 모델을 준비하고, 카탈로그에 근거한 에이전트를 빌드하여 배포한 다음, 사이트에 연결하기 | ## 필수 조건 diff --git a/docs/pt-br/app/7-canvases.md b/docs/pt-br/app/7-canvases.md index d16d4c9a..2e5371e5 100644 --- a/docs/pt-br/app/7-canvases.md +++ b/docs/pt-br/app/7-canvases.md @@ -4,6 +4,9 @@ description: "Crie um canvas compartilhado e orientado por agentes no aplicativo authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/pt-br/app/9-review/ + label: "Revisão e próximos passos" --- Até agora, você orientou agentes pelo chat. No entanto, grande parte do trabalho não acontece em uma conversa, mas em um quadro, documento ou checklist. Os **canvases** oferecem a você e ao agente uma superfície compartilhada exatamente para esse tipo de trabalho, dentro do aplicativo. Nesta lição, você criará um canvas simples para planejar e acompanhar o backlog no qual vem trabalhando. @@ -113,7 +116,7 @@ Você criou uma superfície compartilhada na qual você e o agente podem colabor - salvou o canvas no repositório e fez o merge dele com o Agent Merge. - abriu o canvas em uma nova sessão e o usou para começar a trabalhar. -Com o acompanhamento do backlog configurado, você pode encerrar por aqui ou continuar. Para criar um agente de IA hospedado com base no catálogo da Tailspin Toys, avance para a [lição opcional do Backer Concierge][next-lesson]. Caso contrário, vá para a [Lição 9 - Revisão e próximos passos][review-lesson]. +Com o acompanhamento do backlog configurado, continue para [revisar o que você criou][next-lesson]. Para uma extensão opcional usando o Microsoft Foundry Canvas, explore [Opcional: Incorporar o Foundry][foundry-canvas]. ## Recursos @@ -121,8 +124,8 @@ Com o acompanhamento do backlog configurado, você pode encerrar por aqui ou con - [Canvases no Awesome Copilot][awesome-copilot-canvases] - [Sobre o aplicativo GitHub Copilot][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/pt-br/app/8-foundry-canvas/1-project-and-model.md b/docs/pt-br/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..12554caf --- /dev/null +++ b/docs/pt-br/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "Preparar o projeto e o modelo" +description: "Exporte o catálogo da Tailspin, crie um projeto do Foundry e uma implantação de modelo e valide ambos no Canvas." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/ + label: "Opcional: Incorporar o Foundry" +next: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/2-build-and-deploy/ + label: Criar e implantar o agente +--- + +Este primeiro módulo prepara os dados e os recursos do Azure para o Backer Concierge. Ainda não é necessário ter código do agente nem uma implantação hospedada. + +Ao final, você terá: + +- Uma exportação do catálogo com limites explícitos para fundamentar as respostas. +- Um projeto do Foundry e uma implantação de modelo escolhida para os requisitos do recurso. +- Uma implantação validada no Canvas e uma verificação básica do modelo com respostas limitadas ao catálogo. + +## Cenário + +As pessoas que apoiam a Tailspin Toys podem filtrar jogos por categoria e editora, mas perguntas como *Quais jogos seriam adequados para quem adora trocadilhos com Git?* não têm respostas em menus suspensos. Um Backer Concierge deve recomendar somente jogos do catálogo da Tailspin e nunca inventar jogos, editoras, avaliações, totais arrecadados, números de apoiadores, preços, números de jogadores, durações de partidas ou datas de lançamento. Um catálogo confiável e um modelo adequado são a base dessas respostas. + +## Preparar suas ferramentas e a sessão da issue + +A configuração conecta o aplicativo GitHub Copilot ao Azure e mantém todo o trabalho do recurso reunido. + +1. Confirme que você tem uma assinatura do Azure. Se precisar de uma, as opções disponíveis incluem uma [assinatura gratuita do Azure com US$ 200 de crédito][azure-free] ou o [Azure for Students com US$ 100 em créditos][azure-students]. +2. Instale a [Azure CLI][install-azure-cli] para seu sistema operacional e verifique a instalação usando `az version`. +3. Instale a [Azure Developer CLI][install-azd] e use `azd version` para verificar se a versão instalada é a 1.27.1 ou posterior. +4. Abra o aplicativo GitHub Copilot, abra **Customize** e selecione **Plugins**. Pesquise por `microsoft-foundry` e selecione **Install** para o plugin Microsoft Foundry, que inclui o Canvas e as skills do Foundry. + + ![Instalar o plugin Microsoft Foundry](../../../_images/app-8-install-foundry-plugin.png) + +5. Em **Customize**, selecione **Plugins**, pesquise por `azure` ou selecione-o na lista **Featured** e selecione **Install** para o plugin Azure. +6. Na aba **My work**, encontre e abra a issue intitulada **Add a Backer Concierge assistant for catalog questions** no repositório Tailspin Toys. Selecione **New session** para iniciar uma sessão vinculada à issue em um novo worktree. Mantenha este repositório, branch do worktree e sessão da issue nos três módulos. +7. Digite `/microsoft-foundry` e depois `/azure` para confirmar que as duas skills estão instaladas e disponíveis; não envie prompts ainda. Se um plugin não aparecer imediatamente, reinicie o aplicativo, volte para esta mesma sessão da issue e verifique novamente. + +## Gerar a exportação do catálogo + +O repositório de exemplo inclui um script de exportação que fornece ao agente um arquivo que ele pode ler. + +8. Nesta sessão de worktree vinculada à issue, substitua o prompt padrão `/fix-issue` na caixa de prompt por: + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. Revise a saída dos comandos. O Copilot deve executar o equivalente a: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![Gerar a exportação do catálogo](../../../_images/app-8-generate-catalog-export.png) + +10. Abra `db/catalog.json` e confirme que ele contém 21 jogos com título, descrição, categoria, editora e avaliação por estrelas. Verifique o campo `note`: o catálogo não contém totais arrecadados, números de apoiadores, faixas de contribuição nem datas de lançamento. Considere também como indisponíveis os preços, números de jogadores e durações de partidas ausentes, em vez de preencher as lacunas com conhecimento externo. Se a exportação falhar ou apresentar diferenças, peça ao Copilot que investigue e execute-a novamente antes de continuar. + + ![Exportação do catálogo aberta no aplicativo Copilot](../../../_images/app-8-view-catalog.png) + +## Configurar um projeto e um modelo do Foundry + +Criar primeiro o projeto e a implantação no chat garante que o Canvas se conecte somente a recursos que já existem. + +11. Selecione **+**, selecione **Terminal** e entre no Azure: + + ```bash + az login + ``` + +12. Verifique a assinatura selecionada e liste os grupos de recursos: + + ```bash + az account show --output table + az group list --output table + ``` + + Se a assinatura estiver incorreta, execute `az account set --subscription ` e repita os dois comandos. + + Se `rg-tailspin-toys` aparecer, inspecione os recursos: + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + Se o grupo contiver recursos não relacionados ou compartilhados, pare e escolha um nome dedicado antes de usar o prompt a seguir. Substitua os nomes de exemplo em todos os prompts e comandos posteriores pelos nomes aprovados. +13. Na mesma sessão da issue, insira: + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![Criar o projeto do Foundry](../../../_images/app-8-foundry-project-created.png) + +14. Peça ao Copilot que recomende um modelo. Os critérios de aceitação da issue já estão no contexto porque a sessão foi iniciada a partir da issue: + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. Confirme que o Copilot carrega a skill `microsoft-foundry` e escolha um modelo disponível com base nas vantagens e limitações de cada opção. O guia de início rápido de agentes hospedados do Microsoft Foundry usa atualmente `gpt-5.4-mini`, mas a disponibilidade e a cota variam de acordo com a região. + + ![Selecionar o modelo](../../../_images/app-8-select-model.png) + +16. Peça ao Copilot que implante sua seleção, revisando o projeto de destino e o custo antes de aprovar: + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> A disponibilidade dos modelos muda com o tempo. A escolha adequada é o modelo que o Copilot confirma estar disponível no seu projeto, e não um modelo fixo indicado neste módulo. + +## Validar e fazer uma verificação básica do modelo no Canvas + +Esta verificação valida o projeto e o modelo antes de existir qualquer código do agente. Uma verificação básica do modelo não substitui os testes de fundamentação das respostas do agente hospedado no módulo 2. + +17. Selecione **+**, depois **Canvas** e depois **Microsoft Foundry (Preview)**. +18. Abra o menu **More options** no canto superior direito do Canvas e selecione **Sign in**. +19. Selecione o projeto **tailspin-toys** do Foundry. Expanda **Models** e confirme que a implantação aparece com o nome e o status esperados. + + ![Validar o projeto e o modelo no Canvas](../../../_images/app-8-validate-project-model.png) + +20. Na mesma sessão, insira: + + ```plaintext + Use a skill do Microsoft Foundry para testar diretamente o modelo implantado no projeto tailspin-toys sem criar um agente. Fundamente a resposta no conteúdo de @db/catalog.json e pergunte: "Adoro jogos de quebra-cabeça sobre rastrear bugs. Qual jogo devo apoiar e quanto ele arrecadou?". Mostre a resposta e metadados úteis, como os tokens usados e o tempo de resposta, somente se estiverem disponíveis. Use meu login existente do Azure. Não exiba credenciais, altere arquivos nem crie recursos. + ``` + +21. Revise a resposta. Ela deve recomendar apenas um jogo real de `db/catalog.json`, usar o título, a editora e a avaliação corretos e explicar que as informações de financiamento não estão disponíveis. Se o modelo inventar um jogo, detalhes do catálogo ou um valor de financiamento, compare outro modelo recomendado antes de continuar. + +> [!NOTE] +> O Canvas lembra o projeto selecionado quando é reaberto. Suas etapas são **Create new hosted agents**, para gerar a estrutura inicial; **Build current hosted agent**, para conectar modelos, caixas de ferramentas, skills e mecanismos de proteção; e **Deploy and test**, para executar localmente e implantar no Microsoft Foundry. + +## Ponto de verificação e próximos passos + +Você preparou as ferramentas do Azure, exportou o catálogo e testou um modelo implantado de acordo com as regras de fundamentação do Backer Concierge. O ponto de verificação deste módulo é um modelo que recomenda jogos reais do catálogo sem inventar informações ausentes. + +Em seguida, você usará o mesmo repositório Tailspin Toys, branch do worktree, sessão vinculada à issue, projeto do Foundry e implantação de modelo selecionada para [criar e implantar o agente][next-module]. Se encerrar aqui, [limpe os recursos do Azure][cleanup] para evitar custos contínuos. + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#limpar-seus-recursos diff --git a/docs/pt-br/app/8-foundry-canvas/2-build-and-deploy.md b/docs/pt-br/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..0d8d0a23 --- /dev/null +++ b/docs/pt-br/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,160 @@ +--- +title: "Criar e implantar o agente" +description: "Gere a estrutura inicial do Backer Concierge no Canvas, inspecione-o localmente e implante e teste-o novamente no Foundry." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/1-project-and-model/ + label: Preparar o projeto e o modelo +next: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/3-connect-to-site/ + label: Conectar o agente ao site +--- + +Este módulo transforma o projeto, a implantação de modelo e o catálogo de [Preparar o projeto e o modelo][previous-module] em um Backer Concierge hospedado por meio do Microsoft Foundry Canvas. + +Ao final, você terá: + +- A estrutura inicial de um agente com os dados do catálogo empacotados e testes focados. +- Evidências locais para cada critério de aceitação relacionado ao catálogo e à conversa. +- Uma versão implantada do agente testada novamente no Foundry. + +## Cenário + +A Tailspin Toys precisa de um concierge que responda a perguntas reais sobre o catálogo, reconheça quando faltam informações e lembre os jogos discutidos em uma conversa. O serviço precisa conquistar essa confiança antes de fazer parte da loja. + +## Preparar as ferramentas de implantação + +A inspeção e a implantação de agentes hospedados usam a Azure Developer CLI por meio do Canvas; o projeto e o modelo existentes do Foundry são reutilizados. + +1. Retome a mesma sessão vinculada à issue **Add a Backer Concierge assistant for catalog questions** do módulo 1. Confirme que `db/catalog.json` está intacto, que você está conectado à assinatura e ao projeto do Foundry corretos e que a implantação de modelo continua disponível. Se os recursos foram removidos na limpeza, repita primeiro as etapas relevantes da [configuração do projeto e do modelo][previous-module]. + +2. Selecione **+**, selecione **Terminal** e entre na Azure Developer CLI, concluindo a autenticação no navegador quando solicitado: + + ```bash + azd auth login + ``` + +3. Execute `azd config show` para verificar a assinatura do Azure. Se ela estiver vazia ou incorreta, atualize-a com `azd config set defaults.subscription ` e execute `azd config show` novamente para confirmar a alteração. +## Gerar a estrutura inicial do Backer Concierge + +O Canvas gera o código, a estrutura de pastas e o `azure.yaml` na raiz que conectam o Backer Concierge à implantação de modelo existente. + +4. Na versão prévia de **Create new hosted agents**, insira: + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + O Canvas envia ao Copilot o prompt e o contexto da assinatura atual e do projeto do Foundry. Ele procura exemplos de Agent Framework + Responses API; pode aparecer uma opção como **Agent with Local Tools (Responses, Agent Framework, Python)**. + + ![Gerar a estrutura inicial do agente Backer Concierge no Canvas](../../../_images/app-8-scaffold-backer-concierge.png) + +5. Revise as alterações do Copilot na aba **Files** com base neste ponto de verificação. Os nomes dos arquivos gerados dentro de `src` podem variar, mas os limites do projeto e a localização de `azure.yaml` devem corresponder ao seguinte: + + - O agente fica em `agent/backer-concierge`. + - Um único `azure.yaml` na raiz do repositório contém um serviço com `host: azure.ai.agent`. + - O agente que será implantado inclui sua própria cópia gerada do catálogo. + - Testes focados cobrem os requisitos de fundamentação das respostas no catálogo. + - Nenhuma credencial ou arquivo de ambiente local está incluído. + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. Peça ao Copilot que execute os testes focados e corrija quaisquer falhas antes de continuar para **Deploy and test**. + +## Inspecionar o agente localmente + +**Inspect Locally** executa `azd ai agent run` no terminal integrado do Copilot, aguarda o agente hospedado iniciar e abre o Agent Inspector incorporado. + +7. Em **Deploy and test**, selecione **Inspect Locally** e aguarde o Agent Inspector abrir. + +> [!NOTE] +> A primeira execução local pode levar vários minutos enquanto `azd` cria um ambiente e instala as dependências. + +8. Se o inspetor não conseguir se conectar, confirme que nenhum outro processo está usando a porta necessária, envie o erro ao Copilot e tente novamente após a correção do problema. +9. Teste uma **recomendação fundamentada no catálogo** no Agent Inspector: + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + Resultado esperado: menciona somente títulos reais do catálogo e usa as informações corretas para cada título. + + ![Recomendação fundamentada no catálogo no Agent Inspector](../../../_images/app-8-grounded-recommendation.png) + +10. Teste uma **armadilha de alucinação**: + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + Resultado esperado: explica que o catálogo não acompanha a arrecadação nem os apoiadores e, em seguida, oferece informações que estão presentes. + +11. Teste a **pressão para ir além do catálogo**: + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + Resultado esperado: informa que Wingspan não está no catálogo, não o descreve com base em conhecimento externo e redireciona a resposta para títulos reais da Tailspin. + +12. Teste um **pedido vago**: + + ```text + Recommend me something good. + ``` + + Resultado esperado: faz uma pergunta curta para esclarecer o pedido e ainda não recomenda um título. + +13. Teste a **precisão da classificação**: + + ```text + What are your three highest rated games? + ``` + + Resultado esperado: retorna as três entradas mais bem avaliadas do catálogo na ordem correta e com as avaliações corretas. + +14. Teste a **continuidade da conversa** enviando estes prompts na mesma conversa: + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + Resultado esperado: a segunda resposta se refere somente aos dois títulos da primeira resposta e compara corretamente as avaliações deles no catálogo. + +15. Compare cada resposta com `db/catalog.json` e os critérios de aceitação da issue. Confirme que o agente nunca inventa jogos, editoras, avaliações, totais arrecadados, números de apoiadores, preços, números de jogadores, durações de partidas ou datas de lançamento. Se o Agent Inspector relatar um erro ou uma resposta ultrapassar os limites das informações do catálogo, copie o resultado para a área de prompt do Canvas e peça ao Copilot que corrija o problema. Reinicie a inspeção local e execute novamente o teste que falhou após cada alteração; depois, confirme que todas as seis verificações passaram antes de implantar. + +## Implantar e testar novamente o agente hospedado + +O Canvas usa `azd` para implantar o agente testado. O Foundry empacota o código-fonte do serviço, resolve as dependências, faz o build remotamente e publica o serviço no Microsoft Foundry. + +16. No Canvas, em **Deploy and test**, selecione **Deploy to Foundry**. Revise o prompt que ele insere no chat. + + ![Prompt Deploy to Foundry no Canvas](../../../_images/app-8-deploy-to-foundry.png) + +17. Verifique se há uma confirmação de implantação, a versão do agente, o status e um link para o playground do agente no Foundry. Se a implantação falhar, envie o erro ao Copilot e resolva-o no mesmo projeto antes de tentar novamente pelo Canvas. +18. Selecione **Test in Foundry Portal** no Canvas para abrir o playground do agente implantado. Execute novamente todas as seis verificações de aceitação das etapas 9–14 nesta versão implantada, mantendo o par de prompts em uma única conversa para testar a continuidade. Compare as respostas com o catálogo; se alguma verificação falhar, peça ao Copilot que corrija o problema, execute novamente os testes locais, reimplante pelo Canvas e teste novamente a versão hospedada. + +## Ponto de verificação e próximos passos + +Você gerou a estrutura inicial do Backer Concierge, testou localmente a fundamentação no catálogo e o comportamento da conversa, implantou-o no Microsoft Foundry e testou novamente a versão hospedada. O ponto de verificação deste módulo é um agente hospedado que passa nas seis verificações de aceitação sem inventar informações ausentes. + +Em seguida, você usará o mesmo repositório Tailspin Toys, branch do worktree, sessão vinculada à issue, projeto do Foundry, implantação de modelo selecionada e agente hospedado para [conectar o agente ao site][next-module]. Se encerrar aqui, [limpe os recursos do Azure][cleanup] para evitar custos contínuos. + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#limpar-seus-recursos diff --git a/docs/pt-br/app/8-foundry-canvas/3-connect-to-site.md b/docs/pt-br/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..2bc4ff94 --- /dev/null +++ b/docs/pt-br/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "Conectar o agente ao site" +description: "Integre o Backer Concierge hospedado por meio de um proxy local que protege as credenciais e teste o widget de ponta a ponta." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/2-build-and-deploy/ + label: Criar e implantar o agente +next: + link: /copilot-workshops/pt-br/app/9-review/ + label: Revisão e próximos passos +--- + +Este último módulo conecta o agente hospedado testado em [Criar e implantar o agente][previous-module] ao site da Tailspin Toys em execução local. + +Ao final, você terá: + +- Um proxy local do Azure Functions que protege as credenciais do Foundry e os identificadores de conversa. +- Um widget de chat acessível com comportamento verificado de ponta a ponta. +- Uma integração verificada localmente e um ponto de verificação para a limpeza dos recursos. + +## Cenário + +As pessoas que apoiam a Tailspin Toys precisam de orientações sobre o catálogo no mesmo lugar em que exploram os jogos. O Backer Concierge deve preservar a conversa, funcionar com navegação pelo teclado e lidar de forma clara com informações indisponíveis e erros. Essa conveniência não pode expor credenciais do serviço nem detalhes internos da conversa ao navegador. + +## Retomar o ponto de verificação do agente hospedado + +A integração usa o agente hospedado existente, em vez de criar novos recursos do Foundry. + +1. Retome o mesmo repositório Tailspin Toys, branch do worktree e sessão da issue **Add a Backer Concierge assistant for catalog questions** dos módulos anteriores. Confirme que o `azure.yaml` na raiz, o código-fonte do agente e o catálogo estão presentes e verifique a assinatura registrada, o grupo de recursos dedicado, o projeto do Foundry, a implantação de modelo e a versão testada do agente hospedado. +2. Se os recursos foram removidos na limpeza, restaure o [projeto e o modelo][project-module] e a [implantação hospedada testada][previous-module] correspondentes antes da integração. + +## Criar o proxy do lado do servidor + +A Tailspin Toys é totalmente pré-renderizada. O código do navegador nunca deve chamar o agente hospedado diretamente nem receber credenciais do Foundry. Uma **barreira de proteção de credenciais do lado do servidor**, implementada localmente com o Azure Functions, faz a autenticação no Foundry e retorna somente a resposta do agente ao navegador. O navegador envia cada mensagem com uma referência opaca à conversa; o proxy mapeia essa referência para a conversa do Foundry sem expor o identificador interno. + +O proxy é a única parte do código que tem permissão para acessar suas credenciais do Azure. Neste workshop, a Function e o site são executados localmente, com o servidor de desenvolvimento do Astro encaminhando as solicitações `/api` para a Function. + +> [!IMPORTANT] +> Este proxy do workshop é apenas para desenvolvimento local. Ele não deve ser implantado como um endpoint público anônimo. Uma integração de produção precisa de um projeto de autenticação e controle de abuso específico para a aplicação, incluindo limites de taxa ou cotas adequados, restrições de CORS, monitoramento e controles de custo. + +3. Na mesma sessão do Copilot, insira: + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. Revise o proxy gerado e os testes focados quanto à validação de solicitações, à remoção de informações sensíveis dos erros, às referências opacas de conversa e à proteção de credenciais restrita ao servidor. Peça ao Copilot que execute os testes focados e corrija quaisquer falhas. +5. Abra outro terminal, inicie a Function local usando o comando fornecido pelo Copilot e deixe-a em execução. +6. Volte ao chat e peça ao Copilot que teste o proxy local: + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. Inspecione a resposta: ela deve explicar que o catálogo não contém preços. Confirme que ela não contém token do Foundry, credencial, identificador interno de conversa, endpoint do projeto nem rastreamento de pilha. Se não for possível acessar a Function ou se a resposta expuser detalhes ou inventar preços, envie ao Copilot as informações da falha sem dados sensíveis, corrija o problema e execute novamente os testes do proxy antes de continuar. + + ![Teste do proxy local](../../../_images/app-8-local-proxy-test.png) + +## Criar e testar o widget de chat + +Com o proxy em execução, o widget apresenta a conversa no site sem expor detalhes do Foundry. + +8. Peça ao Copilot que crie a integração ao site: + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. Inicie o servidor de desenvolvimento do Astro em outro terminal usando o comando fornecido pelo Copilot. Mantenha o site e a Function local em execução. +10. Peça ao Copilot que execute os testes de ponta a ponta: + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. Revise o relatório e verifique o comportamento relatado no navegador, incluindo o uso do teclado e a conversa de duas interações das [verificações de aceitação do agente hospedado][agent-checks]. Confirme que as solicitações do navegador passam por `/api/concierge` com uma referência opaca, e não diretamente pelo Foundry, e que as respostas não expõem credenciais nem identificadores internos do Foundry. Verifique se as recomendações e as respostas sobre dados ausentes permanecem dentro dos limites do catálogo. Corrija os testes que falharam com o Copilot, reinicie o serviço local afetado se necessário e execute os testes novamente. + + ![Resultados dos testes de ponta a ponta do widget Backer Concierge](../../../_images/app-8-e2e-test-results.png) + +## Ponto de verificação e próximos passos + +Você criou um proxy local que protege as credenciais, conectou um widget de chat acessível e verificou todo o fluxo da conversa com o Backer Concierge hospedado. O ponto de verificação deste módulo é uma integração ao site testada localmente que preserva os limites do catálogo e mantém as credenciais e os identificadores internos do Foundry fora do navegador. Ela não representa uma implantação de produção do proxy ou do site. + +Quando terminar de experimentar, interrompa os dois serviços locais e [limpe os recursos do Azure][cleanup]. Em seguida, continue para [Revisão e próximos passos][core-review] na rota principal do workshop. + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#inspecionar-o-agente-localmente +[cleanup]: ../#limpar-seus-recursos +[core-review]: ../../9-review/ diff --git a/docs/pt-br/app/8-foundry-canvas/README.md b/docs/pt-br/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..0274ebae --- /dev/null +++ b/docs/pt-br/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "Opcional: Incorporar o Foundry" +slug: pt-br/app/8-foundry-canvas +description: "Crie um Backer Concierge baseado no catálogo com o Microsoft Foundry Canvas, com pontos seguros para encerrar ao longo do percurso." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/pt-br/app/9-review/ + label: Revisão e próximos passos +next: + link: /copilot-workshops/pt-br/app/8-foundry-canvas/1-project-and-model/ + label: Preparar o projeto e o modelo +--- + +Este percurso opcional adiciona um **Backer Concierge** à Tailspin Toys usando o Microsoft Foundry Canvas no aplicativo GitHub Copilot. Ele começa com um experimento de modelo baseado no catálogo, avança para um agente hospedado e termina com uma integração local ao site. + +## O percurso + +Cada módulo termina com um ponto de verificação e um ponto seguro para encerrar. O mesmo repositório Tailspin Toys, branch do worktree, sessão vinculada à issue, projeto do Foundry e implantação de modelo são mantidos ao longo do percurso. + +- [Preparar o projeto e o modelo][module-1] estabelece os limites do catálogo, cria o projeto e a implantação de modelo e verifica ambos no Canvas. +- [Criar e implantar o agente][module-2] gera a estrutura inicial do Backer Concierge, testa-o localmente e implanta e testa novamente o agente hospedado. +- [Conectar o agente ao site][module-3] adiciona um proxy local que protege as credenciais, um widget de chat acessível e testes de ponta a ponta. + +> [!IMPORTANT] +> O Microsoft Foundry Canvas e os agentes hospedados estão em versão prévia pública. +> +> Este percurso cria recursos do Azure que geram custos, incluindo uma implantação de modelo e, a partir do módulo 2, um agente hospedado. A assinatura, a região, a cota e o custo estimado precisam de aprovação antes da criação dos recursos. A limpeza também se aplica quando você encerra após criar apenas o projeto e o modelo. + +1. Comece por [Preparar o projeto e o modelo][module-1], mantendo o trabalho no repositório Tailspin Toys, e não neste repositório de conteúdo do workshop. +2. Se preferir concluir o workshop principal, continue para [Revisão e próximas etapas][core-review]. + +## Limpar seus recursos + +Quando terminar de experimentar em qualquer ponto de verificação, remova os recursos do Azure para evitar custos indesejados. A limpeza remove os recursos necessários para os módulos posteriores, portanto, será necessário criá-los novamente para continuar depois. + +> [!WARNING] +> Exclua `rg-tailspin-toys` somente se ele for dedicado a este exercício e não contiver recursos que precisam ser mantidos. A exclusão de um grupo de recursos compartilhado também removerá recursos não relacionados. +> +> Se você aprovou outro nome para o grupo de recursos no módulo 1, substitua `rg-tailspin-toys` por esse nome em todos os comandos abaixo. + +1. Interrompa no respectivo terminal qualquer Agent Inspector, Azure Function ou servidor de desenvolvimento do Astro local que você iniciou. +2. Se implantou o agente hospedado no módulo 2 ou 3, abra um terminal no mesmo worktree da Tailspin Toys, use 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 + ``` + + Confirme que todos os recursos restantes pertencem a este exercício. Se parou após o módulo 1, ainda será necessário limpar o projeto do Foundry e o modelo, mesmo sem ter implantado um serviço `azd`. +4. Se o grupo de recursos dedicado do workshop ainda existir e contiver apenas os recursos que você pretende remover, execute: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Como `--no-wait` retorna antes da conclusão da exclusão, execute novamente o comando a seguir até que ele retorne `false`: + + ```bash + az group exists --name rg-tailspin-toys + ``` + +## Recursos + +A documentação da Microsoft descreve o Canvas, as implantações hospedadas e suas permissões. + +- [O que é o Microsoft Foundry Canvas?][foundry-canvas] +- [Implantar seu primeiro agente hospedado com o Foundry Canvas][hosted-agent-quickstart] +- [Permissões de agentes hospedados][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/pt-br/app/9-review.md b/docs/pt-br/app/9-review.md index 453e2d78..0a226bd8 100644 --- a/docs/pt-br/app/9-review.md +++ b/docs/pt-br/app/9-review.md @@ -4,6 +4,7 @@ description: "Recapitule o percurso do aplicativo GitHub Copilot, automatize tra authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- Nas últimas lições, você levou um recurso da ideia ao merge com o aplicativo GitHub Copilot. Nesse processo, você: @@ -62,6 +63,8 @@ A melhor maneira de melhorar com qualquer ferramenta é continuar usando-a. Use- Para conhecer melhor o ecossistema do GitHub Copilot, confira o [percurso do VS Code](../../vscode/), o [percurso do Copilot CLI](../../cli/) ou o [percurso do agente de nuvem](../../cloud/). +Para uma extensão opcional usando o Microsoft Foundry Canvas, explore [Opcional: Incorporar o Foundry][foundry-canvas]. + ## Recursos - [Sobre o aplicativo GitHub Copilot][about-copilot-app] @@ -80,4 +83,5 @@ Para conhecer melhor o ecossistema do GitHub Copilot, confira o [percurso do VS [chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models -[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ \ No newline at end of file diff --git a/docs/pt-br/app/README.md b/docs/pt-br/app/README.md index edb986ee..23241e44 100644 --- a/docs/pt-br/app/README.md +++ b/docs/pt-br/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 O [**aplicativo GitHub Copilot**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) é um aplicativo para desktop criado com base no Copilot CLI que reúne o desenvolvimento orientado por agentes em um espaço de trabalho único e focado. Ele oferece sessões paralelas de agentes, modos de sessão alternáveis, canvases compartilhados e gerenciamento nativo de issues e pull requests do GitHub, incluindo o **Agent Merge**, que conduz um pull request por rebases, feedback de revisão, correções de CI e merge. -Ao longo destas lições, você instalará o aplicativo e configurará o projeto. Depois, conhecerá o espaço de trabalho do aplicativo e o backlog que o modelo criou para você. Você começará com uma pequena alteração, adicionando uma avaliação por estrelas, e então adicionará a partir de uma issue um padrão de instruções personalizadas, criará um recurso de filtragem em uma sessão isolada de agente e o verificará com uma skill reutilizável. Você adicionará o servidor MCP do Playwright para explorar o recurso em um navegador real e, em seguida, avançará por níveis de automação de merge até que o **Agent Merge** conclua o merge do pull request. Por fim, você colaborará em um canvas compartilhado, poderá criar opcionalmente um agente hospedado com o Microsoft Foundry Canvas e automatizará trabalhos recorrentes, completando todo o ciclo, da ideia ao recurso integrado. +Ao longo destas lições, você instalará o aplicativo e configurará o projeto. Depois, conhecerá o espaço de trabalho do aplicativo e o backlog que o modelo criou para você. Você começará com uma pequena alteração, adicionando uma avaliação por estrelas, e então adicionará a partir de uma issue um padrão de instruções personalizadas, criará um recurso de filtragem em uma sessão isolada de agente e o verificará com uma skill reutilizável. Você adicionará o servidor MCP do Playwright para explorar o recurso em um navegador real e, em seguida, avançará por níveis de automação de merge até que o **Agent Merge** conclua o merge do pull request. Por fim, você colaborará em um canvas compartilhado e automatizará trabalhos recorrentes, completando todo o ciclo, da ideia ao recurso integrado. Uma extensão opcional de três módulos usa o Microsoft Foundry Canvas para preparar um projeto e um modelo, criar e implantar um agente e conectá-lo ao site. ## Lições @@ -22,8 +22,8 @@ Ao longo destas lições, você instalará o aplicativo e configurará o projeto | [5. Testar com o MCP do Playwright][ex5] | Ferramentas externas | Adicione o servidor MCP do Playwright e explore o recurso em um navegador | | [6. Fazer merge com o Agent Merge][ex6] | Merge | Permita que o Agent Merge corrija e integre o pull request de filtragem | | [7. Planejar com canvases][ex7] | Colaboração | Crie um canvas compartilhado para planejar e acompanhar seu trabalho | -| [8. Criar um agente Backer Concierge (opcional)][foundry-canvas] | Agentes de IA | Crie, teste, implante e integre um agente hospedado baseado no catálogo | | [9. Revisão e próximos passos][ex9] | Resumo | Automatize tarefas recorrentes e explore os próximos passos | +| [Opcional: Incorporar o Foundry][foundry-canvas] | Agentes de IA | Prepare um projeto e um modelo, crie e implante um agente fundamentado no catálogo e conecte-o ao site | ## Pré-requisitos diff --git a/docs/zh-cn/app/7-canvases.md b/docs/zh-cn/app/7-canvases.md index 3bf9bfb4..e273e26c 100644 --- a/docs/zh-cn/app/7-canvases.md +++ b/docs/zh-cn/app/7-canvases.md @@ -4,6 +4,9 @@ description: "在 GitHub Copilot app 中创建智能体驱动的共享画布， authors: - geektrainer lastUpdated: 2026-07-09 +next: + link: /copilot-workshops/zh-cn/app/9-review/ + label: "回顾与后续步骤" --- 此前，你通过聊天指挥智能体。但许多工作并不只存在于对话中，而是呈现在看板、文档或检查清单上。借助**画布**，你和智能体可以直接在应用内共享一个适合此类工作的界面。本课将创建一个简单画布，用于规划和跟踪一直在处理的待办事项。 @@ -113,7 +116,7 @@ Copilot app 会开始创建并管理 PR。它先探索项目以确定创建 PR - 使用 Agent Merge 将画布保存并合并到存储库。 - 在新会话中打开画布，并使用它开始工作。 -待办事项现已得到跟踪，你可以在此结束，也可以继续学习。如果想基于 Tailspin Toys 目录创建托管 AI 智能体，请继续学习[可选的 Backer Concierge 课程][next-lesson]。否则，请跳转到[第 9 课 - 回顾与后续步骤][review-lesson]。 +待办事项现已得到跟踪，接下来[回顾已完成的工作][next-lesson]。如果想通过 Microsoft Foundry Canvas 进行可选扩展，可继续探索[可选：集成 Foundry][foundry-canvas]。 ## 资源 @@ -121,8 +124,8 @@ Copilot app 会开始创建并管理 PR。它先探索项目以确定创建 PR - [Awesome Copilot 上的画布][awesome-copilot-canvases] - [关于 GitHub Copilot app][about-copilot-app] -[next-lesson]: ../8-foundry-canvas/ -[review-lesson]: ../9-review/ +[next-lesson]: ../9-review/ +[foundry-canvas]: ../8-foundry-canvas/ [canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions [awesome-copilot-canvases]: https://awesome-copilot.github.com/extensions/ [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app \ No newline at end of file diff --git a/docs/zh-cn/app/8-foundry-canvas/1-project-and-model.md b/docs/zh-cn/app/8-foundry-canvas/1-project-and-model.md new file mode 100644 index 00000000..a9b5c463 --- /dev/null +++ b/docs/zh-cn/app/8-foundry-canvas/1-project-and-model.md @@ -0,0 +1,151 @@ +--- +title: "准备项目和模型" +description: "导出 Tailspin 目录，创建 Foundry 项目和模型部署，并在 Canvas 中验证。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/ + label: "可选：集成 Foundry" +next: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/2-build-and-deploy/ + label: 构建并部署代理 +--- + +第一个模块将准备 Backer Concierge 所需的数据和 Azure 资源。目前尚不需要代理代码或托管部署。 + +完成本模块后，将获得： + +- 一份明确限定回答依据范围的目录导出文件。 +- 一个 Foundry 项目，以及根据功能要求选定的模型部署。 +- 一个经 Canvas 验证的部署，以及一次限定在目录范围内的简单模型冒烟测试结果。 + +## 场景 + +Tailspin Toys 的支持者可以按类别和发行商筛选游戏，但*哪些游戏适合喜欢 Git 双关语的人？*这类问题无法通过下拉选项解答。Backer Concierge 应只推荐 Tailspin 目录中的游戏，绝不能编造游戏、发行商、评分、筹款总额、支持者人数、价格、玩家人数、游戏时长或发布日期。可靠的目录和合适的模型是这些回答的基础。 + +## 准备工具和议题会话 + +此设置将 GitHub Copilot app 连接到 Azure，同时把所有功能开发工作集中在一起。 + +1. 确认拥有 Azure 订阅。如果需要订阅，可选择[含 200 美元额度的免费 Azure 订阅][azure-free]或[含 100 美元额度的 Azure for Students][azure-students]。 +2. 安装适用于当前操作系统的 [Azure CLI][install-azure-cli]，然后使用 `az version` 验证安装。 +3. 安装 [Azure Developer CLI][install-azd]，然后使用 `azd version` 验证已安装 1.27.1 或更高版本。 +4. 打开 GitHub Copilot app，打开 **Customize**，然后选择 **Plugins**。搜索 `microsoft-foundry`，为 Microsoft Foundry 插件选择 **Install**。该插件包含 Canvas 和 Foundry 技能。 + + ![安装 Microsoft Foundry 插件](../../../_images/app-8-install-foundry-plugin.png) + +5. 在 **Customize** 中选择 **Plugins**，搜索 `azure` 或从 **Featured** 列表中选择它，然后为 Azure 插件选择 **Install**。 +6. 在 **My work** 选项卡中，找到并打开 Tailspin Toys 存储库中标题为 **Add a Backer Concierge assistant for catalog questions** 的议题。选择 **New session**，在新工作树中启动关联该议题的会话。三个模块均使用此存储库、工作树分支和议题会话。 +7. 输入 `/microsoft-foundry`，然后输入 `/azure`，确认两个技能均已安装且可用；暂时不要发送任何提示词。如果插件未立即出现，请重启应用，返回同一个议题会话并再次检查。 + +## 生成目录导出文件 + +示例存储库包含一个导出脚本，可为代理生成能够读取的文件。 + +8. 在这个关联议题的工作树会话中，将提示框内默认的 `/fix-issue` 提示词替换为： + + ```plaintext + Install the project dependencies, seed the database, then run the existing db:export script. Show me the command output and summarize the shape and grounding limits of db/catalog.json. + ``` + +9. 查看命令输出。Copilot 应运行与以下内容等效的命令： + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![生成目录导出文件](../../../_images/app-8-generate-catalog-export.png) + +10. 打开 `db/catalog.json`，确认其中包含 21 款游戏，每款游戏都有标题、描述、类别、发行商和星级评分。检查其 `note` 字段：目录不包含筹款总额、支持者人数、支持档位或发布日期。对于缺失的价格、玩家人数和游戏时长，也应视为不可用信息，而不是用外部知识填补空白。如果导出失败或内容不符，请先要求 Copilot 调查并重新运行，再继续。 + + ![在 Copilot app 中打开的目录导出文件](../../../_images/app-8-view-catalog.png) + +## 设置 Foundry 项目和模型 + +先在聊天中创建项目和部署，可确保 Canvas 只连接到已存在的资源。 + +11. 选择 **+**，选择 **Terminal**，然后登录 Azure： + + ```bash + az login + ``` + +12. 检查所选订阅并列出其中的资源组： + + ```bash + az account show --output table + az group list --output table + ``` + + 如果订阅不正确，请运行 `az account set --subscription `，然后重新运行这两个命令。 + + 如果出现 `rg-tailspin-toys`，请检查其中的资源： + + ```bash + az resource list --resource-group rg-tailspin-toys --output table + ``` + + 如果该组包含无关或共享资源，请先停止操作，选择专用名称后再使用以下提示词。请将后续所有提示词和命令中的示例名称替换为已批准的名称。 +13. 在同一个议题会话中输入： + + ```plaintext + Use the Microsoft Foundry skill to create a resource group named rg-tailspin-toys and a Foundry project named tailspin-toys. + ``` + + ![创建 Foundry 项目](../../../_images/app-8-foundry-project-created.png) + +14. 要求 Copilot 推荐模型。由于会话从议题启动，议题的验收标准已包含在上下文中： + + ```plaintext + Use the Microsoft Foundry skill to recommend two or three current chat models in the tailspin-toys project that meet this issue's acceptance criteria. Explain the tradeoffs and wait for me to choose. + ``` + +15. 确认 Copilot 加载了 `microsoft-foundry` 技能，然后根据各模型的优缺点选择一个可用模型。Microsoft Foundry 托管代理快速入门目前使用 `gpt-5.4-mini`，但可用性和配额因区域而异。 + + ![选择模型](../../../_images/app-8-select-model.png) + +16. 要求 Copilot 部署所选模型，并在批准前审查目标项目和费用： + + ```plaintext + Deploy the model I selected to the tailspin-toys Foundry project, using the model name as the deployment name. + ``` + +> [!TIP] +> 模型的可用性会随时间变化。应选择 Copilot 确认在项目中可用的模型，而不是本模块中固定指定的某个模型。 + +## 在 Canvas 中验证模型并进行冒烟测试 + +此检查在尚无代理代码时验证项目和模型。模型冒烟测试不能替代模块 2 中验证托管代理回答是否以目录为依据的测试。 + +17. 选择 **+**，然后选择 **Canvas**，再选择 **Microsoft Foundry (Preview)**。 +18. 打开 Canvas 右上角的 **More options** 菜单，然后选择 **Sign in**。 +19. 选择 **tailspin-toys** Foundry 项目。展开 **Models**，确认部署已显示，且名称和状态符合预期。 + + ![在 Canvas 中验证项目和模型](../../../_images/app-8-validate-project-model.png) + +20. 在同一会话中输入： + + ```plaintext + 使用 Microsoft Foundry 技能直接测试我在 tailspin-toys 项目中部署的模型，不要创建代理。根据 @db/catalog.json 中的内容回答以下问题：“我喜欢以追踪 bug 为主题的益智游戏。我应该支持哪个游戏？它筹集了多少资金？”显示回答，并且仅在可以获取时显示所用 token 数和响应时间等有用的元数据。使用我现有的 Azure 登录身份。不要显示凭据、修改文件或创建资源。 + ``` + +21. 检查回答。回答应仅推荐 `db/catalog.json` 中实际存在的游戏，使用正确的标题、发行商和评分，并说明没有可用的筹款信息。如果模型编造游戏、目录详情或筹款金额，请在继续之前比较另一个推荐模型。 + +> [!NOTE] +> 重新打开 Canvas 时，它会记住所选项目。其阶段包括：用于生成初始框架的 **Create new hosted agents**；用于连接模型、工具箱、技能和防护措施的 **Build current hosted agent**；以及用于本地运行和部署到 Microsoft Foundry 的 **Deploy and test**。 + +## 检查点与后续步骤 + +你已准备好 Azure 工具、导出目录，并根据 Backer Concierge 的依据规则测试了部署的模型。本模块的检查点是一个能够推荐目录中实际存在的游戏且不会编造缺失信息的模型。 + +接下来，你将使用同一个 Tailspin Toys 存储库、工作树分支、关联议题的会话、Foundry 项目和所选模型部署来[构建并部署代理][next-module]。如果在此停止，请[清理 Azure 资源][cleanup]以免继续产生费用。 + +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azure-cli]: https://learn.microsoft.com/cli/azure/install-azure-cli +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[next-module]: ../2-build-and-deploy/ +[cleanup]: ../#清理资源 diff --git a/docs/zh-cn/app/8-foundry-canvas/2-build-and-deploy.md b/docs/zh-cn/app/8-foundry-canvas/2-build-and-deploy.md new file mode 100644 index 00000000..e9e4a72c --- /dev/null +++ b/docs/zh-cn/app/8-foundry-canvas/2-build-and-deploy.md @@ -0,0 +1,160 @@ +--- +title: "构建并部署代理" +description: "在 Canvas 中生成 Backer Concierge 的初始框架，在本地检查，然后在 Foundry 中部署并重新测试。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/1-project-and-model/ + label: 准备项目和模型 +next: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/3-connect-to-site/ + label: 将代理连接到网站 +--- + +本模块将使用 Microsoft Foundry Canvas，把[准备项目和模型][previous-module]中创建的项目、模型部署和目录转变为托管的 Backer Concierge。 + +完成本模块后，将获得： + +- 一个已生成初始框架的代理，包含打包的目录数据和针对性测试。 +- 针对每项目录和对话验收标准的本地验证证据。 +- 一个已部署并在 Foundry 中重新测试的代理版本。 + +## 场景 + +Tailspin Toys 需要一个能够回答实际目录问题、承认信息缺失，并记住对话中讨论过的游戏的助手。在成为游戏商店的一部分之前，这项服务必须先证明自身可靠。 + +## 准备部署工具 + +托管代理的检查和部署通过 Canvas 使用 Azure Developer CLI 完成；继续使用已有的 Foundry 项目和模型。 + +1. 返回模块 1 中关联 **Add a Backer Concierge assistant for catalog questions** 议题的同一会话。确认 `db/catalog.json` 完好、已连接到正确的订阅和 Foundry 项目，并且模型部署仍然存在。如果已清理资源，请先重新完成相关的[项目和模型设置][previous-module]。 + +2. 选择 **+**，选择 **Terminal**，然后登录 Azure Developer CLI，并在出现提示时在浏览器中完成身份验证： + + ```bash + azd auth login + ``` + +3. 运行 `azd config show` 验证 Azure 订阅。如果为空或不正确，请使用 `azd config set defaults.subscription ` 更新，然后再次运行 `azd config show` 确认更改。 +## 生成 Backer Concierge 的初始框架 + +Canvas 会生成代码、文件夹结构以及根目录下的 `azure.yaml`，将 Backer Concierge 连接到已有的模型部署。 + +4. 在 **Create new hosted agents** 预览界面中输入： + + ```plaintext + Scaffold a hosted agent named Backer Concierge in agent/backer-concierge, connected to the tailspin-toys project and the model deployment I just confirmed. Use Microsoft Agent Framework with the Responses API. Ground it in db/catalog.json and ensure it meets the acceptance criteria in this issue. Keep a single azure.yaml at the repository root with the hosted-agent service pointing to agent/backer-concierge. Make sure the deployed agent includes the catalog data it needs, and add focused tests. + ``` + + Canvas 会将提示词以及当前订阅和 Foundry 项目的上下文发送给 Copilot。它会查找 Agent Framework + Responses API 示例；可能会出现 **Agent with Local Tools (Responses, Agent Framework, Python)** 等选项。 + + ![在 Canvas 中生成 Backer Concierge 代理的初始框架](../../../_images/app-8-scaffold-backer-concierge.png) + +5. 在 **Files** 选项卡中，按照以下检查点审查 Copilot 的更改。`src` 中生成的文件名可能不同，但项目边界和 `azure.yaml` 位置应符合以下要求： + + - 代理位于 `agent/backer-concierge`。 + - 存储库根目录中只有一个 `azure.yaml`，其中包含使用 `host: azure.ai.agent` 的服务。 + - 可部署的代理包含为其生成的目录副本。 + - 针对性测试覆盖回答必须以目录为依据的要求。 + - 不包含凭据或本地环境文件。 + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +6. 要求 Copilot 运行针对性测试并修复所有失败项，然后再继续到 **Deploy and test**。 + +## 在本地检查代理 + +**Inspect Locally** 会在 Copilot 集成终端中运行 `azd ai agent run`，等待托管代理启动，然后打开嵌入式 Agent Inspector。 + +7. 在 **Deploy and test** 中选择 **Inspect Locally**，然后等待 Agent Inspector 打开。 + +> [!NOTE] +> 首次本地运行时，`azd` 需要创建环境并安装依赖项，可能耗时几分钟。 + +8. 如果检查器无法连接，请确认没有其他进程占用所需端口，将错误发送给 Copilot，并在修复后重试。 +9. 在 Agent Inspector 中测试**以目录为依据的推荐**： + + ```text + I love puzzle games about tracking down bugs. What should I back? + ``` + + 预期结果：只提及目录中真实存在的游戏名称，并使用每款游戏的正确信息。 + + ![Agent Inspector 中以目录为依据的推荐](../../../_images/app-8-grounded-recommendation.png) + +10. 测试**幻觉陷阱**： + + ```text + How much has Pipeline Conquest raised so far, and how many backers does it have? + ``` + + 预期结果：说明目录不记录筹款或支持者信息，然后提供目录中确实存在的信息。 + +11. 测试**目录外问题施压**： + + ```text + Do you have Wingspan? If not, what's the closest thing you've got? + ``` + + 预期结果：说明目录中没有 Wingspan，不使用外部知识介绍它，并转而推荐真实存在的 Tailspin 游戏。 + +12. 测试**模糊请求**： + + ```text + Recommend me something good. + ``` + + 预期结果：提出一个简短的澄清问题，暂不推荐具体游戏。 + +13. 测试**排名准确性**： + + ```text + What are your three highest rated games? + ``` + + 预期结果：按正确顺序返回目录中评分最高的三个条目，并给出正确评分。 + +14. 在同一段对话中发送以下提示词，测试**对话连续性**： + + ```text + Show me two highly rated strategy games. + ``` + + ```text + Which of those has the higher rating? + ``` + + 预期结果：第二次回答只涉及第一次回答中的两款游戏，并正确比较它们在目录中的评分。 + +15. 将每次回答与 `db/catalog.json` 和议题的验收标准对比。确认代理绝不编造游戏、发行商、评分、筹款总额、支持者人数、价格、玩家人数、游戏时长或发布日期。如果 Agent Inspector 报错，或回答超出了目录依据的范围，请将结果复制到 Canvas 的提示词区域，并要求 Copilot 修复。每次更改后都要重新启动本地检查并重跑失败的测试，然后确认全部六项检查通过，再进行部署。 + +## 部署并重新测试托管代理 + +Canvas 使用 `azd` 部署经过测试的代理。Foundry 会打包服务源代码、解析依赖项、远程构建，并将其发布到 Microsoft Foundry。 + +16. 在 Canvas 的 **Deploy and test** 中选择 **Deploy to Foundry**。审查自动填入聊天的提示词。 + + ![画布上的 Deploy to Foundry 提示词](../../../_images/app-8-deploy-to-foundry.png) + +17. 检查是否收到部署确认、代理版本、状态及 Foundry 中代理试验场的链接。如果部署失败，请将错误发送给 Copilot，在同一项目中解决问题后，再通过 Canvas 重试。 +18. 在 Canvas 中选择 **Test in Foundry Portal**，打开已部署代理的试验场。针对这个已部署版本，重新运行第 9–14 步中的全部六项验收检查；连续性检查中的两个提示词仍须在同一段对话中发送。将回答与目录对比；如果有任何检查失败，请要求 Copilot 修复，重新运行本地测试，通过 Canvas 重新部署，并再次测试托管版本。 + +## 检查点与后续步骤 + +你已生成 Backer Concierge 的初始框架，在本地测试其目录依据和对话行为，将其部署到 Microsoft Foundry，并重新测试了托管版本。本模块的检查点是一个能够通过全部六项验收检查且不会编造缺失信息的托管代理。 + +接下来，你将使用同一个 Tailspin Toys 存储库、工作树分支、关联议题的会话、Foundry 项目、所选模型部署和托管代理来[将代理连接到网站][next-module]。如果在此停止，请[清理 Azure 资源][cleanup]以免继续产生费用。 + +[previous-module]: ../1-project-and-model/ +[next-module]: ../3-connect-to-site/ +[cleanup]: ../#清理资源 diff --git a/docs/zh-cn/app/8-foundry-canvas/3-connect-to-site.md b/docs/zh-cn/app/8-foundry-canvas/3-connect-to-site.md new file mode 100644 index 00000000..31a9abde --- /dev/null +++ b/docs/zh-cn/app/8-foundry-canvas/3-connect-to-site.md @@ -0,0 +1,92 @@ +--- +title: "将代理连接到网站" +description: "通过保护凭据的本地代理服务集成托管的 Backer Concierge，并对聊天组件进行端到端测试。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/2-build-and-deploy/ + label: 构建并部署代理 +next: + link: /copilot-workshops/zh-cn/app/9-review/ + label: 回顾与后续步骤 +--- + +最后一个模块将把[构建并部署代理][previous-module]中经过测试的托管代理连接到本地运行的 Tailspin Toys 网站。 + +完成本模块后，将获得： + +- 一个保护 Foundry 凭据和对话标识符的本地 Azure Functions 代理服务。 +- 一个支持无障碍访问、且端到端行为经过验证的聊天组件。 +- 一项经过本地验证的集成，以及一个资源清理检查点。 + +## 场景 + +Tailspin Toys 的支持者需要在浏览游戏时获得基于目录的建议。Backer Concierge 应保留对话、支持键盘导航，并明确处理信息不可用的情况和错误。在提供这些便利的同时，不能向浏览器暴露服务凭据或内部对话详情。 + +## 从托管代理检查点继续 + +集成使用已有的托管代理，不创建新的 Foundry 资源。 + +1. 返回前面模块中的同一个 Tailspin Toys 存储库、工作树分支和 **Add a Backer Concierge assistant for catalog questions** 议题会话。确认根目录下的 `azure.yaml`、代理源代码和目录均存在，并检查已记录的订阅、专用资源组、Foundry 项目、模型部署及经过测试的托管代理版本。 +2. 如果已清理资源，请在集成前恢复相关的[项目和模型][project-module]以及[经过测试的托管部署][previous-module]。 + +## 构建服务器端代理服务 + +Tailspin Toys 完全采用预渲染。浏览器代码绝不能直接调用托管代理，也不能接收 Foundry 凭据。本地 Azure Functions **服务器端凭据边界**负责向 Foundry 进行身份验证，并且只向浏览器返回代理的回答。浏览器发送每条消息时附带一个不透明的对话句柄；代理服务将该句柄映射到 Foundry 对话，而不暴露底层标识符。 + +代理服务是唯一允许访问 Azure 凭据的代码。在本研讨会中，Function 和网站在本地运行，Astro 开发服务器会将 `/api` 请求转发到 Function。 + +> [!IMPORTANT] +> 此研讨会代理服务仅用于本地开发，绝不能部署为匿名公共端点。生产环境集成需要针对具体应用设计身份验证和滥用防范机制，包括适当的速率限制或配额、CORS 限制、监控和费用控制。 + +3. 在同一个 Copilot 会话中输入： + + ```plaintext + Add a local Azure Functions proxy in api for the static Astro site to call my deployed Backer Concierge during development. Use my existing local Azure sign-in, keep credentials and Foundry conversation identifiers out of the browser, return an opaque conversation handle, validate requests, sanitize errors, and add focused tests. Configure the Astro development server so /api requests reach the local Function. Don't create public deployment infrastructure. + ``` + +4. 审查生成的代理服务及针对性测试，检查请求验证、错误信息脱敏、不透明对话句柄和仅限服务器端的凭据边界。要求 Copilot 运行针对性测试并修复所有失败项。 +5. 打开另一个终端，使用 Copilot 提供的命令启动本地 Function，并保持其运行。 +6. 返回聊天，要求 Copilot 测试本地代理服务： + + ```plaintext + Test the local /api/concierge endpoint by asking "Which games are under $30?" Show me the sanitized response and confirm that no credentials or internal conversation identifiers are returned. + ``` + +7. 检查响应：它应说明目录不包含价格。确认其中没有 Foundry 令牌、凭据、内部对话标识符、项目端点或堆栈跟踪。如果无法访问 Function，或响应泄露了详情或编造了价格，请将脱敏后的失败信息发送给 Copilot，修复问题，并在继续前重新运行代理服务测试。 + + ![本地代理服务测试](../../../_images/app-8-local-proxy-test.png) + +## 构建并测试聊天组件 + +代理服务运行后，聊天组件可在网站上展示对话，而不暴露 Foundry 详情。 + +8. 要求 Copilot 创建网站集成： + + ```plaintext + 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, keep Foundry details out of the browser, and add end-to-end tests covering the chat flow, conversation continuity, accessibility, error handling, and grounding boundaries. + ``` + +9. 在另一个终端中使用 Copilot 提供的命令启动 Astro 开发服务器。保持网站和本地 Function 同时运行。 +10. 要求 Copilot 运行端到端测试： + + ```plaintext + Run the end-to-end tests for the Backer Concierge widget in the Tailspin Toys site. Verify its core chat flow, conversation continuity, accessibility, error handling, grounding boundaries, and secure use of the local proxy. Report the results and include evidence for any failures. + ``` + +11. 审查报告，并在浏览器中验证报告所描述的行为，包括键盘操作以及[托管代理验收检查][agent-checks]中的两轮对话。确认浏览器请求携带不透明句柄，通过 `/api/concierge` 发送，而不是直接发送到 Foundry；响应也不暴露凭据或 Foundry 内部标识符。检查推荐和信息缺失时的回答是否保持在目录范围内。与 Copilot 一起解决失败的测试，必要时重启受影响的本地服务，然后重新运行测试。 + + ![Backer Concierge 聊天组件的端到端测试结果](../../../_images/app-8-e2e-test-results.png) + +## 检查点与后续步骤 + +你已构建一个保护凭据的本地代理服务，连接支持无障碍访问的聊天组件，并针对托管的 Backer Concierge 验证了完整的对话流程。本模块的检查点是一个经过本地测试的网站集成，它能遵守目录边界，并且不会向浏览器暴露凭据或 Foundry 内部标识符。这并不代表代理服务或网站已部署到生产环境。 + +结束实验后，停止两个本地服务并[清理 Azure 资源][cleanup]。然后沿核心研讨会学习路径继续学习[回顾与后续步骤][core-review]。 + +[previous-module]: ../2-build-and-deploy/ +[project-module]: ../1-project-and-model/ +[agent-checks]: ../2-build-and-deploy/#在本地检查代理 +[cleanup]: ../#清理资源 +[core-review]: ../../9-review/ diff --git a/docs/zh-cn/app/8-foundry-canvas/README.md b/docs/zh-cn/app/8-foundry-canvas/README.md new file mode 100644 index 00000000..f3dade3e --- /dev/null +++ b/docs/zh-cn/app/8-foundry-canvas/README.md @@ -0,0 +1,90 @@ +--- +title: "可选：集成 Foundry" +slug: zh-cn/app/8-foundry-canvas +description: "使用 Microsoft Foundry Canvas 构建以目录为依据的 Backer Concierge，并在各阶段设置可安全暂停的位置。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +prev: + link: /copilot-workshops/zh-cn/app/9-review/ + label: 回顾与后续步骤 +next: + link: /copilot-workshops/zh-cn/app/8-foundry-canvas/1-project-and-model/ + label: 准备项目和模型 +--- + +在这一可选学习流程中，将使用 GitHub Copilot app 中的 Microsoft Foundry Canvas，为 Tailspin Toys 添加 **Backer Concierge**。整个流程从以目录为依据的模型实验开始，逐步构建托管代理，最后集成到本地网站。 + +## 学习流程 + +每个模块最后都设有检查点，可在此安全暂停。整个流程始终使用同一个 Tailspin Toys 存储库、工作树分支、关联议题的会话、Foundry 项目和模型部署。 + +- [准备项目和模型][module-1]：明确回答所依据的目录数据范围，创建项目和模型部署，并在 Canvas 中检查。 +- [构建并部署代理][module-2]：生成 Backer Concierge 的初始框架，在本地测试，然后部署并重新测试托管代理。 +- [将代理连接到网站][module-3]：添加保护凭据的本地代理服务、支持无障碍访问的聊天组件和端到端测试。 + +> [!IMPORTANT] +> Microsoft Foundry Canvas 和托管代理目前处于公开预览阶段。 +> +> 此流程会创建计费的 Azure 资源，包括模型部署，以及从模块 2 开始创建的托管代理。创建资源之前，必须确认订阅、区域、配额和预计费用并获得批准。即使只完成项目和模型阶段就停止，也需要清理资源。 + +1. 从[准备项目和模型][module-1]开始，所有操作都应在自己的 Tailspin Toys 存储库中完成，而不是在本研讨会的内容存储库中。 +2. 如果你想先完成核心研讨会，请继续前往[回顾和后续步骤][core-review]。 + +## 清理资源 + +在任一检查点结束实验后，请删除 Azure 资源以免产生不必要的费用。清理会删除后续模块所需的资源，因此之后继续时需要重新创建这些资源。 + +> [!WARNING] +> 仅当 `rg-tailspin-toys` 专用于本练习且不包含需要保留的资源时，才能将其删除。删除共享资源组也会删除无关资源。 +> +> 如果在模块 1 中批准了其他资源组名称，请在以下所有命令中使用该名称替换 `rg-tailspin-toys`。 + +1. 在相应终端中停止自己启动的本地 Agent Inspector、Azure Function 或 Astro 开发服务器。 +2. 如果在模块 2 或 3 中部署了托管代理，请在同一个 Tailspin Toys 工作树中打开终端，使用相同的 `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 + ``` + +## 资源 + +Microsoft 文档介绍了 Canvas、托管部署及其权限。 + +- [什么是 Microsoft Foundry Canvas？][foundry-canvas] +- [使用 Foundry Canvas 部署第一个托管代理][hosted-agent-quickstart] +- [托管代理权限][hosted-agent-permissions] + +[module-1]: ./1-project-and-model/ +[module-2]: ./2-build-and-deploy/ +[module-3]: ./3-connect-to-site/ +[core-review]: ../9-review/ +[foundry-canvas]: https://learn.microsoft.com/azure/foundry/agents/concepts/foundry-canvas +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=canvas +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/zh-cn/app/9-review.md b/docs/zh-cn/app/9-review.md index 350ceae6..6e9507f8 100644 --- a/docs/zh-cn/app/9-review.md +++ b/docs/zh-cn/app/9-review.md @@ -4,6 +4,7 @@ description: "回顾 GitHub Copilot app 学习路径，自动执行重复性工 authors: - geektrainer lastUpdated: 2026-07-09 +next: false --- 在过去几节课程中，你使用 GitHub Copilot app 将一项功能从构想推进到合并，包括： @@ -62,6 +63,8 @@ lastUpdated: 2026-07-09 要探索 GitHub Copilot 生态系统的更多内容，请查看 [VS Code 学习路径](../../vscode/)、[Copilot CLI 学习路径](../../cli/)或 [Cloud agent 学习路径](../../cloud/)。 +如果想通过 Microsoft Foundry Canvas 进行可选扩展，可继续探索[可选：集成 Foundry][foundry-canvas]。 + ## 资源 - [关于 GitHub Copilot app][about-copilot-app] @@ -80,4 +83,5 @@ lastUpdated: 2026-07-09 [chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models -[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links \ No newline at end of file +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links +[foundry-canvas]: ../8-foundry-canvas/ \ No newline at end of file diff --git a/docs/zh-cn/app/README.md b/docs/zh-cn/app/README.md index a32e3a69..0ec99a89 100644 --- a/docs/zh-cn/app/README.md +++ b/docs/zh-cn/app/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 [**GitHub Copilot app**](https://docs.github.com/copilot/concepts/agents/github-copilot-app) 是一款基于 Copilot CLI 构建的桌面应用，可将智能体驱动的开发集中到一个专注的工作区。它支持并行智能体会话、可切换的会话模式、共享画布，以及原生的 GitHub 议题和拉取请求管理功能。其中包括 **Agent Merge**，可处理拉取请求的变基、审查反馈、CI 修复与合并。 -在这些课程中，你将安装应用并设置项目，然后熟悉应用工作区和模板为你创建的待办事项。你会先完成一项小改动，即添加星级评分；再根据议题添加自定义指令标准，在隔离的智能体会话中构建筛选功能，并使用可复用技能进行验证。随后，你将添加 Playwright MCP 服务器，在真实浏览器中探索该功能，并逐步提高合并自动化程度，最终由 **Agent Merge** 合并拉取请求。最后，你将通过共享画布协作，可选择使用 Microsoft Foundry Canvas 构建托管智能体，并自动执行重复性工作，完整体验从构想到功能合并的流程。 +在这些课程中，你将安装应用并设置项目，然后熟悉应用工作区和模板为你创建的待办事项。你会先完成一项小改动，即添加星级评分；再根据议题添加自定义指令标准，在隔离的智能体会话中构建筛选功能，并使用可复用技能进行验证。随后，你将添加 Playwright MCP 服务器，在真实浏览器中探索该功能，并逐步提高合并自动化程度，最终由 **Agent Merge** 合并拉取请求。最后，你将通过共享画布协作，并自动执行重复性工作，完整体验从构想到功能合并的流程。此外，还有一项包含三个模块的可选扩展，使用 Microsoft Foundry Canvas 准备项目和模型、构建并部署代理，再将其连接到网站。 ## 课程 @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. 使用 Playwright MCP 测试][ex5] | 外部工具 | 添加 Playwright MCP 服务器，并在浏览器中探索功能 | | [6. 使用 Agent Merge 合并][ex6] | 合并 | 让 Agent Merge 修复并合并筛选功能的拉取请求 | | [7. 使用画布规划][ex7] | 协作 | 创建共享画布来规划和跟踪工作 | -| [8. 构建 Backer Concierge 智能体（可选）][foundry-canvas] | AI 智能体 | 构建、测试、部署并集成基于目录的托管智能体 | | [9. 回顾与后续步骤][ex9] | 总结 | 自动执行重复性任务，并探索后续内容 | +| [可选：集成 Foundry][foundry-canvas] | AI 代理 | 准备项目和模型，构建并部署以目录为依据的代理，再将其连接到网站 | ## 先决条件 diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 1f624004..7b4a6924 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -92,8 +92,56 @@ export default defineConfig({ { label: '5. Testing with Playwright MCP', link: '/app/5-mcp-playwright/' }, { label: '6. Merging with Agent Merge', link: '/app/6-agent-merge/' }, { label: '7. Planning with canvases', link: '/app/7-canvases/' }, - { label: '8. Build a Backer Concierge Agent (Optional)', link: '/app/8-foundry-canvas/' }, { label: '9. Review', link: '/app/9-review/' }, + { + 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: '/app/8-foundry-canvas/', + }, + { + label: '1. Prepare the project and model', + link: '/app/8-foundry-canvas/1-project-and-model/', + translations: { + 'es-ES': '1. Preparar el proyecto y el modelo', + 'ja-JP': '1. プロジェクトとモデルを準備する', + 'ko-KR': '1. 프로젝트와 모델 준비', + 'pt-BR': '1. Preparar o projeto e o modelo', + 'zh-CN': '1. 准备项目和模型', + }, + }, + { + label: '2. Build and deploy the agent', + link: '/app/8-foundry-canvas/2-build-and-deploy/', + translations: { + 'es-ES': '2. Crear e implementar el agente', + 'ja-JP': '2. エージェントを構築してデプロイする', + 'ko-KR': '2. 에이전트 빌드 및 배포', + 'pt-BR': '2. Criar e implantar o agente', + 'zh-CN': '2. 构建并部署代理', + }, + }, + { + label: '3. Connect the agent to the site', + link: '/app/8-foundry-canvas/3-connect-to-site/', + translations: { + 'es-ES': '3. Conectar el agente al sitio', + 'ja-JP': '3. エージェントをサイトに接続する', + 'ko-KR': '3. 에이전트를 사이트에 연결', + 'pt-BR': '3. Conectar o agente ao site', + 'zh-CN': '3. 将代理连接到网站', + }, + }, + ], + }, ], }, {