diff --git a/AUTHORING.md b/AUTHORING.md index fd226b81..a3606579 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -12,7 +12,7 @@ This is the entry point for **content authors and maintainers** of **Copilot Wor copilot-workshops/ ├── docs/ ← Markdown source. EDIT HERE. Browsable on github.com. │ ├── README.md ← Workshop landing page (also site home via slug: index) -│ ├── cli/ ← Copilot CLI lessons (0-prerequisites.md + numbered exercises) +│ ├── cli/ ← Copilot CLI lessons, including the optional 8-foundry-agent/ series │ ├── vscode/ ← VS Code lessons (0-prerequisites.md + numbered exercises) │ ├── cloud/ ← Cloud agent lessons (0-prerequisites.md + numbered exercises) │ ├── app/ ← GitHub Copilot app lessons (setup folded into Exercise 1) @@ -85,6 +85,12 @@ Every folder's landing page is a `README.md` so it renders directly when someone 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. +### Optional multi-module series + +An optional series can live in a lesson subfolder, such as `docs/cli/8-foundry-agent/`, with a `README.md` overview and numbered module files. The overview uses `slug: cli/8-foundry-agent` to preserve the series entry URL. The sidebar groups its overview and modules under the optional series title, after the core workshop's review lesson. + +Each module has its own objectives, story-focused scenario, numbered instructions, completion checkpoint, and next-module handoff. Shared cleanup instructions live on the overview and are linked from every module so learners can stop at any checkpoint. When moving a lesson into a subfolder, adjust image paths and navigation links for the extra directory level, and keep existing localized entry links aligned; missing module translations use the site's English fallback. + ### Add an image 1. **Drop the file** in `docs/_images/` (or a path-scoped `cli/_images/` etc. when the image is path-specific). Use lowercase-with-hyphens filenames; prefix with `shared-` if the image is referenced from multiple harnesses. diff --git a/docs/cli/7-slash-commands.md b/docs/cli/7-slash-commands.md index be354f12..57ed3854 100644 --- a/docs/cli/7-slash-commands.md +++ b/docs/cli/7-slash-commands.md @@ -141,7 +141,7 @@ Using slash commands in Copilot CLI allows you to configure it, share sessions, - `/model` to explore the list of available models and select a new one if you so desire. - Learned about `/delegate` as an optional bridge to cloud agent. -There are of course more slash commands available, and more to explore with Copilot CLI! If you want to go further, the [optional Microsoft Foundry lesson][foundry-lesson] walks through building a hosted agent on top of the Tailspin catalog. Otherwise, let's close out our journey by [reviewing what we've learned][next-lesson] and some next steps to continue learning. +There are of course more slash commands available, and more to explore with Copilot CLI! Let's close out our journey by [reviewing what we've learned][next-lesson] and some next steps to continue learning. If you'd like an optional challenge before wrapping up, [build a concierge with GitHub Copilot CLI and Foundry][foundry-lesson] in a three-module series. ## Resources diff --git a/docs/cli/8-foundry-agent.md b/docs/cli/8-foundry-agent.md deleted file mode 100644 index afb0f303..00000000 --- a/docs/cli/8-foundry-agent.md +++ /dev/null @@ -1,433 +0,0 @@ ---- -title: "Exercise 8 - (Optional) Build a Backer Concierge AI Agent" -description: "Use GitHub Copilot CLI and the Microsoft Foundry Skill to create, test, deploy, and integrate a catalog-grounded hosted agent." -authors: - - juliamuiruri4 -lastUpdated: 2026-09-09 ---- - -In this optional lesson, you'll take the Tailspin catalog and build an AI agent on top of it. You'll use GitHub Copilot CLI to set up your own Microsoft Foundry project, choose and deploy a model, scaffold and test the agent, deploy it as a hosted agent, and connect it to the Tailspin Toys website. - -In this lesson, you will: - -- install the Azure Skills Plugin for GitHub Copilot CLI. -- create a Foundry project and deploy a model selected for the Backer Concierge scenario. -- scaffold, configure, and test a hosted agent from the terminal. -- deploy the agent to Microsoft Foundry. -- connect the hosted agent to the Tailspin Toys website. - -> [!IMPORTANT] -> Microsoft Foundry 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 - -Before you start, make sure you have: - -1. An Azure subscription. - - - [Free Azure subscription with $200 credit][azure-free] - - [Azure for Students with $100 credit][azure-students] - -1. Install the Azure CLI in the dev container: - - ```bash - curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash - az version - ``` - - Sign in to Azure CLI with `az login` and ensure you are using the correct subscription with `az account show` - -1. Install the [Azure Developer CLI][install-azd] version 1.27.1 or later. Microsoft Foundry uses `azd` to test and deploy hosted agents. - - ```bash - curl -sL https://aka.ms/install-azd.sh | bash - azd version - ``` - - Sign in to Azure Developer CLI with `azd auth login` and ensure you are using the correct subscription with `azd config show` - -1. Install the Azure Developer CLI (azd) Foundry extensions - - ```bash - azd ext install microsoft.foundry - ``` - -1. Install the [Azure Skills Plugin][azure-skills] which adds Azure skills, Azure MCP Server, and Foundry MCP Server to GitHub Copilot CLI. - - - Open a new Copilot CLI session to the side from the command palette. Press Command+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux), then select **Chat: New Copilot CLI session to the side**. - - - Add the Azure Skills marketplace. You only need to do this the first time you install the plugin: - - ```text - /plugin marketplace add microsoft/azure-skills - ``` - - - Install the Azure plugin: - - ```text - /plugin install azure@azure-skills - ``` - - - Confirm that the plugin configured the Azure MCP server: - - ```text - /mcp list - ``` - -The skills teach Copilot the workflow, while the MCP servers let it inspect and work with your Azure resources. - -> [!TIP] -> If the skills or MCP servers don't appear, try `/skills reload` or `/restart` - -## 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. - -The previous exercises may have created and pushed other feature branches. Start this optional lesson from an up-to-date `main` branch so the agent work stays separate. - -```bash -git checkout main -git pull -git checkout -b foundry-agent-cli -``` - -## Generate the catalog export - -The agent needs the catalog as a file it can read. The Tailspin Toys sample includes a tested export script for this purpose. - -In Copilot CLI, enter: - -```text -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 -``` - -![Summary of the catalog export](../_images/cli-8-export-db-catalog.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. It also has no price, player count, or play-time fields. Those omissions define the boundary your agent must respect. - -## Plan the Foundry work - -Before Copilot creates any Azure resources or changes the repository, use plan mode to make the intended workflow visible. - -1. Enter the following prompt: - - ```text - /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. - ``` - -1. Review the proposed plan. Confirm that Copilot intends to use the `microsoft-foundry` skill and that it separates the hosted agent from the existing Astro application. - - If you note anything concerning or unexpected in the proposed plan, request revisions before proceeding. - -1. Leave plan mode after you are satisfied with the approach. - -## Set up a Foundry project and model - -The agent needs a Foundry project and a deployed model. Use the Microsoft Foundry Skill to select them from live availability and quota within your subscription. - -1. Ask Copilot to create the project: - - ```text - Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. - ``` - - ![Create a public Foundry project](../_images/cli-8-create-foundry-project.png) - -1. After the project is ready, ask Copilot to recommend a model: - - ```text - Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. - ``` - - Copilot may prompt you to select a model from the recommended options. - - ![Select a model from the recommended options](../_images/cli-8-select-foundry-model.png) - - We'll continue with `gpt-5.4-mini` in the remaining steps, but availability and quota vary by region. - -1. Ask Copilot to deploy your selection. *Insert your selection*: - - ```text - Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. - ``` - - ![Deploy the selected model](../_images/cli-8-deploy-foundry-model.png) - -> [!TIP] -> Model availability changes over time. Use the model that Copilot confirms is available in your project rather than substituting a hardcoded model. - -## Test the deployed model - -You deployed the model based on Copilot's recommendation. Before building the hosted agent, test whether the model follows the Backer Concierge grounding rules. This tests the model with the intended instructions and catalog context before any agent code or configuration is involved. - -First, grant your signed-in account the **Foundry Project Manager** role for hosted-agent development (later in the workshop), and the **Cognitive Services OpenAI User** role for direct model inference. Replace `` with the Foundry account name reported when the project was created, then in a new terminal, run: - -Set the account, project, and user values: - -```bash -SUBSCRIPTION_ID=$(az account show --query id --output tsv) -USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) -FOUNDRY_ACCOUNT="" -ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) -PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" -``` - -Assign the **Foundry Project Manager** role: - -```bash -az role assignment create \ - --assignee-object-id "$USER_OBJECT_ID" \ - --assignee-principal-type User \ - --role "Foundry Project Manager" \ - --scope "$PROJECT_SCOPE" \ - --subscription "$SUBSCRIPTION_ID" -``` - -Assign the **Cognitive Services OpenAI User** role: - -```bash -az role assignment create \ - --assignee-object-id "$USER_OBJECT_ID" \ - --assignee-principal-type User \ - --role "Cognitive Services OpenAI User" \ - --scope "$ACCOUNT_SCOPE" \ - --subscription "$SUBSCRIPTION_ID" -``` - -Back in Copilot CLI, enter: - -```text -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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. -``` - -![Foundry model response recommending a real catalog game and noting that funding data isn't available](../_images/cli-8-foundry-agent-response.png) - -The response should recommend only a real game from the catalog, use the correct catalog details, and explain that funding information isn't available. If the model invents a title, game details, or a funding total, compare another recommended model before continuing. - -> [!NOTE] -> This step tests only your deployed model with temporary instructions and catalog context. It doesn't test an agent. You will repeat the test after scaffolding to validate the hosted agent's code, packaging, and conversation behavior. - -## Scaffold the Backer Concierge Agent - -Now ask the Microsoft Foundry Skill to scaffold the hosted agent inside the existing Tailspin Toys repository. - -1. Enter the following prompt in Copilot CLI: - - ```text - Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. - - Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. - - Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. - ``` - -1. Follow the session for questions about the Foundry project, model deployment, agent name, or environment. - -1. When Copilot finishes, inspect the changes: - - ```text - /diff - ``` - - Confirm that: - - - `azure.yaml` contains a service with `host: azure.ai.agent`. - - the service points to `agent/backer-concierge` - - the deployed service package includes its own generated copy of the catalog. - - one script or build step refreshes that copy from `db/catalog.json` instead of maintaining two hand-edited catalogs. - - the agent uses the selected model deployment and the Responses API. - - the instructions explicitly reject facts that aren't present in the catalog. - - no credentials, access tokens, `.env` files, or `.azure` environment files are staged for commit. - - Use the following structure as the checkpoint after scaffolding: - - ```text - tailspin-toys/ - ├── azure.yaml - ├── agent/ - │ └── backer-concierge/ - │ ├── catalog.json - │ └── requirements.txt - ├── db/ - │ └── catalog.json - └── src/ - ``` - - > [!IMPORTANT] - > `azd deploy` packages the hosted-agent service directory. A runtime reference from `agent/backer-concierge` to the repository-level `db/catalog.json` can work locally and then fail after deployment. Verify that the generated copy is available in the `agent/backer-concierge/` directory before deployment. - -1. Ask Copilot to run the focused tests and inspect the generated configuration before starting the service: - - ```text - Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. - ``` - - Don't continue until the focused tests pass. - - ![Verify the agent scaffolding](../_images/cli-8-verify-generated-agent.png) - -## Test the agent locally - -The local agent service occupies its terminal while it runs. Keep Copilot CLI open in your current terminal and start the agent from a second terminal. - -1. Open another terminal by selecting Ctrl+\`. -2. From the Tailspin Toys repository root, run: - - ```bash - azd ai agent run - ``` - - The first local run creates a Python environment, installs dependencies, and starts the hosted agent. Leave this terminal running. - -3. Return to Copilot CLI in the first terminal and enter: - - ```text - Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. - - 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. - 2. "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 known information. - 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. - 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. - 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. - 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. - 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. - ``` - - If a test fails, (most likely due to prompt gaps), ask Copilot to fix only the local defect, run the focused tests, and tell you when to restart `azd ai agent run`. Restart the service and rerun the failed acceptance test after each change. - - > [!NOTE] - > If the agent can't connect, confirm that the second terminal is still running the service. - - ![Hosted Agent Deployment tests pass](../_images/cli-8-passing-acceptance-scenarios.png) - -## Deploy the hosted agent - -1. Stop the local service with Ctrl+C after all acceptance tests pass. -1. Return to Copilot CLI and enter: - - ```text - Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Foundry Agent Service, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" - ``` - - > [!NOTE] - > If prompted to select an evaluation suite source, choose **No, set it up later** - - ![Hosted Agent Deployment status and playground link](../_images/cli-8-hosted-agent-deployment.png) - -The playground link displayed allows you to interact with the deployed hosted agent on the Microsoft Foundry portal. - -The skill-led workflow uses `azd deploy` to package the service source, resolve dependencies, build it remotely, and publish it to Foundry Agent Service. It uses the Foundry invocation workflow to test the deployed endpoint. - -## 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. - -### Build the server-side proxy - -The `microsoft-foundry` skill owns the hosted-agent workflow, while the broader Azure skills in the same plugin can prepare the local Function project. - -1. In Copilot CLI, enter: - - ```text - Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. - - For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. - ``` - - ![Azure Functions local proxy setup](../_images/cli-8-azure-functions-proxy.png) - -1. Open another terminal, then start the local Function using the command provided by Copilot. Leave the Function running. - -1. Return to Copilot CLI and ask Copilot to test the local proxy: - - ```text - Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. - ``` - - The response should explain that the catalog doesn't contain prices. It must not contain a Foundry token, credential, project endpoint, raw Foundry conversation identifier, or stack trace. - - ![Sanitized JSON response from the local concierge endpoint](../_images/cli-8-sanitized-json-response.png) - -### Build the chat widget - -1. Ask Copilot to create the site integration: - - ```text - Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. - ``` - -1. Keep the local Function running and start the Astro site in another terminal using the command provided by Copilot. - -1. Return to Copilot CLI. The Playwright MCP server you added in [Exercise 4][playwright-lesson] is already available. Ask Copilot to test the widget: - - ```text - Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. - ``` - - ![Screenshot of the Backer Concierge widget in the Tailspin Toys site](../_images/cli-8-backer-concierge-widget.png) - -## Clean up your resources - -When you're done experimenting, remove the resources to avoid unwanted costs. - -1. Exit Copilot CLI and run: - - ```bash - azd down --purge - ``` - -1. 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: - -- installed the Azure and Microsoft Foundry Skills and used the tools from GitHub Copilot CLI. -- created a Foundry project and selected a model from the feature requirements and acceptance criteria. -- used the Microsoft Foundry Skill to scaffold and configure a hosted agent. -- tested grounding and conversation behavior through the local Responses API. -- deployed and tested 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 [Exercise 9 - Review and next steps][next-lesson]. - -## Resources - -- [Azure Skills Plugin][azure-skills] -- [Use the Microsoft Foundry Skill in coding agents][foundry-skill] -- [Deploy your first hosted agent with the Microsoft Foundry Skill][hosted-agent-quickstart] -- [Hosted agent permissions][hosted-agent-permissions] - ---- - -| [← Previous lesson: Slash commands][previous-lesson] | [Next lesson: Review and next steps →][next-lesson] | -| :-- | --: | - -[previous-lesson]: ../7-slash-commands/ -[next-lesson]: ../9-review/ -[playwright-lesson]: ../4-mcp/ -[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 -[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli -[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli -[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills -[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/cli/8-foundry-agent/1-project-and-model.md b/docs/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..93baa56e --- /dev/null +++ b/docs/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "Module 1 - Prepare the project and model" +description: "Set up Azure tools, export the Tailspin catalog, and select and test a Foundry model with GitHub Copilot CLI." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +This is the first module in [Optional: Incorporate Foundry][overview]. You'll prepare the tools and catalog, then use Copilot to create a Foundry project and test a deployed model before building the agent. + +In this module, you will: + +- install the Azure command-line tools and Azure Skills Plugin. +- export the catalog and plan the Foundry work. +- select, deploy, and test a model against the catalog's limits. + +## Scenario + +Tailspin Toys needs a concierge that can distinguish between catalog facts and information the company doesn't provide. A useful recommendation might name a highly rated puzzle game, but it must not invent that game's funding total. Before investing in a complete assistant, the team wants confidence that its chosen model can respect that boundary. + +## Prerequisites and setup + +You'll use Azure to host the Backer Concierge and Copilot CLI to guide the work. First, prepare the command-line tools and plugin that let Copilot work with your Azure resources. + +> [!IMPORTANT] +> The [cleanup instructions][cleanup] cover stopping after this module as well as finishing the series. + +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. Return to your Tailspin Toys codespace and open a terminal. +3. Install the Azure CLI in the dev container: + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. Sign in to Azure CLI with `az login` and ensure you are using the correct subscription with `az account show`. +5. Install the [Azure Developer CLI][install-azd] version 1.27.1 or later. Microsoft Foundry uses `azd` to test and deploy hosted agents. + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. Sign in to Azure Developer CLI with `azd auth login` and ensure you are using the correct subscription with `azd config show`. +7. Install the Azure Developer CLI (azd) Foundry extension: + + ```bash + azd ext install microsoft.foundry + ``` + +8. Open a new Copilot CLI session to the side from the command palette. Press Command+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux), then select **Chat: New Copilot CLI session to the side**. +9. Add the Azure Skills marketplace. You only need to do this the first time you install the plugin: + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. Install the [Azure Skills Plugin][azure-skills], which adds Azure skills, Azure MCP Server, and Foundry MCP Server to GitHub Copilot CLI: + + ```text + /plugin install azure@azure-skills + ``` + +11. Confirm that the plugin configured the Azure MCP server: + + ```text + /mcp list + ``` + +12. If the skills or MCP servers don't appear, try `/skills reload` or `/restart`, then check again. + +The skills teach Copilot the workflow, while the MCP servers let it inspect and work with your Azure resources. + +## Prepare your working branch + +The previous exercises may have created and pushed other feature branches. You'll start this optional series from an up-to-date `main` branch so the agent work stays separate. + +1. In your shell terminal, switch to `main`, pull the latest changes, and create a branch for the Backer Concierge: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## Generate the catalog export + +The agent needs the catalog as a file it can read. The Tailspin Toys sample includes a tested export script for this purpose. + +1. Return to Copilot CLI and enter: + + ```text + 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 + ``` + + ![Summary of the catalog export](../../_images/cli-8-export-db-catalog.png) + +2. Open `db/catalog.json`. Confirm that it contains 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. It also has no price, player count, or play-time fields. Those omissions define the boundary your agent must respect. + +## Plan the Foundry work + +Before Copilot creates any Azure resources or adds agent code, you'll use plan mode to make the intended workflow visible. + +1. Enter the following prompt: + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. Review the proposed plan. Confirm that Copilot intends to use the `microsoft-foundry` skill and that it separates the hosted agent from the existing Astro application. If you note anything concerning or unexpected, request revisions before proceeding. +3. Leave plan mode after you are satisfied with the approach. + +## Set up a Foundry project and model + +The agent needs a Foundry project and a deployed model. You'll use the Microsoft Foundry Skill to select them from live availability and quota within your subscription. + +1. Ask Copilot to create the project. Before approving resource creation, check the selected subscription, region, quota, and estimated cost: + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![Create a public Foundry project](../../_images/cli-8-create-foundry-project.png) + +2. After the project is ready, ask Copilot to recommend a model: + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + Copilot may prompt you to select a model from the recommended options. + + ![Select a model from the recommended options](../../_images/cli-8-select-foundry-model.png) + + We'll continue with `gpt-5.4-mini` in the remaining steps, but availability and quota vary by region. + +3. Select a model from the recommended options, then ask Copilot to deploy your selection. Review capacity and cost before approving deployment: + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![Deploy the selected model](../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> Model availability changes over time. The right choice is a model that Copilot confirms is available in your project, not a hardcoded model from an example. + +## Test the deployed model + +Before building the hosted agent, you'll test whether the model follows the Backer Concierge grounding rules. This uses the intended instructions and catalog context without any agent code or configuration. + +You'll first grant your signed-in account the **Foundry Project Manager** role for hosted-agent development in Module 2 and the **Cognitive Services OpenAI User** role for direct model inference. Then you'll ask a catalog question that also requests information the catalog doesn't contain. + +1. Open a new terminal and set the account, project, and user values. Replace `` with the Foundry account name reported when the project was created: + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. Assign the **Foundry Project Manager** role: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. Assign the **Cognitive Services OpenAI User** role: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. Return to Copilot CLI and enter: + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![Foundry model response recommending a real catalog game and noting that funding data isn't available](../../_images/cli-8-foundry-agent-response.png) + +5. Review the response. It should recommend only a real game from the catalog, use the correct catalog details, and explain that funding information isn't available. If the model invents a title, game details, or a funding total, compare another recommended model before continuing. + +> [!NOTE] +> This tests only your deployed model with temporary instructions and catalog context. It doesn't test an agent. Module 2 repeats the test after scaffolding to validate the hosted agent's code, packaging, and conversation behavior. + +## Summary 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 repository, `foundry-agent-cli` branch, Copilot CLI session, Foundry project, and selected model deployment to [build and deploy the agent][next-lesson]. If you're stopping here, [clean up your Azure resources][cleanup] to avoid ongoing costs. + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#clean-up-your-resources +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/cli/8-foundry-agent/2-build-and-deploy.md b/docs/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..3081801a --- /dev/null +++ b/docs/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "Module 2 - Build and deploy the agent" +description: "Use GitHub Copilot CLI and the Microsoft Foundry Skill to scaffold, test, and deploy the Backer Concierge." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +In [Module 1][previous-lesson], you prepared the catalog and tested a deployed model. This second module in the [optional concierge series][overview] turns that foundation into a hosted agent. + +In this module, you will: + +- scaffold the agent with its own deployable catalog copy. +- test grounding and conversation continuity locally. +- deploy the agent and invoke it remotely. + +## Scenario + +Tailspin Toys needs more than a one-off answer from a model. Backers expect the concierge to remember the games it just recommended and answer follow-up questions about them. The team also needs those answers to remain reliable when the concierge moves from a developer's machine to a hosted service. + +## Continue with your project + +This module builds on the working model from Module 1. You'll keep the same project and deployment rather than creating another set of Azure resources. + +1. Return to the Tailspin Toys repository on the `foundry-agent-cli` branch and your Copilot CLI session from Module 1. +2. Confirm that `db/catalog.json` is available and that you still have the Foundry project, selected model deployment, and Azure sign-in used for the model test. If you haven't completed that setup, finish [Prepare the project and model][previous-lesson] first. + +> [!IMPORTANT] +> Hosted agents are in public preview and create billable Azure resources. The [cleanup instructions][cleanup] apply if you stop after this module. + +## Scaffold the Backer Concierge agent + +You'll now ask the Microsoft Foundry Skill to scaffold the hosted agent inside the existing Tailspin Toys repository, then inspect its packaging and configuration before running it. + +1. Enter the following prompt in Copilot CLI: + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. Follow the session for questions about the Foundry project, model deployment, agent name, or environment. +3. When Copilot finishes, inspect the changes: + + ```text + /diff + ``` + + Confirm that: + + - `azure.yaml` contains a service with `host: azure.ai.agent`. + - the service points to `agent/backer-concierge`. + - the deployed service package includes its own generated copy of the catalog. + - one script or build step refreshes that copy from `db/catalog.json` instead of maintaining two hand-edited catalogs. + - the agent uses the selected model deployment and the Responses API. + - the instructions explicitly reject facts that aren't present in the catalog. + - no credentials, access tokens, `.env` files, or `.azure` environment files are staged for commit. + + Use the following structure as the checkpoint after scaffolding: + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy` packages the hosted-agent service directory. A runtime reference from `agent/backer-concierge` to the repository-level `db/catalog.json` can work locally and then fail after deployment. The generated copy must be available in the `agent/backer-concierge/` directory before deployment. + +4. Ask Copilot to run the focused tests and inspect the generated configuration before starting the service: + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + Don't continue until the focused tests pass. + + ![Verify the agent scaffolding](../../_images/cli-8-verify-generated-agent.png) + +## Test the agent locally + +You'll now check the agent's grounding and conversation behavior through its local Responses API. The local agent service occupies its terminal while it runs, so you'll keep Copilot CLI open in your current terminal and start the agent from a second terminal. + +1. Open another terminal by pressing Ctrl+\`. +2. From the Tailspin Toys repository root, run: + + ```bash + azd ai agent run + ``` + + The first local run creates a Python environment, installs dependencies, and starts the hosted agent. Leave this terminal running. + +3. Return to Copilot CLI in the first terminal and enter: + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![Hosted Agent Deployment tests pass](../../_images/cli-8-passing-acceptance-scenarios.png) + +4. Review the results. If the agent can't connect, confirm that the second terminal is still running the service. If a test fails, ask Copilot to fix only the local defect, run the focused tests, and tell you when to restart `azd ai agent run`. Restart the service and rerun the failed acceptance test after each change. + +## Deploy the hosted agent + +With the local acceptance tests passing, you're ready to deploy the agent to Microsoft Foundry. You'll use the same skill-led workflow to check deployment readiness and test the remote endpoint. + +1. Stop the local service with Ctrl+C after all acceptance tests pass. +2. Return to Copilot CLI and enter the following prompt. Review the proposed resources and estimated cost before approving deployment: + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. If prompted to select an evaluation suite source, choose **No, set it up later**. + + ![Hosted Agent Deployment status and playground link](../../_images/cli-8-hosted-agent-deployment.png) + +4. Review the deployment status and remote response. Confirm that the agent is running and recommends only real catalog games. If deployment or invocation fails, ask Copilot to diagnose the failure and repeat the remote test before continuing. + +The playground link displayed allows you to interact with the deployed hosted agent on the Microsoft Foundry portal. + +The skill-led workflow uses `azd deploy` to package the service source, resolve dependencies, build it remotely, and publish it to Microsoft Foundry. It uses the Foundry invocation workflow to test the deployed endpoint. + +## Summary and next steps + +You scaffolded an agent with a deployable catalog copy, tested grounding and conversation continuity, and verified a remote response from Microsoft Foundry. You now have a working hosted Backer Concierge. + +Next, you'll keep the same repository, branch, Copilot CLI session, and deployed agent to [connect the concierge to the website][next-lesson]. If a hosted agent is enough for your exploration, you can stop here and [clean up your Azure resources][cleanup]. + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#clean-up-your-resources diff --git a/docs/cli/8-foundry-agent/3-connect-to-site.md b/docs/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..3eeada38 --- /dev/null +++ b/docs/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "Module 3 - Connect the agent to the website" +description: "Connect the hosted Backer Concierge to Tailspin Toys through a local Azure Functions proxy and an accessible chat widget." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +In [Module 2][previous-lesson], you deployed and tested the Backer Concierge. This final module in the [optional concierge series][overview] makes that agent available through your local Tailspin Toys website. + +In this module, you will: + +- build a local Azure Functions proxy that keeps Foundry credentials on the server. +- add an accessible chat widget to the site. +- verify the complete conversation flow and clean up your resources. + +## Scenario + +Backers discover games on the Tailspin Toys website, not in a developer's terminal or an Azure portal. The team wants the concierge available alongside the catalog, with a chat experience that supports follow-up questions and protects the service's credentials. + +## Continue with your hosted agent + +The website integration needs the deployed agent from Module 2. You'll keep that agent running in Foundry while the proxy and website run locally. + +1. Return to the Tailspin Toys repository on the `foundry-agent-cli` branch and your existing Copilot CLI session. +2. Confirm that the Backer Concierge is deployed and that the remote invocation from [Build and deploy the agent][previous-lesson] passed. If you already removed the Azure resources, recreate them through the earlier modules before continuing. + +> [!IMPORTANT] +> The proxy and website in this module run locally; this is not a production website deployment. Your model and hosted agent remain billable Azure resources until you complete [cleanup][cleanup]. + +## Build the server-side proxy + +Tailspin Toys is fully pre-rendered. Browser code must never call the hosted agent directly or receive Foundry credentials. You'll add a local Azure Functions **server-side credential boundary** that authenticates to Foundry and returns only the agent response to the browser. + +The `microsoft-foundry` skill owns the hosted-agent workflow, while the broader Azure skills in the same plugin can prepare the local Function project. You'll use those skills to build the proxy, then check that it reaches the agent without exposing credentials. + +1. In Copilot CLI, enter: + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Azure Functions local proxy setup](../../_images/cli-8-azure-functions-proxy.png) + +2. Open another terminal, then start the local Function using the command provided by Copilot. Leave the Function running. +3. Return to Copilot CLI and ask Copilot to test the local proxy: + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. Inspect the response. It should explain that the catalog doesn't contain prices. It must not contain a Foundry token, credential, project endpoint, raw Foundry conversation identifier, or stack trace. + + ![Sanitized JSON response from the local concierge endpoint](../../_images/cli-8-sanitized-json-response.png) + +## Build the chat widget + +The proxy gives the browser a safe way to reach the concierge. You'll now add a chat widget to the site and use Playwright to check the complete conversation flow. + +1. Ask Copilot to create the site integration: + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. Keep the local Function running and start the Astro site in another terminal using the command provided by Copilot. +3. Return to Copilot CLI. The Playwright MCP server you added in [Exercise 4][playwright-lesson] is already available. Ask Copilot to test the widget: + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Screenshot of the Backer Concierge widget in the Tailspin Toys site](../../_images/cli-8-backer-concierge-widget.png) + +4. Review the results against the reported evidence. If any checks fail, ask Copilot to fix the relevant proxy or widget behavior and rerun the failed checks before finishing. + +## Clean up your resources + +You've reached the final checkpoint: a working concierge in your local website. The shared cleanup instructions cover both the local services and Azure resources created across the series. + +1. Complete [Clean up your resources][cleanup], including stopping the local services and verifying that Azure resource deletion finishes. + +## Summary and next steps + +You connected the hosted Backer Concierge to Tailspin Toys through a local server-side proxy and an accessible chat widget. Across the series, you used GitHub Copilot CLI and Foundry to prepare a model, build and deploy an agent, and verify a complete website integration. + +Continue to [Review and next steps][review] to close out the CLI workshop. + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#clean-up-your-resources diff --git a/docs/cli/8-foundry-agent/README.md b/docs/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..3440bfab --- /dev/null +++ b/docs/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: cli/8-foundry-agent +title: "Optional: Incorporate Foundry" +description: "A three-module series to prepare a model, build and deploy a catalog-grounded agent, and connect it to Tailspin Toys." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +This optional series uses GitHub Copilot CLI and the Microsoft Foundry Skill to turn the Tailspin Toys catalog into a conversational assistant. The three modules take you from project and model setup to a hosted agent and a working website integration. + +In this series, you will: + +- prepare an Azure environment and test a model against the catalog. +- scaffold, test, and deploy a hosted Backer Concierge agent. +- connect the agent to the website through a local server-side proxy and chat widget. + +## Scenario + +Tailspin Toys backers can browse games by category and publisher, but those filters don't help everyone find their next game. Some backers have questions such as *Which games would suit someone who loves Git puns?* Those questions don't have dropdown answers. + +Tailspin Toys wants a **Backer Concierge** that helps backers discover games through conversation. It should recommend games from the Tailspin catalog, ask a short clarifying question when someone's preferences are vague, and remember earlier recommendations when they ask a follow-up question. + +Backers need answers they can trust. The concierge should use only information in the catalog and be clear when a detail isn't available, rather than inventing games, publishers, ratings, funding totals, backer counts, prices, player counts, play times, or release dates. + +## Choose your next step + +The modules build on one another in the same Tailspin Toys repository, branch, and Foundry project. Each ends with a working checkpoint. + +| Module | What you'll do | Completion point | +| --- | --- | --- | +| [1. Prepare the project and model][project-model] | Set up the tools, export the catalog, and select and test a model | A deployed model that answers catalog questions correctly | +| [2. Build and deploy the agent][build-deploy] | Scaffold the agent, test its behavior, and deploy it to Foundry | A working hosted Backer Concierge | +| [3. Connect the agent to the website][connect-site] | Build a local proxy and chat widget, then test the complete flow | A concierge available through your local website | + +> [!IMPORTANT] +> Microsoft Foundry hosted agents are in public preview. +> +> This series creates billable Azure resources, including a model deployment and a hosted agent. Resource creation requires a review of the selected subscription, region, quota, and estimated cost. The [cleanup instructions][cleanup] apply even if you stop after the first or second module. + +1. To begin the optional series, continue to [Prepare the project and model][project-model]. Setup instructions are included there. +2. If you'd rather finish the core workshop, continue to [Review and next steps][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. + +> [!CAUTION] +> 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. + +1. Stop any local agent, Function, or Astro dev server you started by pressing Ctrl+C in its terminal. +2. Exit Copilot CLI. If you scaffolded the agent in Module 2, run the following from the Tailspin Toys repository root using the same `azd` environment: + + ```bash + azd down --purge + ``` + +3. Check the selected subscription with `az account show`. Inspect `rg-tailspin-toys` in that subscription and 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 haven't scaffolded 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. Confirm in the Azure portal that resource group deletion finishes. The `--no-wait` command returns before deletion completes. + +## Resources + +- [Azure Skills Plugin][azure-skills] +- [Use the Microsoft Foundry Skill in coding agents][foundry-skill] +- [Deploy your first hosted agent with the Microsoft Foundry Skill][hosted-agent-quickstart] +- [Hosted agent permissions][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #clean-up-your-resources +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/cli/9-review.md b/docs/cli/9-review.md index 7d80db13..c86f4115 100644 --- a/docs/cli/9-review.md +++ b/docs/cli/9-review.md @@ -13,7 +13,7 @@ Over the last several exercises, you explored some of the most common use cases - calling custom agents for advanced and more complex tasks. - using slash commands to manage your session, and optionally bridging back to cloud agent via `/delegate`. -If you haven't yet, consider the [optional Microsoft Foundry lesson][foundry-lesson] before you finish, which builds a catalog-grounded hosted agent on top of the Tailspin Toys site. +If you'd like an optional challenge, [build a concierge with GitHub Copilot CLI and Foundry][foundry-lesson] in a three-module series covering model setup, agent development and deployment, and website integration. Let's talk about some slash commands, best practices, and next steps. diff --git a/docs/cli/README.md b/docs/cli/README.md index 7cb6a4a6..0aa1511f 100644 --- a/docs/cli/README.md +++ b/docs/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 **[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** puts GitHub Copilot in your terminal as an agentic coding assistant. It explores codebases, generates code, runs commands, and connects to external tools — all from the command line, so you can stay in the flow without switching to a graphical editor. -Across these exercises you'll install and authenticate Copilot CLI, then give it project context with custom instructions before using plan mode to generate a feature deliberately. You'll connect the Playwright MCP server to test that feature in a real browser, then extend Copilot with reusable agent skills and custom agents. Finally, you'll explore slash commands for managing context, models, and sharing a wrapup of what you've built. You can also explore an optional exercise that uses the Microsoft Foundry Skill to build and deploy a hosted agent. +Across these exercises you'll install and authenticate Copilot CLI, then give it project context with custom instructions before using plan mode to generate a feature deliberately. You'll connect the Playwright MCP server to test that feature in a real browser, then extend Copilot with reusable agent skills and custom agents. Finally, you'll explore slash commands for managing context, models, and sharing, and wrap up with a review of what you've built. An optional three-module series uses GitHub Copilot CLI and Foundry to prepare a model, build and deploy a hosted agent, and connect it to the website. ## Exercises @@ -22,8 +22,8 @@ Across these exercises you'll install and authenticate Copilot CLI, then give it | [5. Agent Skills][ex5] | Skills | Enhance Copilot with specialized skills | | [6. Custom Agents][ex6] | Agents | Review and use custom agents | | [7. Slash Commands][ex7] | CLI Features | Explore context, models, sharing, and optional delegation to cloud agent | -| [8. Build a Backer Concierge AI Agent (Optional)][foundry] | Hosted agents | Build and deploy a catalog-grounded Backer Concierge | | [9. Review][ex9] | Summary | Review key concepts and next steps | +| [Optional: Incorporate Foundry][foundry] | Hosted agents | Prepare a model, build and deploy the concierge, and connect it to the website in three modules | ## Prerequisites diff --git a/docs/es-es/cli/7-slash-commands.md b/docs/es-es/cli/7-slash-commands.md index 281493b4..0973cdf8 100644 --- a/docs/es-es/cli/7-slash-commands.md +++ b/docs/es-es/cli/7-slash-commands.md @@ -157,7 +157,7 @@ Usar comandos de barra en Copilot CLI te permite configurarlo, compartir sesione - `/model` para explorar la lista de modelos disponibles y seleccionar uno nuevo si así lo deseas. - `/delegate` como puente opcional hacia cloud agent. -Por supuesto, hay más comandos de barra disponibles y mucho más por explorar con Copilot CLI. Si quieres ir más allá, la [lección opcional de Microsoft Foundry][foundry-lesson] te guía para compilar un agente hospedado sobre el catálogo de Tailspin. Si no, vamos a cerrar este recorrido [repasando lo que hemos aprendido][next-lesson] y viendo algunos próximos pasos para seguir aprendiendo. +Por supuesto, hay más comandos de barra disponibles y mucho más por explorar con Copilot CLI. Vamos a cerrar este recorrido [repasando lo que hemos aprendido][next-lesson] y viendo algunos próximos pasos para seguir aprendiendo. Si te apetece un reto opcional antes de terminar, puedes [crear un concierge con GitHub Copilot CLI y Foundry][foundry-lesson] en una serie de tres módulos. ## Recursos diff --git a/docs/es-es/cli/8-foundry-agent/1-project-and-model.md b/docs/es-es/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..93e2ea9e --- /dev/null +++ b/docs/es-es/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "Módulo 1 - Prepara el proyecto y el modelo" +description: "Configura las herramientas de Azure, exporta el catálogo de Tailspin y selecciona y prueba un modelo de Foundry con GitHub Copilot CLI." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +Este es el primer módulo de [Opcional: incorpora Foundry][overview]. Prepararás las herramientas y el catálogo y, después, usarás Copilot para crear un proyecto de Foundry y probar un modelo desplegado antes de crear el agente. + +En este módulo: + +- instalarás las herramientas de línea de comandos de Azure y el complemento Azure Skills. +- exportarás el catálogo y planificarás el trabajo en Foundry. +- seleccionarás, desplegarás y probarás un modelo teniendo en cuenta los límites del catálogo. + +## Escenario + +Tailspin Toys necesita un concierge que distinga entre los datos del catálogo y la información que la empresa no proporciona. Una recomendación útil podría mencionar un juego de puzles con una buena valoración, pero no debe inventar su importe total de financiación. Antes de invertir en un asistente completo, el equipo quiere asegurarse de que el modelo elegido respeta ese límite. + +## Requisitos previos y configuración + +Usarás Azure para hospedar el Backer Concierge y Copilot CLI para guiar el trabajo. Primero, prepara las herramientas de línea de comandos y el complemento que permiten a Copilot trabajar con tus recursos de Azure. + +> [!IMPORTANT] +> Las [instrucciones de limpieza][cleanup] cubren tanto la posibilidad de parar después de este módulo como la de terminar la serie. + +1. Confirma que tienes una suscripción de Azure. Si necesitas una, las opciones disponibles incluyen una [suscripción gratuita de Azure con 200 USD de crédito][azure-free] o [Azure for Students con 100 USD de crédito][azure-students]. +2. Vuelve a tu codespace de Tailspin Toys y abre un terminal. +3. Instala Azure CLI en el contenedor de desarrollo: + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. Inicia sesión en Azure CLI con `az login` y comprueba que estás usando la suscripción correcta con `az account show`. +5. Instala [Azure Developer CLI][install-azd], versión 1.27.1 o posterior. Microsoft Foundry usa `azd` para probar y desplegar agentes hospedados. + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. Inicia sesión en Azure Developer CLI con `azd auth login` y comprueba que estás usando la suscripción correcta con `azd config show`. +7. Instala la extensión de Foundry para Azure Developer CLI (azd): + + ```bash + azd ext install microsoft.foundry + ``` + +8. Abre una nueva sesión de Copilot CLI en un panel lateral desde la paleta de comandos. Pulsa Command+Shift+P (Mac) o Ctrl+Shift+P (Windows/Linux) y selecciona **Chat: New Copilot CLI session to the side**. +9. Añade el marketplace de Azure Skills. Solo necesitas hacerlo la primera vez que instalas el complemento: + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. Instala el [complemento Azure Skills][azure-skills], que añade habilidades de Azure, Azure MCP Server y Foundry MCP Server a GitHub Copilot CLI: + + ```text + /plugin install azure@azure-skills + ``` + +11. Confirma que el complemento ha configurado el servidor MCP de Azure: + + ```text + /mcp list + ``` + +12. Si las habilidades o los servidores MCP no aparecen, prueba `/skills reload` o `/restart` y vuelve a comprobarlo. + +Las habilidades enseñan a Copilot el flujo de trabajo, mientras que los servidores MCP le permiten inspeccionar tus recursos de Azure y trabajar con ellos. + +## Prepara la rama de trabajo + +En los ejercicios anteriores puede que hayas creado y enviado otras ramas de funcionalidades. Empezarás esta serie opcional desde una rama `main` actualizada para mantener separado el trabajo del agente. + +1. En el terminal de shell, cambia a `main`, descarga los últimos cambios y crea una rama para el Backer Concierge: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## Genera la exportación del catálogo + +El agente necesita el catálogo en un archivo que pueda leer. El ejemplo de Tailspin Toys incluye un script de exportación probado para este fin. + +1. Vuelve a Copilot CLI e introduce: + + ```text + 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 debería ejecutar el equivalente de: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![Resumen de la exportación del catálogo](../../../_images/cli-8-export-db-catalog.png) + +2. Abre `db/catalog.json`. Confirma que contiene 21 juegos con título, descripción, categoría, editorial y valoración por estrellas. Su campo `note` indica que el catálogo no contiene importes totales de financiación, cifras de personas que apoyan los juegos, niveles de aportación ni fechas de lanzamiento. Tampoco tiene campos de precio, número de jugadores o duración de las partidas. Esas omisiones definen el límite que debe respetar el agente. + +## Planifica el trabajo en Foundry + +Antes de que Copilot cree recursos de Azure o añada código del agente, usarás el modo de planificación para revisar el flujo de trabajo previsto. + +1. Introduce el siguiente prompt: + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. Revisa el plan propuesto. Confirma que Copilot pretende usar la habilidad `microsoft-foundry` y que separa el agente hospedado de la aplicación Astro existente. Si observas algo preocupante o inesperado, solicita cambios antes de continuar. +3. Sal del modo de planificación cuando estés conforme con el enfoque. + +## Configura un proyecto de Foundry y un modelo + +El agente necesita un proyecto de Foundry y un modelo desplegado. Usarás la habilidad Microsoft Foundry para seleccionarlos según la disponibilidad y la cuota actuales de tu suscripción. + +1. Pide a Copilot que cree el proyecto. Antes de aprobar la creación de recursos, comprueba la suscripción, la región y la cuota seleccionadas, así como el coste estimado: + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![Creación de un proyecto público de Foundry](../../../_images/cli-8-create-foundry-project.png) + +2. Cuando el proyecto esté listo, pide a Copilot que recomiende un modelo: + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + Copilot puede pedirte que selecciones un modelo entre las opciones recomendadas. + + ![Selección de un modelo entre las opciones recomendadas](../../../_images/cli-8-select-foundry-model.png) + + Continuaremos con `gpt-5.4-mini` en los pasos restantes, pero la disponibilidad y la cuota varían según la región. + +3. Selecciona un modelo entre las opciones recomendadas y pide a Copilot que lo despliegue. Revisa la capacidad y el coste antes de aprobar el despliegue: + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![Despliegue del modelo seleccionado](../../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> La disponibilidad de los modelos cambia con el tiempo. La elección adecuada es un modelo cuya disponibilidad en tu proyecto confirme Copilot, no un modelo fijado en un ejemplo. + +## Prueba el modelo desplegado + +Antes de crear el agente hospedado, comprobarás si el modelo sigue las reglas del Backer Concierge para fundamentar las respuestas en el catálogo. Esta prueba usa las instrucciones previstas y el contexto del catálogo, sin código ni configuración de agente. + +Primero, asignarás a la cuenta con la que has iniciado sesión el rol **Foundry Project Manager**, para desarrollar el agente hospedado en el módulo 2, y el rol **Cognitive Services OpenAI User**, para realizar inferencias directamente con el modelo. Después, harás una pregunta sobre el catálogo que también solicite información que este no contiene. + +1. Abre un terminal nuevo y define los valores de la cuenta, el proyecto y el usuario. Sustituye `` por el nombre de la cuenta de Foundry que se indicó al crear el proyecto: + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. Asigna el rol **Foundry Project Manager**: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. Asigna el rol **Cognitive Services OpenAI User**: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. Vuelve a Copilot CLI e introduce: + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![Respuesta del modelo de Foundry que recomienda un juego real del catálogo e indica que no hay datos de financiación disponibles](../../../_images/cli-8-foundry-agent-response.png) + +5. Revisa la respuesta. Debe recomendar únicamente un juego real del catálogo, usar los datos correctos del catálogo y explicar que la información de financiación no está disponible. Si el modelo inventa un título, detalles del juego o un importe total de financiación, compáralo con otro modelo recomendado antes de continuar. + +> [!NOTE] +> Esta prueba solo evalúa el modelo desplegado con instrucciones temporales y el contexto del catálogo. No prueba un agente. El módulo 2 repite la prueba después de generar la estructura del agente para validar su código, su empaquetado y su comportamiento conversacional. + +## Resumen y siguientes pasos + +Has preparado las herramientas de Azure, exportado el catálogo y probado un modelo desplegado con las reglas del Backer Concierge para fundamentar las respuestas en el catálogo. El resultado que debes comprobar al terminar este módulo es un modelo que recomiende juegos reales del catálogo sin inventar la información que falta. + +A continuación, usarás el mismo repositorio, la rama `foundry-agent-cli`, la sesión de Copilot CLI, el proyecto de Foundry y el despliegue del modelo seleccionado para [crear y desplegar el agente][next-lesson]. Si vas a parar aquí, [elimina los recursos de Azure][cleanup] para evitar que sigan generando costes. + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#elimina-los-recursos +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/es-es/cli/8-foundry-agent/2-build-and-deploy.md b/docs/es-es/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..ad11981b --- /dev/null +++ b/docs/es-es/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "Módulo 2 - Crea y despliega el agente" +description: "Usa GitHub Copilot CLI y la habilidad Microsoft Foundry para generar la estructura del Backer Concierge, probarlo y desplegarlo." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +En el [módulo 1][previous-lesson], preparaste el catálogo y probaste un modelo desplegado. Este segundo módulo de la [serie opcional del concierge][overview] convierte esa base en un agente hospedado. + +En este módulo: + +- generarás la estructura del agente con su propia copia del catálogo lista para desplegar. +- comprobarás en local que las respuestas se fundamentan en el catálogo y que se mantiene la continuidad de la conversación. +- desplegarás el agente y lo invocarás de forma remota. + +## Escenario + +Tailspin Toys necesita algo más que una respuesta aislada de un modelo. Quienes apoyan los juegos esperan que el concierge recuerde los que acaba de recomendar y responda a preguntas de seguimiento sobre ellos. El equipo también necesita que esas respuestas sigan siendo fiables cuando el concierge pase del equipo de un desarrollador a un servicio hospedado. + +## Continúa con tu proyecto + +Este módulo parte del modelo funcional del módulo 1. Mantendrás el mismo proyecto y despliegue en lugar de crear otro conjunto de recursos de Azure. + +1. Vuelve al repositorio de Tailspin Toys en la rama `foundry-agent-cli` y a la sesión de Copilot CLI del módulo 1. +2. Confirma que `db/catalog.json` está disponible y que conservas el proyecto de Foundry, el despliegue del modelo seleccionado y la sesión de Azure que usaste para probar el modelo. Si no has completado esa configuración, termina primero [Prepara el proyecto y el modelo][previous-lesson]. + +> [!IMPORTANT] +> Los agentes hospedados están en versión preliminar pública y crean recursos facturables de Azure. Las [instrucciones de limpieza][cleanup] se aplican si paras después de este módulo. + +## Genera la estructura del agente Backer Concierge + +Ahora pedirás a la habilidad Microsoft Foundry que genere la estructura del agente hospedado dentro del repositorio existente de Tailspin Toys y, después, inspeccionarás su empaquetado y configuración antes de ejecutarlo. + +1. Introduce el siguiente prompt en Copilot CLI: + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. Sigue la sesión para responder a las preguntas sobre el proyecto de Foundry, el despliegue del modelo, el nombre del agente o el entorno. +3. Cuando Copilot termine, inspecciona los cambios: + + ```text + /diff + ``` + + Confirma que: + + - `azure.yaml` contiene un servicio con `host: azure.ai.agent`. + - el servicio apunta a `agent/backer-concierge`. + - el paquete del servicio desplegado incluye su propia copia generada del catálogo. + - un script o paso de compilación actualiza esa copia desde `db/catalog.json`, en lugar de mantener dos catálogos editados a mano. + - el agente usa el despliegue del modelo seleccionado y la API Responses. + - las instrucciones rechazan explícitamente los datos que no aparecen en el catálogo. + - no hay credenciales, tokens de acceso, archivos `.env` ni archivos de entorno de `.azure` preparados para incluirse en un commit. + + Usa la siguiente estructura como punto de comprobación tras generar la estructura del agente: + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy` empaqueta el directorio del servicio del agente hospedado. Una referencia en tiempo de ejecución desde `agent/backer-concierge` a `db/catalog.json`, situado en la raíz del repositorio, puede funcionar en local y fallar después del despliegue. La copia generada debe estar disponible en el directorio `agent/backer-concierge/` antes del despliegue. + +4. Pide a Copilot que ejecute las pruebas específicas e inspeccione la configuración generada antes de iniciar el servicio: + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + No continúes hasta que las pruebas específicas se superen. + + ![Verificación de la estructura generada del agente](../../../_images/cli-8-verify-generated-agent.png) + +## Prueba el agente en local + +Ahora comprobarás, mediante la API Responses local del agente, que sus respuestas se fundamentan en el catálogo y que su comportamiento conversacional es correcto. El servicio del agente local ocupa el terminal mientras se ejecuta, así que mantendrás Copilot CLI abierto en el terminal actual e iniciarás el agente desde un segundo terminal. + +1. Abre otro terminal pulsando Ctrl+\`. +2. Desde la raíz del repositorio de Tailspin Toys, ejecuta: + + ```bash + azd ai agent run + ``` + + La primera ejecución local crea un entorno de Python, instala las dependencias e inicia el agente hospedado. Deja este terminal en ejecución. + +3. Vuelve a Copilot CLI en el primer terminal e introduce: + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![Pruebas del despliegue del agente hospedado superadas](../../../_images/cli-8-passing-acceptance-scenarios.png) + +4. Revisa los resultados. Si el agente no puede conectarse, confirma que el segundo terminal sigue ejecutando el servicio. Si falla una prueba, pide a Copilot que corrija solo el defecto local, ejecute las pruebas específicas y te indique cuándo reiniciar `azd ai agent run`. Reinicia el servicio y repite la prueba de aceptación fallida después de cada cambio. + +## Despliega el agente hospedado + +Una vez superadas las pruebas de aceptación locales, puedes desplegar el agente en Microsoft Foundry. Usarás el mismo flujo guiado por la habilidad para comprobar que todo está listo para el despliegue y probar el punto de conexión remoto. + +1. Detén el servicio local con Ctrl+C cuando se hayan superado todas las pruebas de aceptación. +2. Vuelve a Copilot CLI e introduce el siguiente prompt. Revisa los recursos propuestos y el coste estimado antes de aprobar el despliegue: + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. Si se te pide que selecciones el origen de una batería de evaluación, elige **No, set it up later**. + + ![Estado del despliegue del agente hospedado y enlace al área de pruebas](../../../_images/cli-8-hosted-agent-deployment.png) + +4. Revisa el estado del despliegue y la respuesta remota. Confirma que el agente está en ejecución y recomienda únicamente juegos reales del catálogo. Si el despliegue o la invocación fallan, pide a Copilot que diagnostique el fallo y repita la prueba remota antes de continuar. + +El enlace al área de pruebas que se muestra te permite interactuar con el agente hospedado desplegado en el portal de Microsoft Foundry. + +El flujo guiado por la habilidad usa `azd deploy` para empaquetar el código fuente del servicio, resolver las dependencias, compilarlo de forma remota y publicarlo en Microsoft Foundry. Usa el flujo de invocación de Foundry para probar el punto de conexión desplegado. + +## Resumen y siguientes pasos + +Has generado la estructura de un agente con una copia del catálogo lista para desplegar, probado que las respuestas se fundamentan en el catálogo y que la conversación mantiene la continuidad, y verificado una respuesta remota de Microsoft Foundry. Ahora tienes un Backer Concierge hospedado y funcional. + +A continuación, mantendrás el mismo repositorio, la misma rama, la misma sesión de Copilot CLI y el agente desplegado para [conectar el concierge al sitio web][next-lesson]. Si un agente hospedado es suficiente para lo que quieres explorar, puedes parar aquí y [eliminar los recursos de Azure][cleanup]. + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#elimina-los-recursos diff --git a/docs/es-es/cli/8-foundry-agent/3-connect-to-site.md b/docs/es-es/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..8df12ffc --- /dev/null +++ b/docs/es-es/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "Módulo 3 - Conecta el agente al sitio web" +description: "Conecta el Backer Concierge hospedado a Tailspin Toys mediante un proxy local de Azure Functions y un widget de chat accesible." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +En el [módulo 2][previous-lesson], desplegaste y probaste el Backer Concierge. Este último módulo de la [serie opcional del concierge][overview] permite acceder a ese agente desde tu sitio web local de Tailspin Toys. + +En este módulo: + +- crearás un proxy local de Azure Functions que mantenga las credenciales de Foundry en el servidor. +- añadirás un widget de chat accesible al sitio. +- verificarás el flujo completo de conversación y eliminarás los recursos. + +## Escenario + +Quienes apoyan los juegos los descubren en el sitio web de Tailspin Toys, no en el terminal de un desarrollador ni en un portal de Azure. El equipo quiere que el concierge esté disponible junto al catálogo, con una experiencia de chat que admita preguntas de seguimiento y proteja las credenciales del servicio. + +## Continúa con el agente hospedado + +La integración con el sitio web necesita el agente desplegado del módulo 2. Mantendrás ese agente en ejecución en Foundry mientras el proxy y el sitio web se ejecutan en local. + +1. Vuelve al repositorio de Tailspin Toys en la rama `foundry-agent-cli` y a la sesión de Copilot CLI existente. +2. Confirma que el Backer Concierge está desplegado y que la invocación remota de [Crea y despliega el agente][previous-lesson] se completó correctamente. Si ya has eliminado los recursos de Azure, vuelve a crearlos siguiendo los módulos anteriores antes de continuar. + +> [!IMPORTANT] +> El proxy y el sitio web de este módulo se ejecutan en local; no se trata de un despliegue del sitio web en producción. El modelo y el agente hospedado siguen siendo recursos facturables de Azure hasta que completes la [limpieza][cleanup]. + +## Crea 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. Añadirás una función local de Azure Functions que actúe como **barrera de protección de credenciales del lado del servidor**: se autenticará en Foundry y devolverá al navegador únicamente la respuesta del agente. + +La habilidad `microsoft-foundry` se encarga del flujo del agente hospedado, mientras que las habilidades más generales de Azure del mismo complemento pueden preparar el proyecto local de la función. Usarás esas habilidades para crear el proxy y, después, comprobarás que se conecta al agente sin exponer credenciales. + +1. En Copilot CLI, introduce: + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Configuración del proxy local de Azure Functions](../../../_images/cli-8-azure-functions-proxy.png) + +2. Abre otro terminal e inicia la función local con el comando que te proporcione Copilot. Deja la función en ejecución. +3. Vuelve a Copilot CLI y pide a Copilot que pruebe el proxy local: + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. Inspecciona la respuesta. Debe explicar que el catálogo no contiene precios. No debe contener ningún token, credencial, punto de conexión del proyecto ni identificador de conversación sin procesar de Foundry, ni tampoco una traza de la pila. + + ![Respuesta JSON sin datos sensibles del punto de conexión local del concierge](../../../_images/cli-8-sanitized-json-response.png) + +## Crea el widget de chat + +El proxy ofrece al navegador una forma segura de conectarse al concierge. Ahora añadirás un widget de chat al sitio y usarás Playwright para comprobar el flujo completo de conversación. + +1. Pide a Copilot que cree la integración con el sitio: + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. Mantén la función local en ejecución e inicia el sitio Astro en otro terminal con el comando que te proporcione Copilot. +3. Vuelve a Copilot CLI. El servidor MCP de Playwright que añadiste en el [ejercicio 4][playwright-lesson] ya está disponible. Pide a Copilot que pruebe el widget: + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Captura del widget Backer Concierge en el sitio de Tailspin Toys](../../../_images/cli-8-backer-concierge-widget.png) + +4. Revisa los resultados y las pruebas aportadas. Si alguna comprobación falla, pide a Copilot que corrija el comportamiento correspondiente del proxy o del widget y repita las comprobaciones fallidas antes de terminar. + +## Elimina los recursos + +Has llegado al último punto de comprobación: un concierge funcional en tu sitio web local. Las instrucciones de limpieza comunes cubren tanto los servicios locales como los recursos de Azure creados a lo largo de la serie. + +1. Completa las instrucciones de [Elimina los recursos][cleanup], incluida la detención de los servicios locales y la verificación de que la eliminación de los recursos de Azure ha terminado. + +## Resumen y siguientes pasos + +Has conectado el Backer Concierge hospedado a Tailspin Toys mediante un proxy local del lado del servidor y un widget de chat accesible. A lo largo de la serie, has usado GitHub Copilot CLI y Foundry para preparar un modelo, crear y desplegar un agente y verificar una integración completa con el sitio web. + +Continúa con [Repaso y próximos pasos][review] para terminar el taller de CLI. + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#elimina-los-recursos diff --git a/docs/es-es/cli/8-foundry-agent/README.md b/docs/es-es/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..27342b72 --- /dev/null +++ b/docs/es-es/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: es-es/cli/8-foundry-agent +title: "Opcional: incorpora Foundry" +description: "Una serie de tres módulos para preparar un modelo, crear y desplegar un agente basado en el catálogo y conectarlo a Tailspin Toys." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +Esta serie opcional usa GitHub Copilot CLI y la habilidad Microsoft Foundry para convertir el catálogo de Tailspin Toys en un asistente conversacional. Los tres módulos te llevan desde la configuración del proyecto y del modelo hasta un agente hospedado y una integración funcional con el sitio web. + +En esta serie: + +- prepararás un entorno de Azure y probarás un modelo con el catálogo. +- generarás la estructura de un agente Backer Concierge hospedado, lo probarás y lo desplegarás. +- conectarás el agente al sitio web mediante un proxy local del lado del servidor y un widget de chat. + +## Escenario + +Quienes apoyan los juegos de Tailspin Toys pueden explorarlos por categoría y editorial, pero esos filtros no ayudan a todo el mundo a encontrar su próximo juego. Algunas personas tienen preguntas como *¿Qué juegos serían adecuados para alguien a quien le encantan los juegos de palabras sobre Git?* Esas preguntas no se responden con un menú desplegable. + +Tailspin Toys quiere un **Backer Concierge** que ayude a quienes apoyan sus juegos a descubrir nuevos títulos mediante una conversación. Debe recomendar juegos del catálogo de Tailspin, hacer una pregunta breve para aclarar las preferencias cuando sean vagas y recordar las recomendaciones anteriores cuando se plantee una pregunta de seguimiento. + +Quienes apoyan los juegos necesitan respuestas fiables. El concierge debe usar únicamente la información del catálogo e indicar claramente cuándo un dato no está disponible, en lugar de inventar juegos, editoriales, valoraciones, importes totales de financiación, cifras de personas que los apoyan, precios, números de jugadores, duraciones de las partidas o fechas de lanzamiento. + +## Elige el siguiente paso + +Los módulos se apoyan unos en otros y usan el mismo repositorio de Tailspin Toys, la misma rama y el mismo proyecto de Foundry. Cada uno termina con un resultado funcional que puedes comprobar. + +| Módulo | Qué harás | Resultado al terminar | +| --- | --- | --- | +| [1. Prepara el proyecto y el modelo][project-model] | Configura las herramientas, exporta el catálogo y selecciona y prueba un modelo | Un modelo desplegado que responde correctamente a preguntas sobre el catálogo | +| [2. Crea y despliega el agente][build-deploy] | Genera la estructura del agente, prueba su comportamiento y despliégalo en Foundry | Un Backer Concierge hospedado y funcional | +| [3. Conecta el agente al sitio web][connect-site] | Crea un proxy local y un widget de chat y prueba el flujo completo | Un concierge disponible en tu sitio web local | + +> [!IMPORTANT] +> Los agentes hospedados de Microsoft Foundry están en versión preliminar pública. +> +> Esta serie crea recursos facturables de Azure, entre ellos un despliegue de modelo y un agente hospedado. Antes de crear recursos, debes revisar la suscripción, la región y la cuota seleccionadas, así como el coste estimado. Las [instrucciones de limpieza][cleanup] también se aplican si paras después del primer o del segundo módulo. + +1. Para empezar la serie opcional, continúa con [Prepara el proyecto y el modelo][project-model]. Allí se incluyen las instrucciones de configuración. +2. Si prefieres terminar el taller principal, continúa con [Repaso y próximos pasos][review]. + +## Elimina los recursos + +Cuando termines de experimentar en cualquiera de los puntos de comprobación, elimina los recursos de Azure para evitar costes no deseados. La limpieza elimina recursos necesarios para los módulos posteriores, por lo que tendrás que volver a crearlos si quieres continuar después. + +> [!CAUTION] +> Elimina `rg-tailspin-toys` solo si está dedicado a este ejercicio y no contiene recursos que necesites conservar. Si eliminas un grupo de recursos compartido, también eliminarás recursos ajenos al ejercicio. + +1. Detén cualquier agente local, función o servidor de desarrollo de Astro que hayas iniciado pulsando Ctrl+C en su terminal. +2. Sal de Copilot CLI. Si generaste la estructura del agente en el módulo 2, ejecuta lo siguiente desde la raíz del repositorio de Tailspin Toys usando el mismo entorno de `azd`: + + ```bash + azd down --purge + ``` + +3. Comprueba la suscripción seleccionada con `az account show`. Inspecciona `rg-tailspin-toys` en esa suscripción y verifica que todos los recursos restantes pertenecen a este ejercicio. Si paraste después del módulo 1, debes eliminar el proyecto de Foundry y el modelo aunque aún no hayas generado la estructura de un servicio de `azd`. +4. Si el grupo de recursos dedicado al taller sigue existiendo y solo contiene recursos que quieres eliminar, ejecuta: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Confirma en Azure Portal que la eliminación del grupo de recursos ha terminado. El comando con `--no-wait` devuelve el control antes de que termine la eliminación. + +## Recursos + +- [Complemento Azure Skills][azure-skills] +- [Usar la habilidad Microsoft Foundry en agentes de programación][foundry-skill] +- [Desplegar tu primer agente hospedado con la habilidad Microsoft Foundry][hosted-agent-quickstart] +- [Permisos de los agentes hospedados][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #elimina-los-recursos +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/es-es/cli/9-review.md b/docs/es-es/cli/9-review.md index 48534f24..d525c8cb 100644 --- a/docs/es-es/cli/9-review.md +++ b/docs/es-es/cli/9-review.md @@ -1,5 +1,5 @@ --- -title: "Ejercicio 8 - Repaso y próximos pasos" +title: "Ejercicio 9 - Repaso y próximos pasos" authors: - geektrainer lastUpdated: 2026-06-30 @@ -13,6 +13,8 @@ En los últimos ejercicios, has explorado algunos de los casos de uso más habit - invocar agentes personalizados para tareas avanzadas y más complejas. - usar comandos de barra para gestionar tu sesión y, opcionalmente, volver a conectar con cloud agent mediante `/delegate`. +Si te apetece un reto opcional, puedes [crear un concierge con GitHub Copilot CLI y Foundry][foundry-lesson] en una serie de tres módulos que abarca la configuración del modelo, el desarrollo y despliegue del agente y la integración con el sitio web. + Vamos a hablar de algunos comandos de barra, buenas prácticas y próximos pasos. ## Comandos de barra @@ -61,6 +63,7 @@ Si quieres explorar más del ecosistema de GitHub Copilot, consulta el [recorrid - [Especificación de MCP][mcp-spec] [previous-lesson]: ../7-slash-commands/ +[foundry-lesson]: ../8-foundry-agent/ [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli [using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli [awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/es-es/cli/README.md b/docs/es-es/cli/README.md index f1c9b436..568127ff 100644 --- a/docs/es-es/cli/README.md +++ b/docs/es-es/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 **[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** incorpora GitHub Copilot a tu terminal como asistente de programación con agentes. Explora bases de código, genera código, ejecuta comandos y se conecta a herramientas externas, todo desde la línea de comandos, para que puedas mantener el flujo sin cambiar a un editor gráfico. -A lo largo de estos ejercicios instalarás y autenticarás Copilot CLI, y después le darás contexto del proyecto con instrucciones personalizadas antes de usar el modo de planificación para generar una funcionalidad de forma deliberada. Conectarás el servidor MCP de Playwright para probar esa funcionalidad en un navegador real y, a continuación, ampliarás Copilot con habilidades de agente reutilizables y agentes personalizados. Por último, explorarás los comandos de barra para gestionar el contexto, los modelos y el uso compartido, y terminarás con un repaso de lo que has creado. +A lo largo de estos ejercicios instalarás y autenticarás Copilot CLI, y después le darás contexto del proyecto con instrucciones personalizadas antes de usar el modo de planificación para generar una funcionalidad de forma deliberada. Conectarás el servidor MCP de Playwright para probar esa funcionalidad en un navegador real y, a continuación, ampliarás Copilot con habilidades de agente reutilizables y agentes personalizados. Por último, explorarás los comandos de barra para gestionar el contexto, los modelos y el uso compartido, y terminarás con un repaso de lo que has creado. También puedes seguir una [serie opcional de tres módulos con GitHub Copilot CLI y Foundry][foundry] para preparar un modelo, crear y desplegar un agente hospedado e integrarlo en el sitio. ## Ejercicios @@ -22,8 +22,8 @@ A lo largo de estos ejercicios instalarás y autenticarás Copilot CLI, y despu | [5. Habilidades de agente][ex5] | Habilidades | Mejora Copilot con habilidades especializadas | | [6. Agentes personalizados][ex6] | Agentes | Revisa y usa agentes personalizados | | [7. Comandos de barra][ex7] | Funciones de CLI | Explora el contexto, los modelos, el uso compartido y la delegación opcional al agente en la nube | -| [8. Compilar un agente de IA Backer Concierge (opcional)][foundry] | Agentes hospedados | Compila e implementa un Backer Concierge basado en el catálogo | | [9. Repaso][ex9] | Resumen | Repasa los conceptos clave y los próximos pasos | +| [Opcional: incorpora Foundry][foundry] | Agentes hospedados | Prepara un modelo, crea y despliega el concierge y conéctalo al sitio web en tres módulos | ## Requisitos previos diff --git a/docs/ja-jp/cli/7-slash-commands.md b/docs/ja-jp/cli/7-slash-commands.md index ed60b514..e8ec62f2 100644 --- a/docs/ja-jp/cli/7-slash-commands.md +++ b/docs/ja-jp/cli/7-slash-commands.md @@ -156,7 +156,7 @@ Copilot CLI の slash command を使うと、設定の変更、セッション - `/model` で利用可能なモデルの一覧を確認し、必要に応じて別のモデルを選択する。 - `/delegate` が cloud agent への任意の橋渡しになることを学ぶ。 -利用できる slash command はもちろんこれ以外にもあり、Copilot CLI にはまだ多くの機能があります。さらに進みたい場合は、[オプションの Microsoft Foundry レッスン][foundry-lesson]で Tailspin カタログ上にホスト型エージェントを構築する方法を学べます。そうでなければ、最後に[ここまでに学んだことを振り返り][next-lesson]、学習を続けるための次のステップを確認して締めくくりましょう。 +利用できる slash command はもちろんこれ以外にもあり、Copilot CLI にはまだ多くの機能があります。最後に[ここまでに学んだことを振り返り][next-lesson]、学習を続けるための次のステップを確認して締めくくりましょう。締めくくる前に任意の追加課題に挑戦したい場合は、全 3 モジュールのシリーズで[GitHub Copilot CLI と Foundry を使ったコンシェルジュの構築][foundry-lesson]に取り組めます。 ## リソース diff --git a/docs/ja-jp/cli/8-foundry-agent/1-project-and-model.md b/docs/ja-jp/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..bcd7622e --- /dev/null +++ b/docs/ja-jp/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "モジュール 1 - プロジェクトとモデルを準備する" +description: "Azure ツールをセットアップし、Tailspin のカタログをエクスポートして、GitHub Copilot CLI で Foundry モデルを選択してテストします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +これは、[オプション: Foundry を組み込む][overview]の最初のモジュールです。ツールとカタログを準備してから、Copilot で Foundry プロジェクトを作成し、エージェントを構築する前にデプロイ済みのモデルをテストします。 + +このモジュールでは、次の内容に取り組みます。 + +- Azure のコマンド ライン ツールと Azure Skills Plugin をインストールする。 +- カタログをエクスポートし、Foundry での作業を計画する。 +- モデルを選択してデプロイし、カタログの情報の範囲を守れるかテストする。 + +## シナリオ + +Tailspin Toys には、カタログにある事実と、会社が提供していない情報とを区別できるコンシェルジュが必要です。評価の高いパズル ゲームを紹介するのは役立つおすすめですが、そのゲームの資金調達総額を作り上げてはいけません。チームは、本格的なアシスタントの開発に取り組む前に、選んだモデルがその境界を守れることを確かめたいと考えています。 + +## 前提条件とセットアップ + +Azure で Backer Concierge をホストし、Copilot CLI の支援を受けながら作業を進めます。まず、Copilot が Azure リソースを操作するためのコマンド ライン ツールとプラグインを準備します。 + +> [!IMPORTANT] +> [クリーンアップの手順][cleanup]は、シリーズを完了する場合だけでなく、このモジュールで終了する場合にも適用されます。 + +1. Azure サブスクリプションがあることを確認します。必要な場合は、[$200 分のクレジット付きの無料 Azure サブスクリプション][azure-free]や、[$100 分のクレジット付きの Azure for Students][azure-students]などの選択肢があります。 +2. Tailspin Toys の codespace に戻り、ターミナルを開きます。 +3. 開発コンテナーに Azure CLI をインストールします。 + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. `az login` で Azure CLI にサインインし、`az account show` で正しいサブスクリプションを使っていることを確認します。 +5. [Azure Developer CLI][install-azd] バージョン 1.27.1 以降をインストールします。Microsoft Foundry では、ホスト型エージェントのテストとデプロイに `azd` を使います。 + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. `azd auth login` で Azure Developer CLI にサインインし、`azd config show` で正しいサブスクリプションを使っていることを確認します。 +7. Azure Developer CLI (azd) の Foundry 拡張機能をインストールします。 + + ```bash + azd ext install microsoft.foundry + ``` + +8. コマンド パレットから、新しい Copilot CLI セッションを横に開きます。Command+Shift+P (Mac) または Ctrl+Shift+P (Windows/Linux) を押し、**Chat: New Copilot CLI session to the side** を選択します。 +9. Azure Skills マーケットプレースを追加します。この操作が必要なのは、プラグインを初めてインストールするときだけです。 + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. [Azure Skills Plugin][azure-skills] をインストールします。このプラグインは、Azure スキル、Azure MCP Server、Foundry MCP Server を GitHub Copilot CLI に追加します。 + + ```text + /plugin install azure@azure-skills + ``` + +11. プラグインによって Azure MCP サーバーが構成されたことを確認します。 + + ```text + /mcp list + ``` + +12. スキルや MCP サーバーが表示されない場合は、`/skills reload` または `/restart` を試し、再度確認します。 + +スキルは Copilot にワークフローを教え、MCP サーバーは Azure リソースの確認や操作を可能にします。 + +## 作業用ブランチを準備する + +前の演習で、ほかの機能ブランチを作成してプッシュしている場合があります。エージェントの作業を分離するため、このオプション シリーズは最新の `main` ブランチから始めます。 + +1. シェルのターミナルで `main` に切り替え、最新の変更をプルし、Backer Concierge 用のブランチを作成します。 + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## カタログをエクスポートする + +エージェントには、読み取り可能なファイル形式のカタログが必要です。Tailspin Toys のサンプルには、このためのテスト済みエクスポート スクリプトが含まれています。 + +1. Copilot CLI に戻り、次を入力します。 + + ```text + 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 は、次と同等のコマンドを実行するはずです。 + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![カタログのエクスポート結果の概要](../../../_images/cli-8-export-db-catalog.png) + +2. `db/catalog.json` を開きます。21 個のゲームが含まれ、それぞれにタイトル、説明、カテゴリ、パブリッシャー、星評価があることを確認します。`note` フィールドには、カタログに資金調達総額、支援者数、支援プラン、発売日が含まれないと記載されています。価格、プレイ人数、プレイ時間のフィールドもありません。こうした情報の欠如が、エージェントが守るべき境界を定めます。 + +## Foundry での作業を計画する + +Copilot が Azure リソースを作成したり、エージェントのコードを追加したりする前に、プラン モードで予定するワークフローを明確にします。 + +1. 次のプロンプトを入力します。 + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. 提案された計画を確認します。Copilot が `microsoft-foundry` スキルを使う予定であり、ホスト型エージェントを既存の Astro アプリケーションから分離していることを確認します。懸念事項や予想外の内容があれば、進める前に修正を依頼してください。 +3. 方針に納得できたら、プラン モードを終了します。 + +## Foundry プロジェクトとモデルをセットアップする + +エージェントには Foundry プロジェクトとデプロイ済みのモデルが必要です。Microsoft Foundry Skill を使い、サブスクリプション内の現在の提供状況とクォータに基づいて選択します。 + +1. Copilot にプロジェクトの作成を依頼します。リソースの作成を承認する前に、選択したサブスクリプション、リージョン、クォータ、推定コストを確認します。 + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![パブリックな Foundry プロジェクトを作成する](../../../_images/cli-8-create-foundry-project.png) + +2. プロジェクトの準備ができたら、Copilot にモデルの提案を依頼します。 + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + Copilot から、推奨された選択肢の中からモデルを選ぶよう求められる場合があります。 + + ![推奨された選択肢の中からモデルを選択する](../../../_images/cli-8-select-foundry-model.png) + + 以降の手順では `gpt-5.4-mini` を使いますが、提供状況とクォータはリージョンによって異なります。 + +3. 推奨された選択肢からモデルを選び、Copilot に選択したモデルのデプロイを依頼します。デプロイを承認する前に、容量とコストを確認します。 + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![選択したモデルをデプロイする](../../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> モデルの提供状況は変わります。適切なのは、例に固定で指定されたモデルではなく、プロジェクトで利用可能だと Copilot が確認したモデルです。 + +## デプロイ済みのモデルをテストする + +ホスト型エージェントを構築する前に、モデルが Backer Concierge のグラウンディング（根拠となる情報に基づいて回答すること）のルールを守るかテストします。エージェントのコードや構成は使わず、予定している指示とカタログのコンテキストでテストします。 + +まず、サインイン中のアカウントに、モジュール 2 でのホスト型エージェント開発用の **Foundry Project Manager** ロールと、モデルを直接呼び出して推論するための **Cognitive Services OpenAI User** ロールを付与します。その後、カタログに含まれない情報も要求する、カタログに関する質問をします。 + +1. 新しいターミナルを開き、アカウント、プロジェクト、ユーザーの値を設定します。`` は、プロジェクト作成時に表示された Foundry アカウント名に置き換えます。 + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. **Foundry Project Manager** ロールを割り当てます。 + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. **Cognitive Services OpenAI User** ロールを割り当てます。 + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. Copilot CLI に戻り、次を入力します。 + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![カタログに実在するゲームを勧め、資金調達データがないことを伝える Foundry モデルの回答](../../../_images/cli-8-foundry-agent-response.png) + +5. 回答を確認します。カタログに実在するゲームだけを勧め、カタログの正しい詳細を使い、資金調達に関する情報がないことを説明している必要があります。モデルがタイトル、ゲームの詳細、資金調達総額を作り上げた場合は、続行する前に別の推奨モデルと比較してください。 + +> [!NOTE] +> このテストは、一時的な指示とカタログのコンテキストを使って、デプロイ済みのモデルだけをテストするものです。エージェントのテストではありません。モジュール 2 では、ひな形を作成した後にテストを繰り返し、ホスト型エージェントのコード、パッケージ化、会話の動作を検証します。 + +## まとめと次のステップ + +Azure ツールを準備し、カタログをエクスポートして、デプロイ済みのモデルが Backer Concierge のグラウンディング ルールに従うかテストしました。このモジュールのチェックポイントは、不足している情報を作り上げずに、カタログに実在するゲームを勧めるモデルです。 + +次は、同じリポジトリ、`foundry-agent-cli` ブランチ、Copilot CLI セッション、Foundry プロジェクト、選択したモデルのデプロイを使って、[エージェントを構築してデプロイします][next-lesson]。ここで終了する場合は、継続的なコストを避けるために [Azure リソースをクリーンアップしてください][cleanup]。 + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#リソースをクリーンアップする +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/ja-jp/cli/8-foundry-agent/2-build-and-deploy.md b/docs/ja-jp/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..dc332692 --- /dev/null +++ b/docs/ja-jp/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "モジュール 2 - エージェントを構築してデプロイする" +description: "GitHub Copilot CLI と Microsoft Foundry Skill を使って Backer Concierge のひな形を作成し、テストしてデプロイします。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +[モジュール 1][previous-lesson]では、カタログを準備し、デプロイ済みのモデルをテストしました。[コンシェルジュを作るオプション シリーズ][overview]の 2 番目のモジュールでは、その土台をホスト型エージェントに発展させます。 + +このモジュールでは、次の内容に取り組みます。 + +- デプロイ可能な専用のカタログ コピーを含むエージェントのひな形を作成する。 +- グラウンディングと会話の継続性をローカルでテストする。 +- エージェントをデプロイし、リモートで呼び出す。 + +## シナリオ + +Tailspin Toys が必要としているのは、モデルからの 1 回限りの回答だけではありません。支援者は、コンシェルジュが直前に勧めたゲームを覚えていて、それらに関する追加の質問に答えることを期待しています。また、コンシェルジュを開発者のマシンからホスト型サービスに移しても、回答の信頼性を維持する必要があります。 + +## 既存のプロジェクトで続ける + +このモジュールは、モジュール 1 で動作を確認したモデルを引き継ぎます。別の Azure リソース一式を作成するのではなく、同じプロジェクトとデプロイを使い続けます。 + +1. `foundry-agent-cli` ブランチの Tailspin Toys リポジトリと、モジュール 1 の Copilot CLI セッションに戻ります。 +2. `db/catalog.json` が利用でき、モデルのテストで使った Foundry プロジェクト、選択したモデルのデプロイ、Azure のサインインが引き続き利用できることを確認します。セットアップが未完了の場合は、先に[プロジェクトとモデルを準備する][previous-lesson]を完了してください。 + +> [!IMPORTANT] +> ホスト型エージェントはパブリック プレビューであり、課金対象の Azure リソースを作成します。このモジュールで終了する場合も、[クリーンアップの手順][cleanup]に従ってください。 + +## Backer Concierge エージェントのひな形を作成する + +Microsoft Foundry Skill に、既存の Tailspin Toys リポジトリ内でホスト型エージェントのひな形を作成するよう依頼し、実行する前にパッケージ化と構成を確認します。 + +1. Copilot CLI に次のプロンプトを入力します。 + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. セッションを確認し、Foundry プロジェクト、モデルのデプロイ、エージェント名、環境に関する質問に答えます。 +3. Copilot の作業が終わったら、変更を確認します。 + + ```text + /diff + ``` + + 次の点を確認します。 + + - `azure.yaml` に `host: azure.ai.agent` のサービスが含まれている。 + - サービスが `agent/backer-concierge` を参照している。 + - デプロイするサービス パッケージに、自動生成された専用のカタログ コピーが含まれている。 + - 手作業で編集する 2 つのカタログを管理するのではなく、1 つのスクリプトまたはビルド手順で `db/catalog.json` からコピーを更新している。 + - エージェントが、選択したモデルのデプロイと Responses API を使っている。 + - 指示の中で、カタログに存在しない事実を明示的に拒否している。 + - 資格情報、アクセス トークン、`.env` ファイル、`.azure` 環境ファイルがコミット対象としてステージングされていない。 + + ひな形作成後のチェックポイントとして、次の構成を確認します。 + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy` は、ホスト型エージェントのサービス ディレクトリをパッケージ化します。実行時に `agent/backer-concierge` からリポジトリ レベルの `db/catalog.json` を参照すると、ローカルでは動いてもデプロイ後に失敗する可能性があります。生成されたコピーは、デプロイ前に `agent/backer-concierge/` ディレクトリ内で利用できる必要があります。 + +4. サービスを起動する前に、対象を絞ったテストを実行し、生成された構成を確認するよう Copilot に依頼します。 + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + 対象を絞ったテストがすべて成功するまでは、先に進まないでください。 + + ![生成されたエージェントのひな形を検証する](../../../_images/cli-8-verify-generated-agent.png) + +## エージェントをローカルでテストする + +ローカルの Responses API を通じて、エージェントのグラウンディングと会話の動作を確認します。ローカルのエージェント サービスは実行中にターミナルを占有するため、現在のターミナルでは Copilot CLI を開いたままにし、2 つ目のターミナルからエージェントを起動します。 + +1. Ctrl+\` を使って、別のターミナルを開きます。 +2. Tailspin Toys リポジトリのルートから、次を実行します。 + + ```bash + azd ai agent run + ``` + + ローカルでの初回実行では、Python 環境を作成し、依存関係をインストールして、ホスト型エージェントを起動します。このターミナルは実行したままにします。 + +3. 最初のターミナルの Copilot CLI に戻り、次を入力します。 + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![ホスト型エージェントのデプロイに向けたテストの成功結果](../../../_images/cli-8-passing-acceptance-scenarios.png) + +4. 結果を確認します。エージェントに接続できない場合は、2 つ目のターミナルでサービスがまだ実行中であることを確認します。テストが失敗した場合は、ローカルの不具合だけを修正し、対象を絞ったテストを実行して、`azd ai agent run` の再起動が必要なタイミングを知らせるよう Copilot に依頼します。変更するたびにサービスを再起動し、失敗した受け入れテストを再実行します。 + +## ホスト型エージェントをデプロイする + +ローカルの受け入れテストが成功したら、エージェントを Microsoft Foundry にデプロイする準備が整います。同じスキル主導のワークフローで、デプロイの準備状況を確認し、リモート エンドポイントをテストします。 + +1. すべての受け入れテストが成功したら、Ctrl+C でローカル サービスを停止します。 +2. Copilot CLI に戻り、次のプロンプトを入力します。デプロイを承認する前に、提案されたリソースと推定コストを確認してください。 + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. 評価スイートのソースを選ぶよう求められた場合は、**No, set it up later** を選択します。 + + ![ホスト型エージェントのデプロイ状況とプレイグラウンドへのリンク](../../../_images/cli-8-hosted-agent-deployment.png) + +4. デプロイ状況とリモートからの回答を確認します。エージェントが実行中であり、カタログに実在するゲームだけを勧めていることを確認します。デプロイまたは呼び出しが失敗した場合は、続行する前に、Copilot に原因の診断を依頼してリモート テストを繰り返します。 + +表示されたプレイグラウンドのリンクから、Microsoft Foundry ポータルでデプロイ済みのホスト型エージェントと対話できます。 + +スキル主導のワークフローは、`azd deploy` でサービスのソースをパッケージ化し、依存関係を解決してリモートでビルドし、Microsoft Foundry に公開します。デプロイ済みのエンドポイントのテストには、Foundry の呼び出しワークフローを使います。 + +## まとめと次のステップ + +デプロイ可能なカタログ コピーを含むエージェントのひな形を作成し、グラウンディングと会話の継続性をテストして、Microsoft Foundry からのリモートの回答を検証しました。これで、正常に動作するホスト型の Backer Concierge が完成しました。 + +次は、同じリポジトリ、ブランチ、Copilot CLI セッション、デプロイ済みのエージェントを使って、[コンシェルジュを Web サイトに接続します][next-lesson]。ホスト型エージェントを試すだけで十分な場合は、ここで終了して [Azure リソースをクリーンアップできます][cleanup]。 + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#リソースをクリーンアップする diff --git a/docs/ja-jp/cli/8-foundry-agent/3-connect-to-site.md b/docs/ja-jp/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..60ba3160 --- /dev/null +++ b/docs/ja-jp/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "モジュール 3 - エージェントを Web サイトに接続する" +description: "ローカルの Azure Functions プロキシとアクセシブルなチャット ウィジェットを通じて、ホスト型の Backer Concierge を Tailspin Toys に接続します。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +[モジュール 2][previous-lesson]では、Backer Concierge をデプロイしてテストしました。[コンシェルジュを作るオプション シリーズ][overview]の最後のモジュールでは、そのエージェントをローカルの Tailspin Toys Web サイトから利用できるようにします。 + +このモジュールでは、次の内容に取り組みます。 + +- Foundry の資格情報をサーバー内に保持する、ローカルの Azure Functions プロキシを構築する。 +- アクセシブルなチャット ウィジェットをサイトに追加する。 +- 会話の一連の流れを検証し、リソースをクリーンアップする。 + +## シナリオ + +支援者がゲームを見つけるのは、開発者のターミナルや Azure ポータルではなく、Tailspin Toys の Web サイトです。チームは、カタログと並べてコンシェルジュを提供したいと考えています。チャットは追加の質問に対応し、サービスの資格情報を保護する必要があります。 + +## ホスト型エージェントを引き続き使う + +Web サイトとの統合には、モジュール 2 でデプロイしたエージェントが必要です。エージェントは Foundry で実行したままにし、プロキシと Web サイトをローカルで実行します。 + +1. `foundry-agent-cli` ブランチの Tailspin Toys リポジトリと、既存の Copilot CLI セッションに戻ります。 +2. Backer Concierge がデプロイされており、[エージェントを構築してデプロイする][previous-lesson]でのリモート呼び出しが成功したことを確認します。Azure リソースをすでに削除した場合は、前のモジュールの手順で再作成してから続行してください。 + +> [!IMPORTANT] +> このモジュールのプロキシと Web サイトはローカルで実行します。本番 Web サイトのデプロイではありません。[クリーンアップ][cleanup]を完了するまで、モデルとホスト型エージェントは課金対象の Azure リソースのままです。 + +## サーバー側プロキシを構築する + +Tailspin Toys は、すべて事前レンダリングされています。ブラウザーのコードからホスト型エージェントを直接呼び出したり、ブラウザーで Foundry の資格情報を受け取ったりしてはいけません。ローカルの Azure Functions を追加し、**サーバー側で資格情報を隔離する境界**にします。これにより、Foundry への認証を行い、エージェントの回答だけをブラウザーに返します。 + +`microsoft-foundry` スキルはホスト型エージェントのワークフローを担当し、同じプラグインに含まれる、より広範な Azure スキルはローカルの Function プロジェクトを準備できます。それらのスキルでプロキシを構築し、資格情報を公開せずにエージェントに接続できることを確認します。 + +1. Copilot CLI で、次を入力します。 + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Azure Functions ローカル プロキシのセットアップ](../../../_images/cli-8-azure-functions-proxy.png) + +2. 別のターミナルを開き、Copilot が提示したコマンドでローカルの Function を起動します。Function は実行したままにします。 +3. Copilot CLI に戻り、ローカル プロキシをテストするよう Copilot に依頼します。 + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. 回答を確認します。カタログには価格が含まれないことを説明している必要があります。Foundry のトークン、資格情報、プロジェクトのエンドポイント、Foundry の会話識別子そのもの、スタック トレースが含まれていてはいけません。 + + ![ローカルのコンシェルジュ エンドポイントから返された、機密情報を除去済みの JSON レスポンス](../../../_images/cli-8-sanitized-json-response.png) + +## チャット ウィジェットを構築する + +プロキシにより、ブラウザーからコンシェルジュに安全に接続できます。次に、サイトにチャット ウィジェットを追加し、Playwright で会話の一連の流れを確認します。 + +1. Copilot にサイトとの統合を依頼します。 + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. ローカルの Function は実行したままにして、別のターミナルで Copilot が提示したコマンドを使い、Astro サイトを起動します。 +3. Copilot CLI に戻ります。[演習 4][playwright-lesson]で追加した Playwright MCP サーバーは、すでに利用できます。Copilot にウィジェットのテストを依頼します。 + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Tailspin Toys サイト内の Backer Concierge ウィジェットのスクリーンショット](../../../_images/cli-8-backer-concierge-widget.png) + +4. 報告された根拠と照らし合わせて結果を確認します。失敗したチェックがある場合は、関連するプロキシやウィジェットの動作を修正するよう Copilot に依頼し、失敗したチェックを再実行してから終了してください。 + +## リソースをクリーンアップする + +最終チェックポイントに到達しました。ローカルの Web サイトでコンシェルジュが動作しています。共通のクリーンアップ手順は、シリーズ全体で作成したローカル サービスと Azure リソースの両方を対象としています。 + +1. [リソースをクリーンアップする][cleanup]の手順を完了します。ローカル サービスを停止し、Azure リソースの削除が完了したことの確認も含めて実施してください。 + +## まとめと次のステップ + +ローカルのサーバー側プロキシとアクセシブルなチャット ウィジェットを通じて、ホスト型の Backer Concierge を Tailspin Toys に接続しました。シリーズ全体を通じて、GitHub Copilot CLI と Foundry を使い、モデルの準備、エージェントの構築とデプロイ、Web サイトとの統合全体の検証に取り組みました。 + +CLI ワークショップを締めくくるために、[振り返りと次のステップ][review]に進みます。 + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#リソースをクリーンアップする diff --git a/docs/ja-jp/cli/8-foundry-agent/README.md b/docs/ja-jp/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..07d0f032 --- /dev/null +++ b/docs/ja-jp/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: ja-jp/cli/8-foundry-agent +title: "オプション: Foundry を組み込む" +description: "モデルを準備し、カタログに基づくエージェントを構築してデプロイし、Tailspin Toys に接続する全 3 モジュールのシリーズです。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +このオプション シリーズでは、GitHub Copilot CLI と Microsoft Foundry Skill を使って、Tailspin Toys のカタログを会話型アシスタントに変えます。3 つのモジュールを通じて、プロジェクトとモデルのセットアップから、ホスト型エージェントの作成、実際に動作する Web サイトとの統合まで進めます。 + +このシリーズでは、次の内容に取り組みます。 + +- Azure 環境を準備し、カタログを使ってモデルをテストする。 +- ホスト型の Backer Concierge エージェントのひな形を作成し、テストしてデプロイする。 +- ローカルのサーバー側プロキシとチャット ウィジェットを通じて、エージェントを Web サイトに接続する。 + +## シナリオ + +Tailspin Toys の支援者はカテゴリやパブリッシャーでゲームを探せますが、それらのフィルターだけでは、誰もが次に遊ぶゲームを見つけられるとは限りません。たとえば、*Git の言葉遊びが好きな人には、どのゲームが向いているだろう？*と考える支援者もいます。こうした質問には、ドロップダウンの選択肢だけでは答えられません。 + +Tailspin Toys は、会話を通じて支援者がゲームを見つけられる **Backer Concierge** を求めています。Tailspin のカタログからゲームを勧め、好みが曖昧な場合は短い確認の質問を 1 つ行い、追加の質問を受けたときには以前のおすすめを覚えている必要があります。 + +支援者には信頼できる回答が必要です。コンシェルジュはカタログにある情報だけを使い、詳細が不明な場合はそのことを明確に伝える必要があります。ゲーム、パブリッシャー、評価、資金調達総額、支援者数、価格、プレイ人数、プレイ時間、発売日を作り上げてはいけません。 + +## 次のステップを選ぶ + +各モジュールは、同じ Tailspin Toys リポジトリ、ブランチ、Foundry プロジェクトで前のモジュールの成果を引き継ぎます。それぞれ、実際に動作する状態まで完成させて終了します。 + +| モジュール | 取り組む内容 | 完了時の状態 | +| --- | --- | --- | +| [1. プロジェクトとモデルを準備する][project-model] | ツールをセットアップし、カタログをエクスポートして、モデルを選択してテストする | カタログに関する質問に正しく答える、デプロイ済みのモデル | +| [2. エージェントを構築してデプロイする][build-deploy] | エージェントのひな形を作成し、動作をテストして Foundry にデプロイする | 正常に動作するホスト型の Backer Concierge | +| [3. エージェントを Web サイトに接続する][connect-site] | ローカルのプロキシとチャット ウィジェットを構築し、一連の流れをテストする | ローカルの Web サイトから利用できるコンシェルジュ | + +> [!IMPORTANT] +> Microsoft Foundry のホスト型エージェントはパブリック プレビューです。 +> +> このシリーズでは、モデルのデプロイやホスト型エージェントなど、課金対象の Azure リソースを作成します。リソースを作成する前に、選択したサブスクリプション、リージョン、クォータ、推定コストを確認する必要があります。最初または 2 番目のモジュールで終了する場合も、[クリーンアップの手順][cleanup]に従ってください。 + +1. オプション シリーズを始めるには、[プロジェクトとモデルを準備する][project-model]に進みます。セットアップの手順も含まれています。 +2. 中核となるワークショップを終えたい場合は、[振り返りと次のステップ][review]に進みます。 + +## リソースをクリーンアップする + +どのチェックポイントで試行を終える場合も、不要なコストを避けるために Azure リソースを削除してください。クリーンアップでは後続のモジュールに必要なリソースも削除するため、その後に続行するにはリソースを再作成する必要があります。 + +> [!CAUTION] +> `rg-tailspin-toys` を削除してよいのは、この演習専用であり、保持する必要のあるリソースが含まれていない場合だけです。共有リソース グループを削除すると、無関係のリソースも削除されます。 + +1. 起動したローカルのエージェント、Function、Astro 開発サーバーがある場合は、それぞれのターミナルで Ctrl+C を押して停止します。 +2. Copilot CLI を終了します。モジュール 2 でエージェントのひな形を作成した場合は、同じ `azd` 環境を使い、Tailspin Toys リポジトリのルートから次を実行します。 + + ```bash + azd down --purge + ``` + +3. `az account show` で選択中のサブスクリプションを確認します。そのサブスクリプションの `rg-tailspin-toys` を調べ、残っているリソースがすべてこの演習に属することを確認します。モジュール 1 で終了した場合は、`azd` サービスのひな形をまだ作成していなくても、Foundry プロジェクトとモデルをクリーンアップする必要があります。 +4. ワークショップ専用のリソース グループがまだ存在し、削除する予定のリソースだけが含まれている場合は、次を実行します。 + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Azure ポータルで、リソース グループの削除が完了したことを確認します。`--no-wait` を指定したコマンドは、削除が完了する前に戻ります。 + +## リソース + +- [Azure Skills Plugin][azure-skills] +- [コーディング エージェントで Microsoft Foundry Skill を使う][foundry-skill] +- [Microsoft Foundry Skill で最初のホスト型エージェントをデプロイする][hosted-agent-quickstart] +- [ホスト型エージェントのアクセス許可][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #リソースをクリーンアップする +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/ja-jp/cli/9-review.md b/docs/ja-jp/cli/9-review.md index 71baaadf..120c1cce 100644 --- a/docs/ja-jp/cli/9-review.md +++ b/docs/ja-jp/cli/9-review.md @@ -1,5 +1,5 @@ --- -title: "演習 8 - 振り返りと次のステップ" +title: "演習 9 - 振り返りと次のステップ" authors: - geektrainer lastUpdated: 2026-06-30 @@ -13,6 +13,8 @@ lastUpdated: 2026-06-30 - custom agent を呼び出して、より高度で複雑なタスクに対応する。 - slash command を使ってセッションを管理し、必要に応じて `/delegate` で cloud agent に橋渡しする。 +任意の追加課題に挑戦したい場合は、全 3 モジュールのシリーズで[GitHub Copilot CLI と Foundry を使ったコンシェルジュの構築][foundry-lesson]に取り組めます。モデルのセットアップ、エージェントの開発とデプロイ、Web サイトとの統合を学びます。 + ここでは、いくつかの slash command、ベスト プラクティス、次のステップについて確認します。 ## slash command @@ -61,6 +63,7 @@ GitHub Copilot エコシステムをさらに試してみたい場合は、[VS C - [MCP 仕様][mcp-spec] [previous-lesson]: ../7-slash-commands/ +[foundry-lesson]: ../8-foundry-agent/ [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli [using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli [awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/ja-jp/cli/README.md b/docs/ja-jp/cli/README.md index cf98f744..ff02387f 100644 --- a/docs/ja-jp/cli/README.md +++ b/docs/ja-jp/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 **[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** は、ターミナルで GitHub Copilot をエージェント型のコーディング アシスタントとして利用できるようにします。コードベースを探索し、コードを生成し、コマンドを実行し、外部ツールに接続できます。すべてコマンド ラインから行えるため、グラフィカル エディターに切り替えずに作業の流れを保てます。 -これらの演習では、Copilot CLI のインストールと認証から始め、カスタム命令でプロジェクトのコンテキストを与えたうえで、プラン モードを使って意図的に機能を実装します。続いて Playwright MCP サーバーを接続し、実際のブラウザーでその機能をテストします。その後、再利用可能な agent skill と custom agent で Copilot を拡張します。最後に、コンテキスト管理、モデル選択、共有に使う slash command を確認し、作成した内容を振り返ります。 +これらの演習では、Copilot CLI のインストールと認証から始め、カスタム命令でプロジェクトのコンテキストを与えたうえで、プラン モードを使って意図的に機能を実装します。続いて Playwright MCP サーバーを接続し、実際のブラウザーでその機能をテストします。その後、再利用可能な agent skill と custom agent で Copilot を拡張します。最後に、コンテキスト管理、モデル選択、共有に使う slash command を確認し、作成した内容を振り返ります。また、[GitHub Copilot CLI と Foundry を使う全 3 モジュールのオプション シリーズ][foundry]では、モデルを準備し、ホスト型エージェントを構築してデプロイし、サイトに統合できます。 ## 演習 @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. エージェント スキル][ex5] | スキル | 専門スキルで Copilot を強化する | | [6. カスタム エージェント][ex6] | エージェント | カスタム エージェントを確認して使用する | | [7. スラッシュ コマンド][ex7] | CLI 機能 | コンテキスト、モデル、共有、cloud agent への任意の委任を確認する | -| [8. Backer Concierge AI エージェントの構築 (オプション)][foundry] | ホスト型エージェント | カタログに基づいた Backer Concierge を構築してデプロイする | | [9. 振り返り][ex9] | まとめ | 重要な概念と次のステップを確認する | +| [オプション: Foundry を組み込む][foundry] | ホスト型エージェント | モデルを準備し、カタログに基づいた Backer Concierge を構築してデプロイし、Web サイトに接続する | ## 前提条件 diff --git a/docs/ko-kr/cli/7-slash-commands.md b/docs/ko-kr/cli/7-slash-commands.md index 088c5be3..377a0f0a 100644 --- a/docs/ko-kr/cli/7-slash-commands.md +++ b/docs/ko-kr/cli/7-slash-commands.md @@ -156,7 +156,7 @@ Copilot CLI의 slash commands를 사용하면 구성을 변경하고, 세션을 - `/model`로 사용 가능한 모델 목록을 살펴보고 원한다면 새 모델을 선택할 수 있음을 확인했습니다. - `/delegate`를 cloud agent로 연결하는 선택적 브리지로 학습했습니다. -물론 더 많은 slash commands가 있으며, Copilot CLI로 탐색할 내용도 더 많습니다. 더 나아가고 싶다면, [선택적 Microsoft Foundry 레슨][foundry-lesson]에서 Tailspin 카탈로그 위에 호스트된 에이전트를 빌드하는 방법을 안내합니다. 그렇지 않다면, 마지막으로 [학습한 내용을 검토하고][next-lesson] 학습을 계속하기 위한 다음 단계를 살펴보며 여정을 마무리하겠습니다. +물론 더 많은 slash commands가 있으며, Copilot CLI로 탐색할 내용도 더 많습니다. 마지막으로 [학습한 내용을 검토하고][next-lesson] 학습을 계속하기 위한 다음 단계를 살펴보며 여정을 마무리하겠습니다. 마무리하기 전에 선택 과제에 도전하고 싶다면, 3개 모듈로 구성된 시리즈에서 [GitHub Copilot CLI와 Foundry로 컨시어지 빌드하기][foundry-lesson]를 진행할 수 있습니다. ## 리소스 diff --git a/docs/ko-kr/cli/8-foundry-agent/1-project-and-model.md b/docs/ko-kr/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..04107bd3 --- /dev/null +++ b/docs/ko-kr/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "모듈 1 - 프로젝트와 모델 준비하기" +description: "Azure 도구를 설정하고, Tailspin 카탈로그를 내보낸 뒤 GitHub Copilot CLI로 Foundry 모델을 선택하고 테스트합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +이 모듈은 [선택 사항: Foundry 통합하기][overview]의 첫 번째 모듈입니다. 도구와 카탈로그를 준비한 뒤, 에이전트를 빌드하기 전에 Copilot을 사용해 Foundry 프로젝트를 만들고 배포된 모델을 테스트합니다. + +이 모듈에서는 다음을 수행합니다. + +- Azure 명령줄 도구와 Azure Skills Plugin을 설치합니다. +- 카탈로그를 내보내고 Foundry 작업을 계획합니다. +- 모델을 선택하고 배포한 뒤 카탈로그가 제공하는 정보의 범위를 지키는지 테스트합니다. + +## 시나리오 + +Tailspin Toys에는 카탈로그의 사실과 회사가 제공하지 않는 정보를 구분할 수 있는 컨시어지(Concierge)가 필요합니다. 유용한 추천이라면 평점이 높은 퍼즐 게임을 소개할 수 있지만, 그 게임의 총 모금액을 지어내서는 안 됩니다. 완전한 도우미를 만드는 데 투자하기 전에, 팀은 선택한 모델이 이러한 경계를 지킬 수 있는지 확인하고자 합니다. + +## 사전 준비 및 설정 + +Azure를 사용해 Backer Concierge를 호스팅하고 Copilot CLI로 작업을 진행합니다. 먼저 Copilot이 Azure 리소스를 다룰 수 있도록 명령줄 도구와 플러그인을 준비합니다. + +> [!IMPORTANT] +> [정리 지침][cleanup]은 시리즈를 모두 마친 경우뿐 아니라 이 모듈을 마친 뒤 중단하는 경우에도 적용됩니다. + +1. Azure 구독이 있는지 확인합니다. 구독이 필요하다면 [$200 크레딧이 포함된 무료 Azure 구독][azure-free] 또는 [$100 크레딧이 포함된 Azure for Students][azure-students] 등의 옵션을 사용할 수 있습니다. +2. Tailspin Toys 코드스페이스로 돌아가 터미널을 엽니다. +3. 개발 컨테이너에 Azure CLI를 설치합니다. + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. `az login`으로 Azure CLI에 로그인하고 `az account show`로 올바른 구독을 사용 중인지 확인합니다. +5. [Azure Developer CLI][install-azd] 버전 1.27.1 이상을 설치합니다. Microsoft Foundry는 `azd`를 사용해 호스트된 에이전트를 테스트하고 배포합니다. + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. `azd auth login`으로 Azure Developer CLI에 로그인하고 `azd config show`로 올바른 구독을 사용 중인지 확인합니다. +7. Azure Developer CLI(azd) Foundry 확장을 설치합니다. + + ```bash + azd ext install microsoft.foundry + ``` + +8. 명령 팔레트에서 새 Copilot CLI 세션을 옆에 엽니다. Command+Shift+P(Mac) 또는 Ctrl+Shift+P(Windows/Linux)를 누른 뒤 **Chat: New Copilot CLI session to the side**를 선택합니다. +9. Azure Skills 마켓플레이스를 추가합니다. 플러그인을 처음 설치할 때만 이 작업이 필요합니다. + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. [Azure Skills Plugin][azure-skills]을 설치합니다. 이 플러그인은 Azure 스킬, Azure MCP Server, Foundry MCP Server를 GitHub Copilot CLI에 추가합니다. + + ```text + /plugin install azure@azure-skills + ``` + +11. 플러그인이 Azure MCP 서버를 구성했는지 확인합니다. + + ```text + /mcp list + ``` + +12. 스킬이나 MCP 서버가 표시되지 않으면 `/skills reload` 또는 `/restart`를 실행한 뒤 다시 확인합니다. + +스킬은 Copilot에 작업 흐름을 알려 주고, MCP 서버는 Copilot이 Azure 리소스를 살펴보고 다룰 수 있도록 합니다. + +## 작업 브랜치 준비하기 + +이전 연습에서 다른 기능 브랜치를 만들고 푸시했을 수 있습니다. 에이전트 작업을 별도로 유지하도록 최신 `main` 브랜치에서 이 선택 사항 시리즈를 시작합니다. + +1. 셸 터미널에서 `main`으로 전환하고 최신 변경 사항을 가져온 뒤 Backer Concierge용 브랜치를 만듭니다. + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## 카탈로그 내보내기 파일 생성하기 + +에이전트가 읽을 수 있도록 카탈로그를 파일로 제공해야 합니다. Tailspin Toys 샘플에는 이를 위한 검증된 내보내기 스크립트가 포함되어 있습니다. + +1. Copilot CLI로 돌아가 다음을 입력합니다. + + ```text + 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은 다음에 해당하는 명령을 실행해야 합니다. + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![카탈로그 내보내기 요약](../../../_images/cli-8-export-db-catalog.png) + +2. `db/catalog.json`을 엽니다. 제목, 설명, 카테고리, 퍼블리셔, 별점이 있는 게임 21개가 포함되어 있는지 확인합니다. `note` 필드에는 카탈로그에 총 모금액, 후원자 수, 후원 등급, 출시일이 없다고 명시되어 있습니다. 가격, 플레이어 수, 플레이 시간 필드도 없습니다. 이러한 누락 항목이 에이전트가 지켜야 할 정보의 경계를 정의합니다. + +## Foundry 작업 계획하기 + +Copilot이 Azure 리소스를 만들거나 에이전트 코드를 추가하기 전에, 계획 모드(Plan mode)를 사용해 예정된 작업 흐름을 확인합니다. + +1. 다음 프롬프트를 입력합니다. + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. 제안된 계획을 검토합니다. Copilot이 `microsoft-foundry` 스킬을 사용하려는지, 호스트된 에이전트를 기존 Astro 애플리케이션과 분리하는지 확인합니다. 우려되거나 예상과 다른 부분이 있으면 진행하기 전에 수정을 요청합니다. +3. 접근 방식이 만족스러우면 계획 모드를 종료합니다. + +## Foundry 프로젝트와 모델 설정하기 + +에이전트에는 Foundry 프로젝트와 배포된 모델이 필요합니다. Microsoft Foundry Skill을 사용해 구독 내 현재 가용성과 할당량을 기준으로 선택합니다. + +1. Copilot에 프로젝트 생성을 요청합니다. 리소스 생성을 승인하기 전에 선택한 구독, 지역, 할당량, 예상 비용을 확인합니다. + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![공개 Foundry 프로젝트 생성하기](../../../_images/cli-8-create-foundry-project.png) + +2. 프로젝트가 준비되면 Copilot에 모델 추천을 요청합니다. + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + Copilot이 추천 옵션 중에서 모델을 선택하도록 요청할 수 있습니다. + + ![추천 옵션 중에서 모델 선택하기](../../../_images/cli-8-select-foundry-model.png) + + 나머지 단계에서는 `gpt-5.4-mini`를 사용하지만, 가용성과 할당량은 지역에 따라 다릅니다. + +3. 추천 옵션 중에서 모델을 선택한 뒤 Copilot에 선택한 모델의 배포를 요청합니다. 배포를 승인하기 전에 용량과 비용을 검토합니다. + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![선택한 모델 배포하기](../../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> 모델 가용성은 시간이 지남에 따라 달라집니다. 예제에 하드코딩된 모델이 아니라, Copilot이 프로젝트에서 사용할 수 있다고 확인한 모델을 선택하는 것이 올바른 방법입니다. + +## 배포된 모델 테스트하기 + +호스트된 에이전트를 빌드하기 전에 모델이 Backer Concierge의 그라운딩(Grounding) 규칙을 따르는지 테스트합니다. 에이전트 코드나 구성 없이, 사용할 지침과 카탈로그 컨텍스트로 테스트합니다. + +먼저 로그인한 계정에 모듈 2의 호스트된 에이전트 개발을 위한 **Foundry Project Manager** 역할과 직접 모델 추론을 위한 **Cognitive Services OpenAI User** 역할을 부여합니다. 그런 다음 카탈로그에 없는 정보도 함께 요청하는 카탈로그 질문을 합니다. + +1. 새 터미널을 열고 계정, 프로젝트, 사용자 값을 설정합니다. ``을 프로젝트 생성 시 안내받은 Foundry 계정 이름으로 바꿉니다. + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. **Foundry Project Manager** 역할을 할당합니다. + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. **Cognitive Services OpenAI User** 역할을 할당합니다. + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. Copilot CLI로 돌아가 다음을 입력합니다. + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![실제 카탈로그 게임을 추천하고 모금 데이터가 없다고 안내하는 Foundry 모델 응답](../../../_images/cli-8-foundry-agent-response.png) + +5. 응답을 검토합니다. 카탈로그에 실제로 있는 게임만 추천하고, 올바른 카탈로그 정보를 사용하며, 모금 정보를 확인할 수 없다고 설명해야 합니다. 모델이 제목, 게임 정보, 총 모금액을 지어낸다면 계속 진행하기 전에 다른 추천 모델과 비교합니다. + +> [!NOTE] +> 이 테스트는 임시 지침과 카탈로그 컨텍스트로 배포된 모델만 테스트합니다. 에이전트를 테스트하는 것은 아닙니다. 모듈 2에서는 스캐폴딩(Scaffolding) 후 이 테스트를 반복해 호스트된 에이전트의 코드, 패키징, 대화 동작을 검증합니다. + +## 요약 및 다음 단계 + +Azure 도구를 준비하고, 카탈로그를 내보내고, 배포된 모델이 Backer Concierge의 그라운딩 규칙을 따르는지 테스트했습니다. 이 모듈의 완료 기준은 누락된 정보를 지어내지 않고 실제 카탈로그 게임을 추천하는 모델입니다. + +다음으로 동일한 리포지토리, `foundry-agent-cli` 브랜치, Copilot CLI 세션, Foundry 프로젝트, 선택한 모델 배포를 사용해 [에이전트를 빌드하고 배포합니다][next-lesson]. 여기서 중단한다면 비용이 계속 발생하지 않도록 [Azure 리소스를 정리합니다][cleanup]. + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#리소스-정리하기 +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/ko-kr/cli/8-foundry-agent/2-build-and-deploy.md b/docs/ko-kr/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..94074d34 --- /dev/null +++ b/docs/ko-kr/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "모듈 2 - 에이전트 빌드 및 배포하기" +description: "GitHub Copilot CLI와 Microsoft Foundry Skill을 사용해 Backer Concierge를 스캐폴드하고 테스트 및 배포합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +[모듈 1][previous-lesson]에서는 카탈로그를 준비하고 배포된 모델을 테스트했습니다. [선택 사항 컨시어지 시리즈][overview]의 두 번째 모듈에서는 이를 바탕으로 호스트된 에이전트(Hosted agent)를 만듭니다. + +이 모듈에서는 다음을 수행합니다. + +- 배포 가능한 자체 카탈로그 사본을 포함하도록 에이전트를 스캐폴드(Scaffold)합니다. +- 로컬에서 그라운딩(Grounding)과 대화 연속성을 테스트합니다. +- 에이전트를 배포하고 원격으로 호출합니다. + +## 시나리오 + +Tailspin Toys에는 모델의 일회성 답변 이상이 필요합니다. 후원자는 컨시어지(Concierge)가 방금 추천한 게임을 기억하고 해당 게임에 대한 후속 질문에 답하기를 기대합니다. 또한 팀은 컨시어지를 개발자 컴퓨터에서 호스트된 서비스로 옮긴 뒤에도 답변의 신뢰성을 유지해야 합니다. + +## 기존 프로젝트에서 계속하기 + +이 모듈은 모듈 1에서 정상적으로 작동한 모델을 기반으로 진행합니다. Azure 리소스를 새로 만들지 않고 동일한 프로젝트와 배포를 유지합니다. + +1. Tailspin Toys 리포지토리의 `foundry-agent-cli` 브랜치와 모듈 1에서 사용한 Copilot CLI 세션으로 돌아갑니다. +2. `db/catalog.json`이 있는지, 모델 테스트에 사용한 Foundry 프로젝트, 선택한 모델 배포, Azure 로그인이 그대로 유지되어 있는지 확인합니다. 설정을 완료하지 않았다면 먼저 [프로젝트와 모델 준비하기][previous-lesson]를 마칩니다. + +> [!IMPORTANT] +> 호스트된 에이전트는 공개 미리 보기 상태이며 요금이 부과되는 Azure 리소스를 만듭니다. 이 모듈을 마친 뒤 중단한다면 [정리 지침][cleanup]을 따라야 합니다. + +## Backer Concierge 에이전트 스캐폴드하기 + +이제 Microsoft Foundry Skill에 기존 Tailspin Toys 리포지토리 안에 호스트된 에이전트를 스캐폴드하도록 요청한 뒤, 실행 전에 패키징과 구성을 살펴봅니다. + +1. Copilot CLI에 다음 프롬프트를 입력합니다. + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. 세션을 살펴보며 Foundry 프로젝트, 모델 배포, 에이전트 이름, 환경에 대한 질문에 응답합니다. +3. Copilot이 작업을 마치면 변경 사항을 살펴봅니다. + + ```text + /diff + ``` + + 다음을 확인합니다. + + - `azure.yaml`에 `host: azure.ai.agent`가 설정된 서비스가 있습니다. + - 서비스 경로가 `agent/backer-concierge`를 가리킵니다. + - 배포되는 서비스 패키지에 자체적으로 생성한 카탈로그 사본이 포함되어 있습니다. + - 카탈로그 두 개를 수동으로 편집하며 유지하는 대신 하나의 스크립트나 빌드 단계가 `db/catalog.json`에서 해당 사본을 갱신합니다. + - 에이전트가 선택한 모델 배포와 Responses API를 사용합니다. + - 지침에서 카탈로그에 없는 사실을 명시적으로 거부합니다. + - 자격 증명, 액세스 토큰, `.env` 파일, `.azure` 환경 파일이 커밋 대상으로 스테이징되어 있지 않습니다. + + 스캐폴딩 후 다음 구조를 기준으로 확인합니다. + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy`는 호스트된 에이전트의 서비스 디렉터리를 패키징합니다. `agent/backer-concierge`에서 리포지토리 수준의 `db/catalog.json`을 런타임에 참조하면 로컬에서는 작동하더라도 배포 후에는 실패할 수 있습니다. 생성된 사본은 배포 전에 `agent/backer-concierge/` 디렉터리에 있어야 합니다. + +4. 서비스를 시작하기 전에 Copilot에 관련 기능에 집중한 테스트를 실행하고 생성된 구성을 살펴보도록 요청합니다. + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + 해당 테스트를 통과하기 전에는 다음으로 진행하지 않습니다. + + ![에이전트 스캐폴딩 검증하기](../../../_images/cli-8-verify-generated-agent.png) + +## 에이전트 로컬 테스트하기 + +이제 로컬 Responses API를 통해 에이전트의 그라운딩과 대화 동작을 확인합니다. 로컬 에이전트 서비스는 실행 중 터미널을 점유하므로, 현재 터미널에는 Copilot CLI를 열어 둔 채 두 번째 터미널에서 에이전트를 시작합니다. + +1. Ctrl+\`를 눌러 다른 터미널을 엽니다. +2. Tailspin Toys 리포지토리 루트에서 다음을 실행합니다. + + ```bash + azd ai agent run + ``` + + 첫 로컬 실행에서는 Python 환경을 만들고, 의존성을 설치하고, 호스트된 에이전트를 시작합니다. 이 터미널을 실행 상태로 둡니다. + +3. 첫 번째 터미널의 Copilot CLI로 돌아가 다음을 입력합니다. + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![호스트된 에이전트 배포 테스트 통과](../../../_images/cli-8-passing-acceptance-scenarios.png) + +4. 결과를 검토합니다. 에이전트에 연결할 수 없다면 두 번째 터미널에서 서비스가 계속 실행 중인지 확인합니다. 테스트가 실패하면 Copilot에 로컬 결함만 수정하고, 관련 기능에 집중한 테스트를 실행한 뒤 `azd ai agent run`을 언제 다시 시작해야 하는지 알려 달라고 요청합니다. 변경할 때마다 서비스를 다시 시작하고 실패한 인수 테스트(Acceptance test)를 다시 실행합니다. + +## 호스트된 에이전트 배포하기 + +로컬 인수 테스트를 통과했다면 에이전트를 Microsoft Foundry에 배포할 준비가 되었습니다. 동일한 스킬 중심 작업 흐름을 사용해 배포 준비 상태를 확인하고 원격 엔드포인트를 테스트합니다. + +1. 모든 인수 테스트를 통과한 뒤 Ctrl+C로 로컬 서비스를 중지합니다. +2. Copilot CLI로 돌아가 다음 프롬프트를 입력합니다. 배포를 승인하기 전에 제안된 리소스와 예상 비용을 검토합니다. + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. 평가 모음 소스를 선택하라는 메시지가 표시되면 **No, set it up later**를 선택합니다. + + ![호스트된 에이전트 배포 상태와 플레이그라운드 링크](../../../_images/cli-8-hosted-agent-deployment.png) + +4. 배포 상태와 원격 응답을 검토합니다. 에이전트가 실행 중이고 실제 카탈로그 게임만 추천하는지 확인합니다. 배포나 호출이 실패하면 계속 진행하기 전에 Copilot에 실패 원인을 진단하고 원격 테스트를 반복하도록 요청합니다. + +표시된 플레이그라운드(Playground) 링크를 통해 Microsoft Foundry 포털에서 배포된 호스트된 에이전트와 상호 작용할 수 있습니다. + +스킬 중심 작업 흐름은 `azd deploy`를 사용해 서비스 소스를 패키징하고, 의존성을 해결하고, 원격으로 빌드한 뒤 Microsoft Foundry에 게시합니다. 배포된 엔드포인트는 Foundry 호출 작업 흐름으로 테스트합니다. + +## 요약 및 다음 단계 + +배포 가능한 카탈로그 사본을 포함한 에이전트를 스캐폴드하고, 그라운딩과 대화 연속성을 테스트한 뒤 Microsoft Foundry의 원격 응답을 검증했습니다. 이제 정상적으로 작동하는 호스트된 Backer Concierge가 준비되었습니다. + +다음으로 동일한 리포지토리, 브랜치, Copilot CLI 세션, 배포된 에이전트를 유지한 채 [컨시어지를 웹사이트에 연결합니다][next-lesson]. 호스트된 에이전트를 살펴본 것으로 충분하다면 여기서 중단하고 [Azure 리소스를 정리합니다][cleanup]. + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#리소스-정리하기 diff --git a/docs/ko-kr/cli/8-foundry-agent/3-connect-to-site.md b/docs/ko-kr/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..680be62b --- /dev/null +++ b/docs/ko-kr/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "모듈 3 - 에이전트를 웹사이트에 연결하기" +description: "로컬 Azure Functions 프록시와 접근성을 갖춘 채팅 위젯을 통해 호스트된 Backer Concierge를 Tailspin Toys에 연결합니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +[모듈 2][previous-lesson]에서는 Backer Concierge를 배포하고 테스트했습니다. [선택 사항 컨시어지 시리즈][overview]의 마지막 모듈에서는 로컬 Tailspin Toys 웹사이트에서 해당 에이전트를 사용할 수 있도록 합니다. + +이 모듈에서는 다음을 수행합니다. + +- Foundry 자격 증명을 서버에만 유지하는 로컬 Azure Functions 프록시(Proxy)를 빌드합니다. +- 사이트에 접근성을 갖춘 채팅 위젯을 추가합니다. +- 전체 대화 흐름을 검증하고 리소스를 정리합니다. + +## 시나리오 + +후원자는 개발자 터미널이나 Azure Portal이 아니라 Tailspin Toys 웹사이트에서 게임을 찾습니다. 팀은 카탈로그와 함께 컨시어지(Concierge)를 제공하면서 후속 질문을 지원하고 서비스 자격 증명을 보호하는 채팅 경험을 구현하려고 합니다. + +## 호스트된 에이전트에서 계속하기 + +웹사이트 통합에는 모듈 2에서 배포한 에이전트가 필요합니다. 프록시와 웹사이트는 로컬에서 실행하고, 에이전트는 Foundry에서 계속 실행 상태로 유지합니다. + +1. Tailspin Toys 리포지토리의 `foundry-agent-cli` 브랜치와 기존 Copilot CLI 세션으로 돌아갑니다. +2. Backer Concierge가 배포되어 있고 [에이전트 빌드 및 배포하기][previous-lesson]의 원격 호출이 성공했는지 확인합니다. Azure 리소스를 이미 제거했다면 계속 진행하기 전에 이전 모듈을 따라 다시 만듭니다. + +> [!IMPORTANT] +> 이 모듈의 프록시와 웹사이트는 로컬에서 실행합니다. 프로덕션 웹사이트 배포가 아닙니다. 모델과 호스트된 에이전트(Hosted agent)는 [정리][cleanup]를 완료할 때까지 요금이 부과되는 Azure 리소스로 남아 있습니다. + +## 서버 측 프록시 빌드하기 + +Tailspin Toys는 전체를 사전 렌더링합니다. 브라우저 코드는 호스트된 에이전트를 직접 호출하거나 Foundry 자격 증명을 받아서는 안 됩니다. Foundry에 인증하고 에이전트 응답만 브라우저에 반환하는 로컬 Azure Functions **서버 측 자격 증명 경계**를 추가합니다. + +`microsoft-foundry` 스킬은 호스트된 에이전트 작업 흐름을 담당하며, 같은 플러그인에 포함된 더 폭넓은 Azure 스킬은 로컬 Function 프로젝트를 준비할 수 있습니다. 이러한 스킬로 프록시를 빌드한 뒤 자격 증명을 노출하지 않고 에이전트에 연결하는지 확인합니다. + +1. Copilot CLI에 다음을 입력합니다. + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Azure Functions 로컬 프록시 설정](../../../_images/cli-8-azure-functions-proxy.png) + +2. 다른 터미널을 열고 Copilot이 제공한 명령으로 로컬 Function을 시작합니다. Function을 실행 상태로 둡니다. +3. Copilot CLI로 돌아가 로컬 프록시 테스트를 요청합니다. + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. 응답을 살펴봅니다. 카탈로그에 가격 정보가 없다고 설명해야 합니다. Foundry 토큰, 자격 증명, 프로젝트 엔드포인트, 원본 Foundry 대화 식별자, 스택 추적이 포함되어서는 안 됩니다. + + ![로컬 컨시어지 엔드포인트에서 받은 민감 정보를 제거한 JSON 응답](../../../_images/cli-8-sanitized-json-response.png) + +## 채팅 위젯 빌드하기 + +프록시를 통해 브라우저가 안전하게 컨시어지에 연결할 수 있게 되었습니다. 이제 사이트에 채팅 위젯을 추가하고 Playwright로 전체 대화 흐름을 확인합니다. + +1. Copilot에 사이트 통합을 요청합니다. + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. 로컬 Function을 실행 상태로 유지한 채 다른 터미널에서 Copilot이 제공한 명령으로 Astro 사이트를 시작합니다. +3. Copilot CLI로 돌아갑니다. [연습 4][playwright-lesson]에서 추가한 Playwright MCP 서버를 이미 사용할 수 있습니다. Copilot에 위젯 테스트를 요청합니다. + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Tailspin Toys 사이트의 Backer Concierge 위젯 화면](../../../_images/cli-8-backer-concierge-widget.png) + +4. 보고된 증거와 결과를 대조해 검토합니다. 실패한 검사가 있다면 마무리하기 전에 Copilot에 해당 프록시나 위젯 동작을 수정하고 실패한 검사를 다시 실행하도록 요청합니다. + +## 리소스 정리하기 + +로컬 웹사이트에서 작동하는 컨시어지라는 최종 결과물을 완성했습니다. 공통 정리 지침은 시리즈 전반에서 만든 로컬 서비스와 Azure 리소스를 모두 다룹니다. + +1. [리소스 정리하기][cleanup]를 완료합니다. 로컬 서비스를 중지하고 Azure 리소스 삭제가 완료되었는지 확인하는 작업도 포함됩니다. + +## 요약 및 다음 단계 + +로컬 서버 측 프록시와 접근성을 갖춘 채팅 위젯을 통해 호스트된 Backer Concierge를 Tailspin Toys에 연결했습니다. 시리즈 전반에서 GitHub Copilot CLI와 Foundry를 사용해 모델을 준비하고, 에이전트를 빌드 및 배포한 뒤 완전한 웹사이트 통합을 검증했습니다. + +CLI 워크숍을 마무리하려면 [검토 및 다음 단계][review]로 이동합니다. + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#리소스-정리하기 diff --git a/docs/ko-kr/cli/8-foundry-agent/README.md b/docs/ko-kr/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..dabcd467 --- /dev/null +++ b/docs/ko-kr/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: ko-kr/cli/8-foundry-agent +title: "선택 사항: Foundry 통합하기" +description: "모델을 준비하고, 카탈로그에 근거한 에이전트를 빌드 및 배포한 뒤 Tailspin Toys에 연결하는 3개 모듈 시리즈입니다." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +이 선택 사항 시리즈에서는 GitHub Copilot CLI와 Microsoft Foundry Skill을 사용해 Tailspin Toys 카탈로그를 대화형 도우미로 만듭니다. 3개 모듈을 통해 프로젝트와 모델 설정부터 호스트된 에이전트(Hosted agent)와 실제로 작동하는 웹사이트 통합까지 진행합니다. + +이 시리즈에서는 다음을 수행합니다. + +- Azure 환경을 준비하고 카탈로그를 기준으로 모델을 테스트합니다. +- 호스트된 Backer Concierge 에이전트를 스캐폴드(Scaffold)하고 테스트 및 배포합니다. +- 로컬 서버 측 프록시(Proxy)와 채팅 위젯을 통해 에이전트를 웹사이트에 연결합니다. + +## 시나리오 + +Tailspin Toys의 후원자는 카테고리와 퍼블리셔별로 게임을 탐색할 수 있지만, 이러한 필터만으로는 모든 후원자가 다음에 즐길 게임을 찾기 어렵습니다. *Git 말장난을 좋아하는 사람에게는 어떤 게임이 어울릴까요?* 같은 질문을 하는 후원자도 있습니다. 이런 질문에는 드롭다운으로 답할 수 없습니다. + +Tailspin Toys는 후원자가 대화를 통해 게임을 찾도록 돕는 **Backer Concierge**를 만들려고 합니다. Tailspin 카탈로그에 있는 게임을 추천하고, 취향이 모호할 때는 이를 구체화하는 짧은 질문을 하며, 후속 질문을 받으면 앞서 추천한 내용을 기억해야 합니다. + +후원자에게는 믿을 수 있는 답변이 필요합니다. 컨시어지(Concierge)는 카탈로그에 있는 정보만 사용하고, 확인할 수 없는 세부 정보는 없다고 명확히 알려야 합니다. 게임, 퍼블리셔, 평점, 총 모금액, 후원자 수, 가격, 플레이어 수, 플레이 시간, 출시일을 지어내서는 안 됩니다. + +## 다음 단계 선택하기 + +각 모듈은 동일한 Tailspin Toys 리포지토리, 브랜치, Foundry 프로젝트에서 이전 모듈의 결과를 이어서 사용합니다. 각 모듈은 작동하는 결과물을 확인하는 단계로 끝납니다. + +| 모듈 | 수행할 작업 | 완료 시점의 결과물 | +| --- | --- | --- | +| [1. 프로젝트와 모델 준비하기][project-model] | 도구를 설정하고, 카탈로그를 내보내고, 모델을 선택하고 테스트합니다 | 카탈로그 질문에 올바르게 답하는 배포된 모델 | +| [2. 에이전트 빌드 및 배포하기][build-deploy] | 에이전트를 스캐폴드하고, 동작을 테스트한 뒤 Foundry에 배포합니다 | 정상적으로 작동하는 호스트된 Backer Concierge | +| [3. 에이전트를 웹사이트에 연결하기][connect-site] | 로컬 프록시와 채팅 위젯을 빌드한 뒤 전체 흐름을 테스트합니다 | 로컬 웹사이트에서 사용할 수 있는 컨시어지 | + +> [!IMPORTANT] +> Microsoft Foundry 호스트된 에이전트는 공개 미리 보기 상태입니다. +> +> 이 시리즈에서는 모델 배포와 호스트된 에이전트를 비롯해 요금이 부과되는 Azure 리소스를 만듭니다. 리소스를 만들기 전에 선택한 구독, 지역, 할당량, 예상 비용을 검토해야 합니다. 첫 번째 또는 두 번째 모듈을 마친 뒤 중단하더라도 [정리 지침][cleanup]을 따라야 합니다. + +1. 선택 사항 시리즈를 시작하려면 [프로젝트와 모델 준비하기][project-model]로 이동합니다. 설정 지침도 해당 모듈에 포함되어 있습니다. +2. 핵심 워크숍을 마무리하고 싶다면 [검토 및 다음 단계][review]로 이동합니다. + +## 리소스 정리하기 + +어느 모듈에서든 실험을 마쳤다면 원치 않는 비용이 발생하지 않도록 Azure 리소스를 제거합니다. 정리하면 이후 모듈에 필요한 리소스도 제거되므로, 나중에 계속하려면 다시 만들어야 합니다. + +> [!CAUTION] +> `rg-tailspin-toys`가 이 연습 전용이고 유지해야 할 리소스가 없는 경우에만 삭제합니다. 공유 리소스 그룹을 삭제하면 관련 없는 리소스도 함께 제거됩니다. + +1. 실행한 로컬 에이전트, Function 또는 Astro 개발 서버가 있다면 해당 터미널에서 Ctrl+C를 눌러 중지합니다. +2. Copilot CLI를 종료합니다. 모듈 2에서 에이전트를 스캐폴드했다면 동일한 `azd` 환경을 사용해 Tailspin Toys 리포지토리 루트에서 다음을 실행합니다. + + ```bash + azd down --purge + ``` + +3. `az account show`로 선택한 구독을 확인합니다. 해당 구독의 `rg-tailspin-toys`를 살펴보고 남아 있는 모든 리소스가 이 연습에 속하는지 확인합니다. 모듈 1을 마친 뒤 중단했다면 `azd` 서비스를 스캐폴드하지 않았더라도 Foundry 프로젝트와 모델을 정리해야 합니다. +4. 워크숍 전용 리소스 그룹이 아직 존재하고 제거하려는 리소스만 포함되어 있다면 다음을 실행합니다. + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Azure Portal에서 리소스 그룹 삭제가 완료되었는지 확인합니다. `--no-wait` 명령은 삭제가 완료되기 전에 반환됩니다. + +## 리소스 + +- [Azure Skills Plugin][azure-skills] +- [코딩 에이전트에서 Microsoft Foundry Skill 사용하기][foundry-skill] +- [Microsoft Foundry Skill로 첫 호스트된 에이전트 배포하기][hosted-agent-quickstart] +- [호스트된 에이전트 권한][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #리소스-정리하기 +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/ko-kr/cli/9-review.md b/docs/ko-kr/cli/9-review.md index be6b5ec5..41e3cce6 100644 --- a/docs/ko-kr/cli/9-review.md +++ b/docs/ko-kr/cli/9-review.md @@ -1,5 +1,5 @@ --- -title: "연습 8 - 검토 및 다음 단계" +title: "연습 9 - 검토 및 다음 단계" authors: - geektrainer lastUpdated: 2026-06-30 @@ -13,6 +13,8 @@ lastUpdated: 2026-06-30 - 고급 작업과 더 복잡한 작업을 위해 커스텀 agent 호출하기 - Slash commands를 사용해 세션을 관리하고, 선택적으로 `/delegate`를 통해 cloud agent로 다시 연결하기 +선택 과제에 도전하고 싶다면, 모델 설정, 에이전트 개발 및 배포, 웹사이트 통합을 다루는 3개 모듈 시리즈에서 [GitHub Copilot CLI와 Foundry로 컨시어지 빌드하기][foundry-lesson]를 진행할 수 있습니다. + 이제 몇 가지 slash commands, 모범 사례, 다음 단계를 정리해 보겠습니다. ## 슬래시 명령 @@ -61,6 +63,7 @@ GitHub Copilot 생태계를 더 살펴보고 싶다면 [VS Code harness](../../v - [MCP 사양][mcp-spec] [previous-lesson]: ../7-slash-commands/ +[foundry-lesson]: ../8-foundry-agent/ [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli [using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli [awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/ko-kr/cli/README.md b/docs/ko-kr/cli/README.md index d2fe259e..d054b04a 100644 --- a/docs/ko-kr/cli/README.md +++ b/docs/ko-kr/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 [**GitHub Copilot CLI**](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)는 터미널에서 GitHub Copilot을 에이전트형 코딩 도우미로 사용할 수 있게 해줍니다. 코드베이스를 탐색하고, 코드를 생성하고, 명령을 실행하고, 외부 도구에 연결하는 작업을 모두 명령줄에서 처리하므로 그래픽 편집기로 전환하지 않고도 작업 흐름을 유지할 수 있습니다. -이 연습 전체에서 Copilot CLI를 설치하고 인증한 다음, 커스텀 지침으로 프로젝트 컨텍스트를 제공한 뒤 plan mode를 사용해 의도적으로 기능을 생성합니다. 이어서 Playwright MCP server를 연결해 실제 브라우저에서 해당 기능을 테스트하고, 재사용 가능한 agent skills와 custom agents로 Copilot을 확장합니다. 마지막으로 slash commands로 컨텍스트, 모델, 공유를 관리하는 방법을 살펴보고, 완성한 내용을 검토합니다. +이 연습 전체에서 Copilot CLI를 설치하고 인증한 다음, 커스텀 지침으로 프로젝트 컨텍스트를 제공한 뒤 plan mode를 사용해 의도적으로 기능을 생성합니다. 이어서 Playwright MCP server를 연결해 실제 브라우저에서 해당 기능을 테스트하고, 재사용 가능한 agent skills와 custom agents로 Copilot을 확장합니다. 마지막으로 slash commands로 컨텍스트, 모델, 공유를 관리하는 방법을 살펴보고, 완성한 내용을 검토합니다. 또한 선택 사항으로, [GitHub Copilot CLI와 Foundry를 사용하는 3개 모듈 시리즈][foundry]에서 모델을 준비하고, 호스트된 에이전트를 빌드 및 배포한 뒤 사이트에 통합할 수 있습니다. ## 연습 @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. 에이전트 스킬][ex5] | 스킬 | 특화된 스킬로 Copilot을 강화합니다 | | [6. 커스텀 에이전트][ex6] | 에이전트 | 커스텀 에이전트를 검토하고 사용합니다 | | [7. 슬래시 명령][ex7] | CLI 기능 | 컨텍스트, 모델, 공유, 그리고 선택적으로 cloud agent 위임을 살펴봅니다 | -| [8. Backer Concierge AI 에이전트 빌드 (선택 사항)][foundry] | 호스트된 에이전트 | 카탈로그 기반 Backer Concierge를 빌드하고 배포합니다 | | [9. 검토][ex9] | 요약 | 핵심 개념과 다음 단계를 검토합니다 | +| [선택 사항: Foundry 통합하기][foundry] | 호스트된 에이전트 | 모델을 준비하고, 카탈로그 기반 Backer Concierge를 빌드 및 배포한 뒤 웹사이트에 연결합니다 | ## 사전 준비 diff --git a/docs/pt-br/cli/7-slash-commands.md b/docs/pt-br/cli/7-slash-commands.md index f74d06d7..22f4803b 100644 --- a/docs/pt-br/cli/7-slash-commands.md +++ b/docs/pt-br/cli/7-slash-commands.md @@ -157,7 +157,7 @@ Usar comandos de barra no Copilot CLI permite configurá-lo, compartilhar sessõ - `/model` para explorar a lista de modelos disponíveis e selecionar outro, se quiser. - `/delegate` como uma ponte opcional para o agente de nuvem. -É claro que há mais comandos de barra disponíveis e muito mais para explorar no Copilot CLI. Se quiser ir além, a [lição opcional de Microsoft Foundry][foundry-lesson] mostra como criar um agente hospedado com base no catálogo do Tailspin. Caso contrário, vamos encerrar essa jornada [revendo o que aprendemos][next-lesson] e vendo alguns próximos passos para continuar aprendendo. +É claro que há mais comandos de barra disponíveis e muito mais para explorar no Copilot CLI. Vamos encerrar essa jornada [revendo o que aprendemos][next-lesson] e vendo alguns próximos passos para continuar aprendendo. Se quiser um desafio opcional antes de concluir, você pode [criar um concierge com GitHub Copilot CLI e Foundry][foundry-lesson] em uma série de três módulos. ## Recursos diff --git a/docs/pt-br/cli/8-foundry-agent/1-project-and-model.md b/docs/pt-br/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..070070f1 --- /dev/null +++ b/docs/pt-br/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "Módulo 1 - Prepare o projeto e o modelo" +description: "Configure as ferramentas do Azure, exporte o catálogo do Tailspin e selecione e teste um modelo do Foundry com o GitHub Copilot CLI." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +Este é o primeiro módulo de [Opcional: Incorpore o Foundry][overview]. Você preparará as ferramentas e o catálogo e, em seguida, usará o Copilot para criar um projeto do Foundry e testar um modelo implantado antes de criar o agente. + +Neste módulo, você vai: + +- instalar as ferramentas de linha de comando do Azure e o plugin Azure Skills. +- exportar o catálogo e planejar o trabalho com o Foundry. +- selecionar, implantar e testar um modelo considerando os limites do catálogo. + +## Cenário + +O Tailspin Toys precisa de um concierge que saiba distinguir os fatos do catálogo das informações que a empresa não fornece. Uma recomendação útil pode indicar um jogo de quebra-cabeça bem avaliado, mas não pode inventar o total arrecadado por esse jogo. Antes de investir em um assistente completo, a equipe quer ter confiança de que o modelo escolhido consegue respeitar esse limite. + +## Pré-requisitos e configuração + +Você usará o Azure para hospedar o Backer Concierge e o Copilot CLI para orientar o trabalho. Primeiro, prepare as ferramentas de linha de comando e o plugin que permitem ao Copilot trabalhar com seus recursos do Azure. + +> [!IMPORTANT] +> As [instruções de limpeza][cleanup] cobrem tanto a interrupção após este módulo quanto a conclusão da série. + +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 em créditos][azure-free] ou o [Azure for Students com US$ 100 em créditos][azure-students]. +2. Volte ao codespace do Tailspin Toys e abra um terminal. +3. Instale a CLI do Azure no contêiner de desenvolvimento: + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. Faça login na CLI do Azure com `az login` e confirme que está usando a assinatura correta com `az account show`. +5. Instale a [Azure Developer CLI][install-azd] versão 1.27.1 ou posterior. O Microsoft Foundry usa o `azd` para testar e implantar agentes hospedados. + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. Faça login na Azure Developer CLI com `azd auth login` e confirme que está usando a assinatura correta com `azd config show`. +7. Instale a extensão Foundry da Azure Developer CLI (azd): + + ```bash + azd ext install microsoft.foundry + ``` + +8. Abra uma nova sessão do Copilot CLI ao lado pela paleta de comandos. Pressione Command+Shift+P (Mac) ou Ctrl+Shift+P (Windows/Linux) e selecione **Chat: Nova sessão do Copilot CLI ao lado**. +9. Adicione o marketplace do Azure Skills. Você só precisa fazer isso na primeira instalação do plugin: + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. Instale o [plugin Azure Skills][azure-skills], que adiciona skills do Azure, o Azure MCP Server e o Foundry MCP Server ao GitHub Copilot CLI: + + ```text + /plugin install azure@azure-skills + ``` + +11. Confirme que o plugin configurou o servidor MCP do Azure: + + ```text + /mcp list + ``` + +12. Se as skills ou os servidores MCP não aparecerem, tente `/skills reload` ou `/restart` e verifique novamente. + +As skills ensinam o fluxo de trabalho ao Copilot, enquanto os servidores MCP permitem que ele inspecione e trabalhe com seus recursos do Azure. + +## Prepare sua branch de trabalho + +Os exercícios anteriores podem ter criado e enviado outras branches de funcionalidade. Você começará esta série opcional a partir de uma branch `main` atualizada para manter o trabalho do agente separado. + +1. No terminal do shell, mude para `main`, baixe as alterações mais recentes e crie uma branch para o Backer Concierge: + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## Gere a exportação do catálogo + +O agente precisa do catálogo em um arquivo que possa ler. O exemplo do Tailspin Toys inclui um script de exportação testado para essa finalidade. + +1. Volte ao Copilot CLI e insira: + + ```text + 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. + ``` + + O Copilot deve executar o equivalente a: + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![Resumo da exportação do catálogo](../../../_images/cli-8-export-db-catalog.png) + +2. Abra `db/catalog.json`. Confirme que ele contém 21 jogos com título, descrição, categoria, editora e avaliação em estrelas. O campo `note` informa que o catálogo não contém totais arrecadados, quantidades de apoiadores, níveis de apoio ou datas de lançamento. Também não há campos de preço, número de jogadores ou tempo de jogo. Essas ausências definem o limite que o agente deve respeitar. + +## Planeje o trabalho com o Foundry + +Antes de o Copilot criar recursos do Azure ou adicionar código do agente, você usará o modo plan para tornar visível o fluxo de trabalho pretendido. + +1. Insira o seguinte prompt: + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. Revise o plano proposto. Confirme que o Copilot pretende usar a skill `microsoft-foundry` e que separa o agente hospedado do aplicativo Astro existente. Se notar algo preocupante ou inesperado, solicite revisões antes de prosseguir. +3. Saia do modo plan quando estiver satisfeito com a abordagem. + +## Configure um projeto e um modelo do Foundry + +O agente precisa de um projeto do Foundry e de um modelo implantado. Você usará a skill do Microsoft Foundry para selecioná-los com base na disponibilidade e na cota atuais da sua assinatura. + +1. Peça ao Copilot para criar o projeto. Antes de aprovar a criação de recursos, verifique a assinatura, a região, a cota e o custo estimado selecionados: + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![Criação de um projeto público do Foundry](../../../_images/cli-8-create-foundry-project.png) + +2. Quando o projeto estiver pronto, peça ao Copilot para recomendar um modelo: + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + O Copilot pode solicitar que você selecione um modelo entre as opções recomendadas. + + ![Seleção de um modelo entre as opções recomendadas](../../../_images/cli-8-select-foundry-model.png) + + Continuaremos com `gpt-5.4-mini` nas próximas etapas, mas a disponibilidade e a cota variam por região. + +3. Selecione um modelo entre as opções recomendadas e peça ao Copilot para implantar sua escolha. Revise a capacidade e o custo antes de aprovar a implantação: + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![Implantação do modelo selecionado](../../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> A disponibilidade dos modelos muda ao longo do tempo. A escolha certa é um modelo cuja disponibilidade no projeto seja confirmada pelo Copilot, não um modelo fixado em um exemplo. + +## Teste o modelo implantado + +Antes de criar o agente hospedado, você testará se o modelo segue as regras do Backer Concierge para fundamentar as respostas. Esse teste usa as instruções pretendidas e o contexto do catálogo, sem nenhum código ou configuração de agente. + +Primeiro, você atribuirá à conta conectada a função **Foundry Project Manager** para desenvolver o agente hospedado no Módulo 2 e a função **Cognitive Services OpenAI User** para inferência direta do modelo. Depois, fará uma pergunta sobre o catálogo que também solicita informações ausentes nele. + +1. Abra um novo terminal e defina os valores da conta, do projeto e do usuário. Substitua `` pelo nome da conta do Foundry informado quando o projeto foi criado: + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. Atribua a função **Foundry Project Manager**: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. Atribua a função **Cognitive Services OpenAI User**: + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. Volte ao Copilot CLI e insira: + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![Resposta do modelo do Foundry recomendando um jogo real do catálogo e informando que os dados de arrecadação não estão disponíveis](../../../_images/cli-8-foundry-agent-response.png) + +5. Revise a resposta. Ela deve recomendar apenas um jogo real do catálogo, usar os detalhes corretos do catálogo e explicar que as informações de arrecadação não estão disponíveis. Se o modelo inventar um título, detalhes do jogo ou um total arrecadado, compare outro modelo recomendado antes de continuar. + +> [!NOTE] +> Isso testa apenas o modelo implantado com instruções temporárias e contexto do catálogo. Não testa um agente. O Módulo 2 repete o teste após a geração da estrutura para validar o código, o empacotamento e o comportamento de conversação do agente hospedado. + +## Resumo e próximos passos + +Você preparou as ferramentas do Azure, exportou o catálogo e testou um modelo implantado com base nas regras do Backer Concierge para fundamentar as respostas. O resultado deste módulo é um modelo que recomenda jogos reais do catálogo sem inventar informações ausentes. + +A seguir, você usará o mesmo repositório, a branch `foundry-agent-cli`, a sessão do Copilot CLI, o projeto do Foundry e a implantação do modelo selecionado para [criar e implantar o agente][next-lesson]. Se for parar por aqui, [limpe seus recursos do Azure][cleanup] para evitar custos contínuos. + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#limpe-seus-recursos +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/pt-br/cli/8-foundry-agent/2-build-and-deploy.md b/docs/pt-br/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..6fcccdbf --- /dev/null +++ b/docs/pt-br/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "Módulo 2 - Crie e implante o agente" +description: "Use o GitHub Copilot CLI e a skill do Microsoft Foundry para gerar a estrutura, testar e implantar o Backer Concierge." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +No [Módulo 1][previous-lesson], você preparou o catálogo e testou um modelo implantado. Este segundo módulo da [série opcional do concierge][overview] transforma essa base em um agente hospedado. + +Neste módulo, você vai: + +- gerar a estrutura do agente com sua própria cópia do catálogo para implantação. +- testar localmente a fundamentação das respostas e a continuidade da conversa. +- implantar o agente e invocá-lo remotamente. + +## Cenário + +O Tailspin Toys precisa de mais do que uma resposta isolada de um modelo. Os apoiadores esperam que o concierge se lembre dos jogos que acabou de recomendar e responda a perguntas de acompanhamento sobre eles. A equipe também precisa que essas respostas continuem confiáveis quando o concierge sair da máquina de desenvolvimento para um serviço hospedado. + +## Continue com seu projeto + +Este módulo dá continuidade ao modelo funcional do Módulo 1. Você manterá o mesmo projeto e a mesma implantação em vez de criar outro conjunto de recursos do Azure. + +1. Volte ao repositório do Tailspin Toys na branch `foundry-agent-cli` e à sessão do Copilot CLI do Módulo 1. +2. Confirme que `db/catalog.json` está disponível e que você ainda tem o projeto do Foundry, a implantação do modelo selecionado e a sessão autenticada no Azure usados no teste do modelo. Se ainda não concluiu essa configuração, termine primeiro [Prepare o projeto e o modelo][previous-lesson]. + +> [!IMPORTANT] +> Os agentes hospedados estão em versão prévia pública e criam recursos do Azure que geram custos. As [instruções de limpeza][cleanup] se aplicam se você parar após este módulo. + +## Gere a estrutura do agente Backer Concierge + +Agora, você pedirá à skill do Microsoft Foundry para gerar a estrutura do agente hospedado dentro do repositório existente do Tailspin Toys e inspecionará o empacotamento e a configuração antes de executá-lo. + +1. Insira o seguinte prompt no Copilot CLI: + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. Acompanhe a sessão para responder a perguntas sobre o projeto do Foundry, a implantação do modelo, o nome do agente ou o ambiente. +3. Quando o Copilot terminar, inspecione as alterações: + + ```text + /diff + ``` + + Confirme que: + + - `azure.yaml` contém um serviço com `host: azure.ai.agent`. + - o serviço aponta para `agent/backer-concierge`. + - o pacote do serviço implantado inclui sua própria cópia gerada do catálogo. + - um script ou uma etapa de build atualiza essa cópia a partir de `db/catalog.json`, em vez de manter dois catálogos editados manualmente. + - o agente usa a implantação do modelo selecionado e a Responses API. + - as instruções rejeitam explicitamente fatos ausentes do catálogo. + - nenhuma credencial, token de acesso, arquivo `.env` ou arquivo de ambiente `.azure` está preparado para commit. + + Use a seguinte estrutura como referência para verificar o resultado após a geração: + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy` empacota o diretório do serviço do agente hospedado. Uma referência em tempo de execução de `agent/backer-concierge` ao arquivo `db/catalog.json` na raiz do repositório pode funcionar localmente e falhar após a implantação. A cópia gerada deve estar disponível no diretório `agent/backer-concierge/` antes da implantação. + +4. Peça ao Copilot para executar os testes específicos e inspecionar a configuração gerada antes de iniciar o serviço: + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + Não continue até que os testes específicos sejam aprovados. + + ![Verificação da estrutura gerada do agente](../../../_images/cli-8-verify-generated-agent.png) + +## Teste o agente localmente + +Agora, você verificará a fundamentação das respostas e o comportamento de conversação do agente por meio da Responses API local. O serviço local do agente ocupa seu terminal enquanto está em execução, portanto, mantenha o Copilot CLI aberto no terminal atual e inicie o agente em um segundo terminal. + +1. Abra outro terminal usando Ctrl+\`. +2. Na raiz do repositório do Tailspin Toys, execute: + + ```bash + azd ai agent run + ``` + + A primeira execução local cria um ambiente Python, instala dependências e inicia o agente hospedado. Deixe esse terminal em execução. + +3. Volte ao Copilot CLI no primeiro terminal e insira: + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![Testes da implantação do agente hospedado aprovados](../../../_images/cli-8-passing-acceptance-scenarios.png) + +4. Revise os resultados. Se o agente não conseguir se conectar, confirme que o segundo terminal ainda está executando o serviço. Se um teste falhar, peça ao Copilot para corrigir apenas o defeito local, executar os testes específicos e informar quando reiniciar `azd ai agent run`. Reinicie o serviço e execute novamente o teste de aceitação que falhou após cada alteração. + +## Implante o agente hospedado + +Com os testes de aceitação locais aprovados, você está pronto para implantar o agente no Microsoft Foundry. Você usará o mesmo fluxo orientado pela skill para verificar se tudo está pronto para a implantação e testar o endpoint remoto. + +1. Pare o serviço local com Ctrl+C depois que todos os testes de aceitação forem aprovados. +2. Volte ao Copilot CLI e insira o seguinte prompt. Revise os recursos propostos e o custo estimado antes de aprovar a implantação: + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. Se for solicitado que você selecione uma fonte para a suíte de avaliação, escolha **Não, configurar mais tarde**. + + ![Status da implantação do agente hospedado e link do playground](../../../_images/cli-8-hosted-agent-deployment.png) + +4. Revise o status da implantação e a resposta remota. Confirme que o agente está em execução e recomenda apenas jogos reais do catálogo. Se a implantação ou a invocação falhar, peça ao Copilot para diagnosticar a falha e repetir o teste remoto antes de continuar. + +O link do playground exibido permite interagir com o agente hospedado implantado no portal do Microsoft Foundry. + +O fluxo orientado pela skill usa `azd deploy` para empacotar o código-fonte do serviço, resolver dependências, compilá-lo remotamente e publicá-lo no Microsoft Foundry. Ele usa o fluxo de invocação do Foundry para testar o endpoint implantado. + +## Resumo e próximos passos + +Você gerou a estrutura de um agente com uma cópia do catálogo para implantação, testou a fundamentação das respostas e a continuidade da conversa e verificou uma resposta remota do Microsoft Foundry. Agora, você tem um Backer Concierge hospedado e funcional. + +A seguir, você manterá o mesmo repositório, a branch, a sessão do Copilot CLI e o agente implantado para [conectar o concierge ao site][next-lesson]. Se um agente hospedado for suficiente para sua exploração, você pode parar por aqui e [limpar seus recursos do Azure][cleanup]. + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#limpe-seus-recursos diff --git a/docs/pt-br/cli/8-foundry-agent/3-connect-to-site.md b/docs/pt-br/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..88c7986a --- /dev/null +++ b/docs/pt-br/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "Módulo 3 - Conecte o agente ao site" +description: "Conecte o Backer Concierge hospedado ao Tailspin Toys por meio de um proxy local do Azure Functions e um widget de chat acessível." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +No [Módulo 2][previous-lesson], você implantou e testou o Backer Concierge. Este último módulo da [série opcional do concierge][overview] disponibiliza esse agente no site local do Tailspin Toys. + +Neste módulo, você vai: + +- criar um proxy local do Azure Functions que mantém as credenciais do Foundry no servidor. +- adicionar um widget de chat acessível ao site. +- verificar o fluxo completo da conversa e limpar seus recursos. + +## Cenário + +Os apoiadores descobrem jogos no site do Tailspin Toys, não no terminal de desenvolvimento ou em um portal do Azure. A equipe quer disponibilizar o concierge junto ao catálogo, com uma experiência de chat que permita perguntas de acompanhamento e proteja as credenciais do serviço. + +## Continue com seu agente hospedado + +A integração com o site precisa do agente implantado no Módulo 2. Você manterá esse agente em execução no Foundry enquanto o proxy e o site são executados localmente. + +1. Volte ao repositório do Tailspin Toys na branch `foundry-agent-cli` e à sessão existente do Copilot CLI. +2. Confirme que o Backer Concierge está implantado e que a invocação remota de [Crie e implante o agente][previous-lesson] foi bem-sucedida. Se você já removeu os recursos do Azure, recrie-os seguindo os módulos anteriores antes de continuar. + +> [!IMPORTANT] +> O proxy e o site deste módulo são executados localmente; esta não é uma implantação do site em produção. O modelo e o agente hospedado continuam sendo recursos do Azure que geram custos até que você conclua a [limpeza][cleanup]. + +## Crie o proxy do lado do servidor + +O Tailspin Toys é totalmente pré-renderizado. O código do navegador nunca deve chamar o agente hospedado diretamente nem receber credenciais do Foundry. Você adicionará uma **barreira de proteção de credenciais do lado do servidor** com o Azure Functions local, que se autentica no Foundry e retorna ao navegador apenas a resposta do agente. + +A skill `microsoft-foundry` é responsável pelo fluxo de trabalho do agente hospedado, enquanto as skills mais abrangentes do Azure no mesmo plugin podem preparar o projeto local da Function. Você usará essas skills para criar o proxy e verificará se ele acessa o agente sem expor credenciais. + +1. No Copilot CLI, insira: + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Configuração do proxy local do Azure Functions](../../../_images/cli-8-azure-functions-proxy.png) + +2. Abra outro terminal e inicie a Function local usando o comando fornecido pelo Copilot. Deixe a Function em execução. +3. Volte ao Copilot CLI e peça ao Copilot para testar o proxy local: + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. Inspecione a resposta. Ela deve explicar que o catálogo não contém preços. Não pode conter um token do Foundry, uma credencial, um endpoint de projeto, um identificador bruto de conversa do Foundry ou um rastreamento de pilha. + + ![Resposta JSON sanitizada do endpoint local do concierge](../../../_images/cli-8-sanitized-json-response.png) + +## Crie o widget de chat + +O proxy oferece ao navegador uma forma segura de acessar o concierge. Agora, você adicionará um widget de chat ao site e usará o Playwright para verificar o fluxo completo da conversa. + +1. Peça ao Copilot para criar a integração com o site: + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. Mantenha a Function local em execução e inicie o site Astro em outro terminal usando o comando fornecido pelo Copilot. +3. Volte ao Copilot CLI. O servidor MCP do Playwright que você adicionou na [Lição 4][playwright-lesson] já está disponível. Peça ao Copilot para testar o widget: + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Captura de tela do widget Backer Concierge no site do Tailspin Toys](../../../_images/cli-8-backer-concierge-widget.png) + +4. Revise os resultados com base nas evidências apresentadas. Se alguma verificação falhar, peça ao Copilot para corrigir o comportamento correspondente do proxy ou do widget e executar novamente as verificações que falharam antes de concluir. + +## Limpe seus recursos + +Você chegou ao resultado final: um concierge funcional no site local. As instruções de limpeza compartilhadas cobrem tanto os serviços locais quanto os recursos do Azure criados ao longo da série. + +1. Conclua [Limpe seus recursos][cleanup], incluindo parar os serviços locais e verificar se a exclusão dos recursos do Azure foi concluída. + +## Resumo e próximos passos + +Você conectou o Backer Concierge hospedado ao Tailspin Toys por meio de um proxy local do lado do servidor e um widget de chat acessível. Ao longo da série, usou o GitHub Copilot CLI e o Foundry para preparar um modelo, criar e implantar um agente e verificar uma integração completa com o site. + +Continue em [Revisão e próximos passos][review] para encerrar o workshop da CLI. + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#limpe-seus-recursos diff --git a/docs/pt-br/cli/8-foundry-agent/README.md b/docs/pt-br/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..af8b0e8c --- /dev/null +++ b/docs/pt-br/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: pt-br/cli/8-foundry-agent +title: "Opcional: Incorpore o Foundry" +description: "Uma série de três módulos para preparar um modelo, criar e implantar um agente baseado no catálogo e conectá-lo ao Tailspin Toys." +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +Esta série opcional usa o GitHub Copilot CLI e a skill do Microsoft Foundry para transformar o catálogo do Tailspin Toys em um assistente de conversação. Os três módulos levam você da configuração do projeto e do modelo a um agente hospedado e uma integração funcional com o site. + +Nesta série, você vai: + +- preparar um ambiente do Azure e testar um modelo com base no catálogo. +- gerar a estrutura, testar e implantar um agente Backer Concierge hospedado. +- conectar o agente ao site por meio de um proxy local do lado do servidor e um widget de chat. + +## Cenário + +Os apoiadores do Tailspin Toys podem explorar jogos por categoria e editora, mas esses filtros não ajudam todo mundo a encontrar o próximo jogo. Alguns apoiadores têm perguntas como *Quais jogos seriam indicados para quem adora trocadilhos com Git?* Essas perguntas não têm respostas em menus suspensos. + +O Tailspin Toys quer um **Backer Concierge** que ajude os apoiadores a descobrir jogos por meio de uma conversa. Ele deve recomendar jogos do catálogo do Tailspin, fazer uma pergunta breve de esclarecimento quando as preferências de alguém forem vagas e lembrar as recomendações anteriores quando essa pessoa fizer uma pergunta de acompanhamento. + +Os apoiadores precisam de respostas confiáveis. O concierge deve usar apenas informações do catálogo e deixar claro quando um detalhe não estiver disponível, em vez de inventar jogos, editoras, avaliações, totais arrecadados, quantidades de apoiadores, preços, números de jogadores, tempos de jogo ou datas de lançamento. + +## Escolha seu próximo passo + +Os módulos dão continuidade ao trabalho anterior no mesmo repositório do Tailspin Toys, na mesma branch e no mesmo projeto do Foundry. Cada um termina com um resultado funcional. + +| Módulo | O que você vai fazer | Resultado ao concluir | +| --- | --- | --- | +| [1. Prepare o projeto e o modelo][project-model] | Configurar as ferramentas, exportar o catálogo e selecionar e testar um modelo | Um modelo implantado que responde corretamente a perguntas sobre o catálogo | +| [2. Crie e implante o agente][build-deploy] | Gerar a estrutura do agente, testar seu comportamento e implantá-lo no Foundry | Um Backer Concierge hospedado e funcional | +| [3. Conecte o agente ao site][connect-site] | Criar um proxy local e um widget de chat e testar o fluxo completo | Um concierge disponível no site local | + +> [!IMPORTANT] +> Os agentes hospedados do Microsoft Foundry estão em versão prévia pública. +> +> Esta série cria recursos do Azure que geram custos, incluindo uma implantação de modelo e um agente hospedado. A criação de recursos exige uma revisão da assinatura, da região, da cota e do custo estimado selecionados. As [instruções de limpeza][cleanup] se aplicam mesmo se você parar após o primeiro ou o segundo módulo. + +1. Para começar a série opcional, continue em [Prepare o projeto e o modelo][project-model]. As instruções de configuração estão incluídas nesse módulo. +2. Se preferir concluir o workshop principal, continue em [Revisão e próximos passos][review]. + +## Limpe seus recursos + +Quando terminar de experimentar em qualquer etapa, remova os recursos do Azure para evitar custos indesejados. A limpeza remove recursos necessários para os módulos seguintes, portanto, será preciso recriá-los se quiser continuar depois. + +> [!CAUTION] +> Exclua `rg-tailspin-toys` somente se ele for dedicado a este exercício e não contiver recursos que você precisa manter. Excluir um grupo de recursos compartilhado também removeria recursos não relacionados. + +1. Pare qualquer agente local, Function ou servidor de desenvolvimento do Astro que tenha iniciado pressionando Ctrl+C no respectivo terminal. +2. Saia do Copilot CLI. Se você gerou a estrutura do agente no Módulo 2, execute o comando a seguir na raiz do repositório do Tailspin Toys usando o mesmo ambiente do `azd`: + + ```bash + azd down --purge + ``` + +3. Verifique a assinatura selecionada com `az account show`. Inspecione `rg-tailspin-toys` nessa assinatura e confirme que todos os recursos restantes pertencem a este exercício. Se você parou após o Módulo 1, o projeto do Foundry e o modelo ainda precisam de limpeza, mesmo que você não tenha gerado a estrutura de um serviço do `azd`. +4. Se o grupo de recursos dedicado ao workshop ainda existir e contiver apenas recursos que você pretende remover, execute: + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. Confirme no portal do Azure que a exclusão do grupo de recursos foi concluída. O comando com `--no-wait` retorna antes de a exclusão terminar. + +## Recursos + +- [Plugin Azure Skills][azure-skills] +- [Use a skill do Microsoft Foundry em agentes de programação][foundry-skill] +- [Implante seu primeiro agente hospedado com a skill do Microsoft Foundry][hosted-agent-quickstart] +- [Permissões de agentes hospedados][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #limpe-seus-recursos +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/pt-br/cli/9-review.md b/docs/pt-br/cli/9-review.md index fe6450da..5c48b5ef 100644 --- a/docs/pt-br/cli/9-review.md +++ b/docs/pt-br/cli/9-review.md @@ -1,5 +1,5 @@ --- -title: "Lição 8 - Revisão e próximos passos" +title: "Lição 9 - Revisão e próximos passos" authors: - geektrainer lastUpdated: 2026-06-30 @@ -13,6 +13,8 @@ Ao longo das últimas lições, você explorou alguns dos casos de uso mais comu - chamar agentes personalizados para tarefas avançadas e mais complexas. - usar comandos de barra para gerenciar sua sessão e, opcionalmente, voltar ao agente de nuvem por meio de `/delegate`. +Se quiser um desafio opcional, [crie um concierge com GitHub Copilot CLI e Foundry][foundry-lesson] em uma série de três módulos que abrange a configuração do modelo, o desenvolvimento e a implantação do agente e a integração com o site. + Vamos falar sobre alguns comandos de barra, boas práticas e próximos passos. ## Comandos de barra @@ -61,6 +63,7 @@ Se quiser explorar mais do ecossistema do GitHub Copilot, confira o [percurso do - [Especificação do MCP][mcp-spec] [previous-lesson]: ../7-slash-commands/ +[foundry-lesson]: ../8-foundry-agent/ [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli [using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli [awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/pt-br/cli/README.md b/docs/pt-br/cli/README.md index 5e9c22a8..fb0a22de 100644 --- a/docs/pt-br/cli/README.md +++ b/docs/pt-br/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 O **[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** coloca o GitHub Copilot no seu terminal como um assistente de programação baseado em agentes. Ele explora bases de código, gera código, executa comandos e se conecta a ferramentas externas — tudo pela linha de comando, para que você mantenha o foco sem trocar para um editor gráfico. -Ao longo destas lições, você instalará e autenticará o Copilot CLI, depois fornecerá contexto do projeto com instruções personalizadas antes de usar o modo plan para gerar um recurso de forma deliberada. Você conectará o servidor MCP do Playwright para testar esse recurso em um navegador real e, em seguida, ampliará o Copilot com skills de agente reutilizáveis e agentes personalizados. Por fim, você explorará comandos de barra para gerenciar contexto, modelos e compartilhamento, e concluirá com uma revisão do que criou. +Ao longo destas lições, você instalará e autenticará o Copilot CLI, depois fornecerá contexto do projeto com instruções personalizadas antes de usar o modo plan para gerar um recurso de forma deliberada. Você conectará o servidor MCP do Playwright para testar esse recurso em um navegador real e, em seguida, ampliará o Copilot com skills de agente reutilizáveis e agentes personalizados. Por fim, você explorará comandos de barra para gerenciar contexto, modelos e compartilhamento, e concluirá com uma revisão do que criou. Você também pode seguir uma [série opcional de três módulos com GitHub Copilot CLI e Foundry][foundry] para preparar um modelo, criar e implantar um agente hospedado e integrá-lo ao site. ## Lições @@ -22,8 +22,8 @@ Ao longo destas lições, você instalará e autenticará o Copilot CLI, depois | [5. Skills de agente][ex5] | Skills | Aprimore o Copilot com skills especializadas | | [6. Agentes personalizados][ex6] | Agentes | Revise e use agentes personalizados | | [7. Comandos de barra][ex7] | Recursos da CLI | Explore contexto, modelos, compartilhamento e a delegação opcional para o agente de nuvem | -| [8. Criar um agente de IA Backer Concierge (opcional)][foundry] | Agentes hospedados | Crie e implante um Backer Concierge baseado no catálogo | | [9. Revisão][ex9] | Resumo | Revise os principais conceitos e os próximos passos | +| [Opcional: Incorpore o Foundry][foundry] | Agentes hospedados | Prepare um modelo, crie e implante um Backer Concierge baseado no catálogo e conecte-o ao site | ## Pré-requisitos diff --git a/docs/zh-cn/cli/7-slash-commands.md b/docs/zh-cn/cli/7-slash-commands.md index fd9f9663..908e57aa 100644 --- a/docs/zh-cn/cli/7-slash-commands.md +++ b/docs/zh-cn/cli/7-slash-commands.md @@ -157,7 +157,7 @@ lastUpdated: 2026-06-30 - 使用 `/model` 查看可用模型列表，并在需要时选择新的模型。 - 了解了 `/delegate` 作为连接 cloud agent 的可选桥梁。 -当然，还有更多斜杠命令可用，也还有更多 Copilot CLI 功能值得探索。如果你想更进一步，[可选的 Microsoft Foundry 课程][foundry-lesson]将带你在 Tailspin 目录之上构建一个托管智能体。否则，最后通过[回顾已学内容][next-lesson]以及后续学习方向，为这段旅程收尾。 +当然，还有更多斜杠命令可用，也还有更多 Copilot CLI 功能值得探索。最后，通过[回顾已学内容][next-lesson]并了解后续学习方向，为这段旅程收尾。如果想在结束前尝试一项可选挑战，可以通过包含三个模块的系列课程[使用 GitHub Copilot CLI 和 Foundry 构建礼宾助手][foundry-lesson]。 ## 资源 diff --git a/docs/zh-cn/cli/8-foundry-agent/1-project-and-model.md b/docs/zh-cn/cli/8-foundry-agent/1-project-and-model.md new file mode 100644 index 00000000..1cfec351 --- /dev/null +++ b/docs/zh-cn/cli/8-foundry-agent/1-project-and-model.md @@ -0,0 +1,220 @@ +--- +title: "模块 1 - 准备项目和模型" +description: "设置 Azure 工具、导出 Tailspin 目录，并使用 GitHub Copilot CLI 选择和测试 Foundry 模型。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +这是[可选：集成 Foundry][overview]中的第一个模块。将先准备工具和目录，然后使用 Copilot 创建 Foundry 项目，并在构建智能体之前测试已部署的模型。 + +在本模块中，将完成以下任务： + +- 安装 Azure 命令行工具和 Azure Skills 插件。 +- 导出目录并规划 Foundry 工作。 +- 选择、部署和测试模型，检查其是否遵守目录的信息边界。 + +## 场景 + +Tailspin Toys 需要一个能够区分目录事实和公司未提供信息的礼宾助手。有效的推荐可以指出一款高评分的益智游戏，但绝不能编造该游戏的筹款总额。在投入精力构建完整助手之前，团队希望确认所选模型能够遵守这一边界。 + +## 先决条件和设置 + +将使用 Azure 托管 Backer Concierge，并通过 Copilot CLI 引导工作。首先，准备好让 Copilot 能够操作 Azure 资源的命令行工具和插件。 + +> [!IMPORTANT] +> 无论是在本模块后停止，还是完成整个系列，都应按照[清理说明][cleanup]操作。 + +1. 确认已拥有 Azure 订阅。如果还没有，可选择[包含 200 美元额度的免费 Azure 订阅][azure-free]或[包含 100 美元额度的 Azure for Students][azure-students]。 +2. 返回 Tailspin Toys codespace 并打开终端。 +3. 在开发容器中安装 Azure CLI： + + ```bash + curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash + az version + ``` + +4. 使用 `az login` 登录 Azure CLI，并通过 `az account show` 确认使用的是正确的订阅。 +5. 安装 1.27.1 或更高版本的 [Azure Developer CLI][install-azd]。Microsoft Foundry 使用 `azd` 测试和部署托管智能体。 + + ```bash + curl -sL https://aka.ms/install-azd.sh | bash + azd version + ``` + +6. 使用 `azd auth login` 登录 Azure Developer CLI，并通过 `azd config show` 确认使用的是正确的订阅。 +7. 安装 Azure Developer CLI (azd) 的 Foundry 扩展： + + ```bash + azd ext install microsoft.foundry + ``` + +8. 从命令面板在侧边打开新的 Copilot CLI 会话。按 Command+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），然后选择 **Chat: New Copilot CLI session to the side**（聊天：在侧边新建 Copilot CLI 会话）。 +9. 添加 Azure Skills 市场。仅在首次安装插件时需要执行此操作： + + ```text + /plugin marketplace add microsoft/azure-skills + ``` + +10. 安装 [Azure Skills 插件][azure-skills]，将 Azure 技能、Azure MCP Server 和 Foundry MCP Server 添加到 GitHub Copilot CLI： + + ```text + /plugin install azure@azure-skills + ``` + +11. 确认插件已配置 Azure MCP 服务器： + + ```text + /mcp list + ``` + +12. 如果未显示技能或 MCP 服务器，请尝试 `/skills reload` 或 `/restart`，然后再次检查。 + +技能向 Copilot 传授工作流程，而 MCP 服务器让它能够查看和操作 Azure 资源。 + +## 准备工作分支 + +之前的练习可能已经创建并推送了其他功能分支。本可选系列将从最新的 `main` 分支开始，以便将智能体相关工作与其他工作分开。 + +1. 在 shell 终端中，切换到 `main`，拉取最新更改，并为 Backer Concierge 创建分支： + + ```bash + git checkout main + git pull + git checkout -b foundry-agent-cli + ``` + +## 生成目录导出文件 + +智能体需要将目录作为可读取的文件。Tailspin Toys 示例为此提供了经过测试的导出脚本。 + +1. 返回 Copilot CLI 并输入： + + ```text + 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 应执行相当于以下命令的操作： + + ```bash + npm install + npm run db:setup + npm run db:export + ``` + + ![目录导出摘要](../../../_images/cli-8-export-db-catalog.png) + +2. 打开 `db/catalog.json`。确认其中包含 21 款游戏，每款游戏都有名称、描述、类别、发行商和星级评分。其 `note` 字段说明目录不包含筹款总额、支持者人数、支持档位或发布日期。目录也没有价格、玩家人数或游戏时长字段。这些缺失的信息界定了智能体必须遵守的边界。 + +## 规划 Foundry 工作 + +在 Copilot 创建任何 Azure 资源或添加智能体代码之前，先使用计划模式明确预期的工作流程。 + +1. 输入以下提示： + + ```text + /plan Use the Microsoft Foundry Skill to plan a Backer Concierge hosted agent for this existing Tailspin Toys repository. Use a public Foundry project, Python 3.13, Microsoft Agent Framework, the Responses API, the Basic sample, and code deployment. Keep the agent in agent/backer-concierge and keep one azure.yaml at the repository root. Ground every answer in db/catalog.json, preserve conversation context, and add focused tests. Include project setup, model selection, local testing, deployment, remote invocation, estimated cost-bearing resources and cleanup. + ``` + +2. 查看建议的计划。确认 Copilot 打算使用 `microsoft-foundry` 技能，并将托管智能体与现有 Astro 应用分开。如果发现任何值得关注或不符合预期的内容，请先要求修改，再继续。 +3. 对方案满意后，退出计划模式。 + +## 设置 Foundry 项目和模型 + +智能体需要一个 Foundry 项目和一个已部署的模型。将使用 Microsoft Foundry 技能，根据订阅中的实时可用情况和配额进行选择。 + +1. 让 Copilot 创建项目。批准资源创建之前，检查所选订阅、区域、配额和预估费用： + + ```text + Use the Microsoft Foundry Skill to create a public Foundry project for this project. Use the resource group rg-tailspin-toys and project name tailspin-toys. + ``` + + ![创建公共 Foundry 项目](../../../_images/cli-8-create-foundry-project.png) + +2. 项目准备就绪后，让 Copilot 推荐模型： + + ```text + Use the Microsoft Foundry Skill to recommend two or three current chat models available in the tailspin-toys project for the Backer Concierge acceptance criteria in the issue titled "Add a Backer Concierge assistant for catalog questions". Prioritize low latency, instruction following, grounding fidelity, available quota, and models that aren't approaching retirement. There is no complex math or multi-step planning. Explain the tradeoffs and wait for me to choose a model from the recommended options. + ``` + + Copilot 可能会提示从推荐选项中选择模型。 + + ![从推荐选项中选择模型](../../../_images/cli-8-select-foundry-model.png) + + 后续步骤将使用 `gpt-5.4-mini`，但可用情况和配额因区域而异。 + +3. 从推荐选项中选择模型，然后让 Copilot 部署所选模型。在批准部署之前，检查容量和费用： + + ```text + Deploy the model we selected to the tailspin-toys Foundry project and use the model name as the deployment name. Choose an SKU with available quota, ask me to confirm the capacity before deployment. After deployment, show me the deployment status. + ``` + + ![部署所选模型](../../../_images/cli-8-deploy-foundry-model.png) + +> [!TIP] +> 模型可用情况会随时间变化。应选择 Copilot 确认在项目中可用的模型，而不是照搬示例中写死的模型。 + +## 测试已部署的模型 + +在构建托管智能体之前，将测试模型是否遵循 Backer Concierge 的信息依据规则。测试使用预期的说明和目录上下文，不涉及任何智能体代码或配置。 + +首先，为当前登录账户授予 **Foundry Project Manager** 角色，以便在模块 2 中开发托管智能体；同时授予 **Cognitive Services OpenAI User** 角色，用于直接执行模型推理。然后提出一个目录问题，其中也包含对目录未提供信息的询问。 + +1. 打开新终端，设置账户、项目和用户相关值。将 `` 替换为创建项目时报告的 Foundry 账户名称： + + ```bash + SUBSCRIPTION_ID=$(az account show --query id --output tsv) + USER_OBJECT_ID=$(az ad signed-in-user show --query id --output tsv) + FOUNDRY_ACCOUNT="" + ACCOUNT_SCOPE=$(az cognitiveservices account show --name "$FOUNDRY_ACCOUNT" --resource-group rg-tailspin-toys --query id --output tsv) + PROJECT_SCOPE="$ACCOUNT_SCOPE/projects/tailspin-toys" + ``` + +2. 分配 **Foundry Project Manager** 角色： + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Foundry Project Manager" \ + --scope "$PROJECT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +3. 分配 **Cognitive Services OpenAI User** 角色： + + ```bash + az role assignment create \ + --assignee-object-id "$USER_OBJECT_ID" \ + --assignee-principal-type User \ + --role "Cognitive Services OpenAI User" \ + --scope "$ACCOUNT_SCOPE" \ + --subscription "$SUBSCRIPTION_ID" + ``` + +4. 返回 Copilot CLI 并输入： + + ```text + 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 like tokens used and response time (only if you can obtain it). Do not change files or create resources. + ``` + + ![Foundry 模型的回答推荐目录中真实存在的游戏，并指出没有筹款数据](../../../_images/cli-8-foundry-agent-response.png) + +5. 查看回答。它应仅推荐目录中真实存在的游戏，使用正确的目录细节，并说明没有筹款信息。如果模型编造游戏名称、游戏细节或筹款总额，请先对比另一个推荐模型，再继续。 + +> [!NOTE] +> 此测试仅使用临时说明和目录上下文测试已部署的模型，并不测试智能体。模块 2 将在生成脚手架后重复测试，以验证托管智能体的代码、打包和对话行为。 + +## 总结和后续步骤 + +本模块准备了 Azure 工具、导出了目录，并根据 Backer Concierge 的信息依据规则测试了已部署的模型。本模块的完成标志是：模型能够推荐目录中真实存在的游戏，而不会编造缺失的信息。 + +接下来，将继续使用同一个存储库、`foundry-agent-cli` 分支、Copilot CLI 会话、Foundry 项目和所选模型部署，[构建并部署智能体][next-lesson]。如果到此为止，请[清理 Azure 资源][cleanup]，以免持续产生费用。 + +[overview]: ../ +[next-lesson]: ../2-build-and-deploy/ +[cleanup]: ../#清理资源 +[azure-free]: https://azure.microsoft.com/pricing/purchase-options/azure-account +[azure-students]: https://azure.microsoft.com/free/students +[install-azd]: https://learn.microsoft.com/azure/developer/azure-developer-cli/install-azd +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli diff --git a/docs/zh-cn/cli/8-foundry-agent/2-build-and-deploy.md b/docs/zh-cn/cli/8-foundry-agent/2-build-and-deploy.md new file mode 100644 index 00000000..ac1cdc37 --- /dev/null +++ b/docs/zh-cn/cli/8-foundry-agent/2-build-and-deploy.md @@ -0,0 +1,150 @@ +--- +title: "模块 2 - 构建并部署智能体" +description: "使用 GitHub Copilot CLI 和 Microsoft Foundry 技能，为 Backer Concierge 生成脚手架、进行测试并部署。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +在[模块 1][previous-lesson]中，已经准备好目录并测试了已部署的模型。本模块是[可选礼宾助手系列][overview]的第二个模块，将在此基础上构建托管智能体。 + +在本模块中，将完成以下任务： + +- 生成智能体脚手架，并为其提供可随服务部署的独立目录副本。 +- 在本地测试回答是否依据目录，以及对话是否连贯。 +- 部署智能体并进行远程调用。 + +## 场景 + +Tailspin Toys 需要的不只是模型的一次性回答。支持者希望礼宾助手记住刚刚推荐的游戏，并回答关于这些游戏的后续问题。团队还需要确保，当礼宾助手从开发者的计算机迁移到托管服务后，回答仍然可靠。 + +## 继续使用现有项目 + +本模块基于模块 1 中已经可用的模型展开。将继续使用同一个项目和部署，而不是再创建一组 Azure 资源。 + +1. 返回 Tailspin Toys 存储库的 `foundry-agent-cli` 分支，以及模块 1 中的 Copilot CLI 会话。 +2. 确认 `db/catalog.json` 可用，并且仍保留模型测试时使用的 Foundry 项目、所选模型部署和 Azure 登录状态。如果尚未完成这些设置，请先完成[准备项目和模型][previous-lesson]。 + +> [!IMPORTANT] +> 托管智能体目前处于公共预览阶段，会创建计费的 Azure 资源。如果在本模块后停止，也应按照[清理说明][cleanup]操作。 + +## 生成 Backer Concierge 智能体脚手架 + +现在将让 Microsoft Foundry 技能在现有 Tailspin Toys 存储库中生成托管智能体脚手架，然后在运行前检查其打包和配置。 + +1. 在 Copilot CLI 中输入以下提示： + + ```text + Use the Microsoft Foundry Skill to scaffold a hosted Backer Concierge in this existing repository using the project and model deployment we selected. Start from the Python 3.13 Basic hosted-agent sample, use Microsoft Agent Framework with the Responses API and code deployment, and keep the agent in agent/backer-concierge. Keep one azure.yaml at the repository root with a service using host: azure.ai.agent. + + Ground every answer in db/catalog.json. Never invent games, publishers, ratings, funding totals, backer counts, pledge tiers, prices, player counts, play times, or release dates. Ask one short clarifying question when a request is vague and preserve conversation context. Ensure the catalog is copied into the deployable service during preparation so the deployed agent never depends on a file outside its service directory. Add focused tests for catalog loading and grounding behavior. + + Scaffold and test locally, but do not deploy the hosted agent yet. Stop and ask me to authenticate if needed. + ``` + +2. 关注会话中关于 Foundry 项目、模型部署、智能体名称或环境的问题。 +3. Copilot 完成后，查看更改： + + ```text + /diff + ``` + + 确认以下内容： + + - `azure.yaml` 包含一个使用 `host: azure.ai.agent` 的服务。 + - 该服务指向 `agent/backer-concierge`。 + - 部署的服务包包含自动生成的独立目录副本。 + - 通过一个脚本或构建步骤从 `db/catalog.json` 更新该副本，而不是手动维护两个目录文件。 + - 智能体使用所选模型部署和 Responses API。 + - 说明明确禁止使用目录中不存在的事实。 + - 没有凭据、访问令牌、`.env` 文件或 `.azure` 环境文件被暂存以待提交。 + + 生成脚手架后，以以下结构为检查标准： + + ```text + tailspin-toys/ + ├── azure.yaml + ├── agent/ + │ └── backer-concierge/ + │ ├── catalog.json + │ └── requirements.txt + ├── db/ + │ └── catalog.json + └── src/ + ``` + +> [!IMPORTANT] +> `azd deploy` 会打包托管智能体的服务目录。如果运行时从 `agent/backer-concierge` 引用存储库级别的 `db/catalog.json`，可能在本地有效，但部署后失败。部署之前，生成的副本必须位于 `agent/backer-concierge/` 目录中。 + +4. 启动服务之前，让 Copilot 运行针对性测试并检查生成的配置： + + ```text + Run the focused Backer Concierge tests. Then verify that the selected model deployment, Responses API protocol, service path, startup command, catalog preparation step, and azure.ai.agent host configuration are consistent. Fix only problems in this hosted-agent project and rerun the failed checks. + ``` + + 只有针对性测试通过后，才能继续。 + + ![验证智能体脚手架](../../../_images/cli-8-verify-generated-agent.png) + +## 在本地测试智能体 + +现在将通过智能体的本地 Responses API，检查其回答是否依据目录，以及对话行为是否符合预期。本地智能体服务运行时会占用终端，因此请在当前终端中保持 Copilot CLI 打开，并从第二个终端启动智能体。 + +1. 按 Ctrl+\` 打开另一个终端。 +2. 在 Tailspin Toys 存储库根目录中运行： + + ```bash + azd ai agent run + ``` + + 首次在本地运行时，会创建 Python 环境、安装依赖项并启动托管智能体。保持此终端中的服务运行。 + +3. 返回第一个终端中的 Copilot CLI 并输入： + + ```text + Test the running Backer Concierge through its Responses API. Run each acceptance prompt below, preserve the response ID for the two-turn conversation test, and compare every response with the expected behavior. Show a concise pass or fail table and the evidence for any failure. Do not change code yet. + + 1. "I love puzzle games about tracking down bugs. What should I back?" Expected: only real catalog titles with correct details. + 2. "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 known information. + 3. "I need something for four players, about an hour long." Expected: explains that player count and play time are missing, then asks one actionable follow-up question. + 4. "Do you have Wingspan? If not, what's the closest thing you've got?" Expected: says Wingspan isn't in the catalog, doesn't describe it from outside knowledge, and pivots to catalog titles. + 5. "Recommend me something good." Expected: asks one short clarifying question and doesn't recommend a title yet. + 6. "What are your three highest rated games?" Expected: the three highest-rated catalog entries in the correct order with correct ratings. + 7. In one conversation, send "Show me two highly rated strategy games." followed by "Which of those has the higher rating?" Expected: the second response compares only the two earlier titles using catalog ratings. + ``` + + ![托管智能体部署测试通过](../../../_images/cli-8-passing-acceptance-scenarios.png) + +4. 查看结果。如果无法连接智能体，请确认第二个终端中的服务仍在运行。如果测试失败，让 Copilot 仅修复本地缺陷、运行针对性测试，并告知何时需要重启 `azd ai agent run`。每次更改后，都要重启服务并重新运行失败的验收测试。 + +## 部署托管智能体 + +本地验收测试通过后，就可以将智能体部署到 Microsoft Foundry。将继续使用由技能引导的工作流程，检查部署准备情况并测试远程终结点。 + +1. 所有验收测试通过后，按 Ctrl+C 停止本地服务。 +2. 返回 Copilot CLI 并输入以下提示。在批准部署之前，检查建议的资源和预估费用： + + ```text + Continue with the Microsoft Foundry Skill workflow. Review the hosted agent for deployment readiness, then deploy it to Microsoft Foundry, show the deployment status and playground link, and invoke it remotely with: "I love puzzle games about tracking down bugs. What should I back?" + ``` + +3. 如果系统提示选择评估套件来源，请选择 **No, set it up later**（否，稍后设置）。 + + ![托管智能体部署状态和操练场链接](../../../_images/cli-8-hosted-agent-deployment.png) + +4. 查看部署状态和远程回答。确认智能体正在运行，且仅推荐目录中真实存在的游戏。如果部署或调用失败，请让 Copilot 诊断故障，并在继续之前重复远程测试。 + +通过显示的操练场链接，可以在 Microsoft Foundry 门户中与已部署的托管智能体交互。 + +由技能引导的工作流程使用 `azd deploy` 打包服务源代码、解析依赖项、执行远程构建，并发布到 Microsoft Foundry。它通过 Foundry 调用流程测试已部署的终结点。 + +## 总结和后续步骤 + +本模块生成了包含可部署目录副本的智能体脚手架，测试了回答的信息依据和对话连贯性，并验证了 Microsoft Foundry 的远程回答。现在已经拥有一个可用的托管 Backer Concierge。 + +接下来，将继续使用同一个存储库、分支、Copilot CLI 会话和已部署的智能体，[将礼宾助手连接到网站][next-lesson]。如果托管智能体已足以满足探索需求，可以到此为止，并[清理 Azure 资源][cleanup]。 + +[overview]: ../ +[previous-lesson]: ../1-project-and-model/ +[next-lesson]: ../3-connect-to-site/ +[cleanup]: ../#清理资源 diff --git a/docs/zh-cn/cli/8-foundry-agent/3-connect-to-site.md b/docs/zh-cn/cli/8-foundry-agent/3-connect-to-site.md new file mode 100644 index 00000000..b2b55d02 --- /dev/null +++ b/docs/zh-cn/cli/8-foundry-agent/3-connect-to-site.md @@ -0,0 +1,96 @@ +--- +title: "模块 3 - 将智能体连接到网站" +description: "通过本地 Azure Functions 代理和无障碍聊天组件，将托管的 Backer Concierge 连接到 Tailspin Toys。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +next: false +--- + +在[模块 2][previous-lesson]中，已经部署并测试了 Backer Concierge。本模块是[可选礼宾助手系列][overview]的最后一个模块，将让本地 Tailspin Toys 网站能够使用该智能体。 + +在本模块中，将完成以下任务： + +- 构建本地 Azure Functions 代理，将 Foundry 凭据保留在服务端。 +- 向网站添加无障碍聊天组件。 +- 验证完整的对话流程并清理资源。 + +## 场景 + +支持者在 Tailspin Toys 网站上发现游戏，而不是在开发者的终端或 Azure 门户中。团队希望在目录旁提供礼宾助手，其聊天体验应支持追问，并保护服务凭据。 + +## 继续使用已托管的智能体 + +网站集成需要模块 2 中已部署的智能体。代理和网站在本地运行期间，智能体将继续在 Foundry 中运行。 + +1. 返回 Tailspin Toys 存储库的 `foundry-agent-cli` 分支，以及现有的 Copilot CLI 会话。 +2. 确认 Backer Concierge 已部署，并且[构建并部署智能体][previous-lesson]中的远程调用已通过验证。如果已经移除了 Azure 资源，请先按照前面的模块重新创建，再继续。 + +> [!IMPORTANT] +> 本模块中的代理和网站在本地运行，并非生产网站部署。在完成[清理][cleanup]之前，模型和托管智能体仍是计费的 Azure 资源。 + +## 构建服务端代理 + +Tailspin Toys 采用完全预渲染方式。浏览器代码绝不能直接调用托管智能体或接收 Foundry 凭据。将添加一个本地 Azure Functions **服务端凭据边界**，由它向 Foundry 进行身份验证，并仅将智能体的回答返回给浏览器。 + +`microsoft-foundry` 技能负责托管智能体的工作流程，而同一插件中用途更广泛的 Azure 技能可用于准备本地 Function 项目。将使用这些技能构建代理，然后检查代理能否在不暴露凭据的情况下访问智能体。 + +1. 在 Copilot CLI 中输入： + + ```text + Use the Azure skills to add an Azure Functions v4 Node.js and TypeScript project in api with one POST /api/concierge endpoint that invokes my deployed Backer Concierge hosted agent. This Function will run locally only; don't add it to azure.yaml or create Azure deployment infrastructure. Use DefaultAzureCredential with my local Azure sign-in. Keep the HTTP trigger thin, isolate the Foundry client in a unit-testable module, validate and limit request bodies, set explicit timeouts, and return sanitized errors. Store the Foundry project endpoint and agent name in local server-side settings that are excluded from version control. Never return credentials or access tokens to the browser. The Astro site is `output: 'static'` with no dev proxy, so also add a local-only Vite dev-server proxy for /api to the Function's port in astro.config.mjs, so relative /api/concierge requests reach it during `astro dev`. + + For conversation state, generate a high-entropy handle on the server, map it to the Foundry conversation server-side with an expiration, and never expose a raw Foundry conversation or thread identifier. Reject malformed, expired, and unknown handles. Add focused unit tests. + ``` + + ![Azure Functions 本地代理设置](../../../_images/cli-8-azure-functions-proxy.png) + +2. 打开另一个终端，然后使用 Copilot 提供的命令启动本地 Function。保持 Function 运行。 +3. 返回 Copilot CLI，让 Copilot 测试本地代理： + + ```text + Send a request to the local /api/concierge endpoint asking "Which games are under $30?" and show me the sanitized JSON response. Confirm that the request reaches the deployed Backer Concierge through DefaultAzureCredential. + ``` + +4. 查看响应。它应说明目录不包含价格。响应中不得包含 Foundry 令牌、凭据、项目终结点、原始 Foundry 对话标识符或堆栈跟踪。 + + ![本地礼宾助手终结点返回的已移除敏感信息的 JSON 响应](../../../_images/cli-8-sanitized-json-response.png) + +## 构建聊天组件 + +代理为浏览器提供了安全访问礼宾助手的方式。现在将向网站添加聊天组件，并使用 Playwright 检查完整的对话流程。 + +1. 让 Copilot 创建网站集成： + + ```text + Add an accessible Backer Concierge chat widget as an Astro component and render it site-wide from Layout.astro. It should POST to /api/concierge and thread the conversation using the returned opaque conversation handle, follow the dark theme in style.instructions.md, support Escape to close, and include data-testid attributes. + ``` + +2. 保持本地 Function 运行，并在另一个终端中使用 Copilot 提供的命令启动 Astro 网站。 +3. 返回 Copilot CLI。在[练习 4][playwright-lesson]中添加的 Playwright MCP 服务器已可用。让 Copilot 测试组件： + + ```text + Use the Playwright MCP server to test the Backer Concierge widget end to end in the running 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. + ``` + + ![Tailspin Toys 网站中的 Backer Concierge 聊天组件截图](../../../_images/cli-8-backer-concierge-widget.png) + +4. 根据报告中的证据检查结果。如果有任何检查失败，请让 Copilot 修复相关代理或组件的行为，并在结束前重新运行失败的检查。 + +## 清理资源 + +现在已经达到最后一个完成标志：在本地网站中运行的礼宾助手。共用的清理说明涵盖了整个系列中创建的本地服务和 Azure 资源。 + +1. 完成[清理资源][cleanup]中的操作，包括停止本地服务并确认 Azure 资源删除已完成。 + +## 总结和后续步骤 + +本模块通过本地服务端代理和无障碍聊天组件，将托管的 Backer Concierge 连接到了 Tailspin Toys。在整个系列中，使用 GitHub Copilot CLI 和 Foundry 准备了模型、构建并部署了智能体，并验证了完整的网站集成。 + +继续学习[回顾与后续步骤][review]，完成 CLI 工作坊。 + +[overview]: ../ +[previous-lesson]: ../2-build-and-deploy/ +[review]: ../../9-review/ +[playwright-lesson]: ../../4-mcp/ +[cleanup]: ../#清理资源 diff --git a/docs/zh-cn/cli/8-foundry-agent/README.md b/docs/zh-cn/cli/8-foundry-agent/README.md new file mode 100644 index 00000000..0aeed993 --- /dev/null +++ b/docs/zh-cn/cli/8-foundry-agent/README.md @@ -0,0 +1,82 @@ +--- +slug: zh-cn/cli/8-foundry-agent +title: "可选：集成 Foundry" +description: "通过三个模块准备模型、构建并部署基于目录的智能体，以及将其连接到 Tailspin Toys。" +authors: + - juliamuiruri4 +lastUpdated: 2026-09-16 +--- + +本可选系列使用 GitHub Copilot CLI 和 Microsoft Foundry 技能，将 Tailspin Toys 目录变为对话助手。三个模块将从项目和模型设置开始，逐步构建托管智能体，并完成可用的网站集成。 + +在本系列中，将完成以下任务： + +- 准备 Azure 环境，并使用目录测试模型。 +- 为托管的 Backer Concierge 智能体生成脚手架，进行测试并部署。 +- 通过本地服务端代理和聊天组件，将智能体连接到网站。 + +## 场景 + +Tailspin Toys 支持者可以按类别和发行商浏览游戏，但这些筛选条件无法帮助所有人找到下一款游戏。有些支持者会问：*喜欢 Git 双关语的人适合哪些游戏？* 下拉选项无法回答这类问题。 + +Tailspin Toys 希望打造一个 **Backer Concierge** 礼宾助手，通过对话帮助支持者发现游戏。它应推荐 Tailspin 目录中的游戏，在偏好不明确时提出一个简短的澄清问题，并在支持者追问时记住之前的推荐。 + +支持者需要可信的回答。礼宾助手应仅使用目录中的信息，并在某个细节不可用时明确说明，而不是编造游戏、发行商、评分、筹款总额、支持者人数、价格、玩家人数、游戏时长或发布日期。 + +## 选择下一步 + +这些模块在同一个 Tailspin Toys 存储库、分支和 Foundry 项目中逐步推进。每个模块结束时都会得到一个可用的阶段成果。 + +| 模块 | 将完成的任务 | 完成标志 | +| --- | --- | --- | +| [1. 准备项目和模型][project-model] | 设置工具、导出目录，以及选择和测试模型 | 一个能够正确回答目录问题的已部署模型 | +| [2. 构建并部署智能体][build-deploy] | 生成智能体脚手架、测试其行为，并部署到 Foundry | 一个可用的托管 Backer Concierge | +| [3. 将智能体连接到网站][connect-site] | 构建本地代理和聊天组件，然后测试完整流程 | 可通过本地网站使用的礼宾助手 | + +> [!IMPORTANT] +> Microsoft Foundry 托管智能体目前处于公共预览阶段。 +> +> 本系列会创建计费的 Azure 资源，包括模型部署和托管智能体。创建资源前，需要检查所选订阅、区域、配额和预估费用。即使在第一个或第二个模块后停止，也应按照[清理说明][cleanup]操作。 + +1. 要开始本可选系列，请继续学习[准备项目和模型][project-model]，其中包含设置说明。 +2. 如果更想完成核心工作坊，请继续学习[回顾与后续步骤][review]。 + +## 清理资源 + +在任意阶段结束实验后，移除 Azure 资源以避免不必要的费用。清理会移除后续模块所需的资源，因此之后若要继续学习，就需要重新创建这些资源。 + +> [!CAUTION] +> 只有当 `rg-tailspin-toys` 专用于本练习，且不包含任何需要保留的资源时，才可将其删除。删除共享资源组也会移除与本练习无关的资源。 + +1. 在各自的终端中按 Ctrl+C，停止此前启动的所有本地智能体、Function 或 Astro 开发服务器。 +2. 退出 Copilot CLI。如果在模块 2 中生成了智能体脚手架，请在 Tailspin Toys 存储库根目录中，使用同一个 `azd` 环境运行以下命令： + + ```bash + azd down --purge + ``` + +3. 使用 `az account show` 检查所选订阅。查看该订阅中的 `rg-tailspin-toys`，确认所有剩余资源都属于本练习。如果在模块 1 后停止，即使尚未生成 `azd` 服务脚手架，也仍需清理 Foundry 项目和模型。 +4. 如果工作坊专用资源组仍然存在，且仅包含打算移除的资源，请运行： + + ```bash + az group delete --name rg-tailspin-toys --yes --no-wait + ``` + +5. 在 Azure 门户中确认资源组删除已完成。`--no-wait` 命令会在删除完成前返回。 + +## 资源 + +- [Azure Skills 插件][azure-skills] +- [在编码智能体中使用 Microsoft Foundry 技能][foundry-skill] +- [使用 Microsoft Foundry 技能部署第一个托管智能体][hosted-agent-quickstart] +- [托管智能体权限][hosted-agent-permissions] + +[project-model]: 1-project-and-model/ +[build-deploy]: 2-build-and-deploy/ +[connect-site]: 3-connect-to-site/ +[review]: ../9-review/ +[cleanup]: #清理资源 +[azure-skills]: https://github.com/microsoft/azure-skills#github-copilot-cli +[foundry-skill]: https://learn.microsoft.com/azure/foundry/how-to/develop/use-microsoft-foundry-skill?tabs=copilot-cli +[hosted-agent-quickstart]: https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-hosted-agent?pivots=foundry-skills +[hosted-agent-permissions]: https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-permissions diff --git a/docs/zh-cn/cli/9-review.md b/docs/zh-cn/cli/9-review.md index 5b1db087..689b7c86 100644 --- a/docs/zh-cn/cli/9-review.md +++ b/docs/zh-cn/cli/9-review.md @@ -1,5 +1,5 @@ --- -title: "练习 8 - 回顾与后续步骤" +title: "练习 9 - 回顾与后续步骤" authors: - geektrainer lastUpdated: 2026-06-30 @@ -13,6 +13,8 @@ lastUpdated: 2026-06-30 - 调用自定义智能体处理更高级、更复杂的任务。 - 使用斜杠命令管理会话，并可选择通过 `/delegate` 衔接回 cloud agent。 +如果想尝试一项可选挑战，可以[使用 GitHub Copilot CLI 和 Foundry 构建礼宾助手][foundry-lesson]，通过三个模块学习模型设置、智能体开发与部署，以及网站集成。 + 下面再谈谈一些斜杠命令、最佳实践和后续步骤。 ## 斜杠命令 @@ -61,6 +63,7 @@ Copilot CLI 提供了一系列斜杠命令用于交互，其中包括一些可 - [MCP 规范][mcp-spec] [previous-lesson]: ../7-slash-commands/ +[foundry-lesson]: ../8-foundry-agent/ [about-copilot-cli]: https://docs.github.com/copilot/concepts/agents/about-copilot-cli [using-copilot-cli]: https://docs.github.com/copilot/how-tos/use-copilot-agents/use-copilot-cli [awesome-copilot]: https://github.com/github/awesome-copilot diff --git a/docs/zh-cn/cli/README.md b/docs/zh-cn/cli/README.md index 8c640d62..6b0693da 100644 --- a/docs/zh-cn/cli/README.md +++ b/docs/zh-cn/cli/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 **[GitHub Copilot CLI](https://docs.github.com/copilot/concepts/agents/about-copilot-cli)** 将 GitHub Copilot 作为代理式编码助手带入终端。它可以探索代码库、生成代码、运行命令，并连接外部工具——全部通过命令行完成，无需切换到图形化编辑器即可保持工作流畅。 -在这些练习中，将先安装并验证 Copilot CLI，然后通过自定义说明为它提供项目上下文，再使用计划模式有目的地生成一个功能。接着连接 Playwright MCP 服务器，在真实浏览器中测试该功能；然后通过可复用的智能体技能和自定义智能体扩展 Copilot。最后，将探索用于管理上下文、模型和共享的斜杠命令，并回顾已完成的内容。 +在这些练习中，将先安装并验证 Copilot CLI，然后通过自定义说明为它提供项目上下文，再使用计划模式有目的地生成一个功能。接着连接 Playwright MCP 服务器，在真实浏览器中测试该功能；然后通过可复用的智能体技能和自定义智能体扩展 Copilot。最后，将探索用于管理上下文、模型和共享的斜杠命令，并回顾已完成的内容。还可以学习[使用 GitHub Copilot CLI 和 Foundry 的可选系列课程][foundry]，通过三个模块准备模型、构建并部署托管智能体，以及将其集成到网站中。 ## 练习 @@ -22,8 +22,8 @@ lastUpdated: 2026-06-30 | [5. 智能体技能][ex5] | 技能 | 用专门的技能增强 Copilot | | [6. 自定义智能体][ex6] | 智能体 | 查看并使用自定义智能体 | | [7. 斜杠命令][ex7] | CLI 功能 | 探索上下文、模型、共享，以及可选的委托给 cloud agent | -| [8. 构建 Backer Concierge AI 智能体（可选）][foundry] | 托管智能体 | 构建并部署基于目录的 Backer Concierge | | [9. 回顾][ex9] | 总结 | 回顾关键概念和后续步骤 | +| [可选：集成 Foundry][foundry] | 托管智能体 | 准备模型、构建并部署基于目录的 Backer Concierge，并将其连接到网站 | ## 先决条件 diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 0395b4c4..e3d62be3 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -77,8 +77,64 @@ export default defineConfig({ { label: '5. Agent skills', link: '/cli/5-agent-skills/' }, { label: '6. Custom agents', link: '/cli/6-custom-agents/' }, { label: '7. Slash commands', link: '/cli/7-slash-commands/' }, - { label: '8. Build a Backer Concierge AI Agent (Optional)', link: '/cli/8-foundry-agent/' }, { label: '9. Review', link: '/cli/9-review/' }, + { + label: 'Optional: Incorporate Foundry', + translations: { + 'es-ES': 'Opcional: incorpora Foundry', + 'ja-JP': 'オプション: Foundry を組み込む', + 'ko-KR': '선택 사항: Foundry 통합하기', + 'pt-BR': 'Opcional: Incorpore o Foundry', + 'zh-CN': '可选：集成 Foundry', + }, + collapsed: true, + items: [ + { + label: 'Overview', + link: '/cli/8-foundry-agent/', + translations: { + 'es-ES': 'Descripción general', + 'ja-JP': '概要', + 'ko-KR': '개요', + 'pt-BR': 'Visão geral', + 'zh-CN': '概述', + }, + }, + { + label: '1. Prepare the project and model', + link: '/cli/8-foundry-agent/1-project-and-model/', + translations: { + 'es-ES': '1. Prepara el proyecto y el modelo', + 'ja-JP': '1. プロジェクトとモデルを準備する', + 'ko-KR': '1. 프로젝트와 모델 준비하기', + 'pt-BR': '1. Prepare o projeto e o modelo', + 'zh-CN': '1. 准备项目和模型', + }, + }, + { + label: '2. Build and deploy the agent', + link: '/cli/8-foundry-agent/2-build-and-deploy/', + translations: { + 'es-ES': '2. Crea y despliega el agente', + 'ja-JP': '2. エージェントを構築してデプロイする', + 'ko-KR': '2. 에이전트 빌드 및 배포하기', + 'pt-BR': '2. Crie e implante o agente', + 'zh-CN': '2. 构建并部署智能体', + }, + }, + { + label: '3. Connect the agent to the website', + link: '/cli/8-foundry-agent/3-connect-to-site/', + translations: { + 'es-ES': '3. Conecta el agente al sitio web', + 'ja-JP': '3. エージェントを Web サイトに接続する', + 'ko-KR': '3. 에이전트를 웹사이트에 연결하기', + 'pt-BR': '3. Conecte o agente ao site', + 'zh-CN': '3. 将智能体连接到网站', + }, + }, + ], + }, ], }, {