From a6a60a69ac94014f4d84e40c6d6bf3f57872b66a Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 8 Jul 2026 14:04:10 +0100 Subject: [PATCH 1/6] Add TOC.json for foundry toolkit extension --- learn/foundry-toolkit-extension/TOC.json | 1 + 1 file changed, 1 insertion(+) create mode 100644 learn/foundry-toolkit-extension/TOC.json diff --git a/learn/foundry-toolkit-extension/TOC.json b/learn/foundry-toolkit-extension/TOC.json new file mode 100644 index 00000000000..8d1c8b69c3f --- /dev/null +++ b/learn/foundry-toolkit-extension/TOC.json @@ -0,0 +1 @@ + From aa37bfec4e7619a902261b72763116180a9067b8 Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 8 Jul 2026 13:24:22 +0000 Subject: [PATCH 2/6] adding course docs --- .../1-get-started.md | 169 +++++++++++++ .../2-exploring-models.md | 216 +++++++++++++++++ .../3-building-social-media-agent.md | 187 +++++++++++++++ .../4-building-hosted-agent.md | 224 ++++++++++++++++++ learn/foundry-toolkit-extension/TOC.json | 1 - learn/toc.json | 12 + 6 files changed, 808 insertions(+), 1 deletion(-) create mode 100644 learn/foundry-toolkit-extension/1-get-started.md create mode 100644 learn/foundry-toolkit-extension/2-exploring-models.md create mode 100644 learn/foundry-toolkit-extension/3-building-social-media-agent.md create mode 100644 learn/foundry-toolkit-extension/4-building-hosted-agent.md delete mode 100644 learn/foundry-toolkit-extension/TOC.json diff --git a/learn/foundry-toolkit-extension/1-get-started.md b/learn/foundry-toolkit-extension/1-get-started.md new file mode 100644 index 00000000000..2b5f06a6dc7 --- /dev/null +++ b/learn/foundry-toolkit-extension/1-get-started.md @@ -0,0 +1,169 @@ +--- +ContentId: 9e9b38c9-a3a0-4264-8b55-325f0a10d28e +DateApproved: 07/08/2026 +MetaDescription: Get started with Foundry Toolkit in Visual Studio Code, connect your project resources, and prepare for model and agent workflows. +MetaSocialImage: ../images/shared/agent-first-development-social.png +Keywords: + - foundry toolkit + - visual studio code + - onboarding + - setup + - ai foundry + - github copilot +--- + +# Getting Started with Foundry Toolkit in Visual Studio Code + + + +If you are building AI apps or agents, one of the first challenges is tool sprawl: one place for models, another for prompts, another for deployment, and yet another for monitoring. Foundry Toolkit solves that by bringing these workflows into Visual Studio Code, so your daily work can stay in one environment. In this chapter, we will walk through what Foundry Toolkit is, why this approach matters, and how to get from installation to your first connected project. + +## Prerequisites + +Before we install anything, let us make sure your baseline setup is ready. Most onboarding friction comes from environment gaps, not product complexity. If you validate these prerequisites first, the setup flow should complete without detours. + +- **Visual Studio Code**: Installed and updated so extension installation and commands work as expected. +- **Extensions access**: You can open the Extensions view and install marketplace extensions. +- **Cloud account**: A Microsoft account and Azure subscription if you want to create Foundry resources in the cloud. +- **GitHub Copilot**: Optional, but recommended if you want guided prompts and setup automation. + +With the setup baseline in place, we can look at what Foundry Toolkit actually gives you. + +## What Is Foundry Toolkit? + +Foundry Toolkit is a Visual Studio Code extension for building, testing, evaluating, and deploying AI solutions without leaving the editor. Instead of stitching together disconnected tools, you get one integrated workflow that spans model discovery, prompt iteration, agent development, evaluation, fine-tuning, and deployment. That integration is the key value proposition for teams moving from experimentation to repeatable delivery. + +In practical terms, here is what that means for your day-to-day work: + +- **Model discovery**: Browse models across providers from one catalog. +- **Prompt experimentation**: Test and iterate prompts in playground workflows. +- **Agent development**: Build agents with low-code or pro-code approaches. +- **Debugging visibility**: Inspect behavior and execution paths with Agent Inspector. +- **Quality measurement**: Evaluate outputs using built-in metrics. +- **Deployment flow**: Push solutions to production and monitor performance from the same environment. + +Before we jump into setup, it is worth being explicit about what you gain from this workflow shift. + +## Why It Matters + +AI teams often lose momentum by bouncing between portals, scripts, notebooks, and separate deployment surfaces. That context switching is not just inconvenient, it introduces inconsistency and slows feedback loops. Foundry Toolkit helps by making the core workflow cohesive inside Visual Studio Code. + +For example, imagine you are testing two prompt variants for the same campaign brief. In a fragmented workflow, you might run prompts in one tool, track results in another, and deploy from a third interface. In Foundry Toolkit, those actions stay connected, which makes iteration faster and easier to audit. + +The practical benefits show up quickly: + +- **Faster delivery**: Move from idea to a testable agent flow with fewer handoffs. +- **Shorter loops**: Run prompt tests, inspect behavior, and revise in one sitting. +- **Better consistency**: Keep local and cloud workflows aligned so team members can reproduce results. +- **Higher quality**: Catch weak outputs earlier by combining inspection, evaluation, and monitoring. + +Next, let us open the extension and map the layout you will use most often. + +## Extension Layout: What You Will See + +Once Foundry Toolkit is installed, the UI is organized into sections that mirror how teams actually build. Understanding this structure early matters because it reduces discovery time and helps new team members orient quickly. + +As a concrete example, if you want to compare model behavior and then move directly into agent creation, you will typically move within one extension surface rather than switching tools. + +### My Resources + +This section shows what is already available to you, both locally and from connected cloud environments. It is your operational inventory and your fastest way to confirm what is ready to use. + +- **Recent agents**: Quick access to recently created or edited agents. +- **Local resources**: Models, tools, and assets available on your machine. +- **Foundry resources**: Cloud resources connected from your Azure-backed project. +- **Connected resources**: External providers and integrated services. + +Once resources are visible, we can move to the section where you actively build. + +### Developer Tools + +This is where most implementation work happens. You will use it to move from model exploration to agent development and then into validation. As your project grows, this section becomes a practical day-to-day control center. + +For example, a common loop is: open Model Catalog, test a prompt in Playground, then inspect behavior in Agent Inspector without leaving the same extension area. + +- **Discover**: Model catalog and tool catalog, including MCP-based tool collections. +- **Build**: Agent creation, Agent Inspector, hosted agent management, and playground workflows. +- **Monitor**: Tracing, evaluations against expected behavior, and model profiling. + +After building and monitoring, you still need support and feedback channels to keep improving. + +### Feedback + +This section helps you close the loop when something is unclear or when you want to improve the product experience. Teams benefit from this because documentation, support, and feedback are easy to find in context. + +- **Documentation access**: Official guides for features and workflows. +- **Support channels**: Paths to troubleshooting and issue resolution. +- **Feedback routes**: Ways to share product feedback and improvement requests. + +Let us run through the initial setup steps. + +## Getting Started in Visual Studio Code + +In this section, we will complete first-run setup and confirm the extension is ready for use. A clean first run saves time before model and agent work begins. + +Here is a quick example outcome to aim for: you can open Foundry Toolkit from the Visual Studio Code activity area and see Resources plus Developer Tools without any missing setup prompts. +If you prefer menu navigation, the same install path starts at View > Extensions. + +1. Open the Extensions panel in Visual Studio Code. +2. Search for Foundry Toolkit. +3. Install the extension. +4. Open the Foundry Toolkit view from the activity bar. +5. Confirm the key sections are visible. + +Expected result: the extension view loads with My Resources, Developer Tools, and Feedback visible, and no unresolved sign-in/install warnings. At this point, you can explore local capabilities immediately, or continue into cloud-connected setup for Foundry projects. +If those three sections are visible, your chapter-1 setup target is met. + +Next, we will use Copilot to speed up guided onboarding. + +## Using Copilot for Guided Setup + +GitHub Copilot can guide the setup workflow by asking focused follow-up questions and invoking the right actions in sequence. This reduces manual navigation, especially for first-time setup in a new subscription or resource group. + +For example, if you say you already have an Azure subscription but no Foundry project yet, Copilot can route directly into project creation steps and prompt for only the missing details. + +For a new cloud setup, the guided path usually looks like this: + +- **Authentication**: Sign in to Azure. +- **Subscription selection**: Choose the subscription to host the project. +- **Resource group choice**: Pick an existing group or create a new one. +- **Region selection**: Select the deployment region. +- **Project creation**: Name and create the Foundry project. + +After deployment completes, your project appears under My Resources so you can inspect and manage assets in one place. + +Expected result: under your Foundry resources, you should see the new project entry and be able to expand it to inspect available assets. + +After the project is connected, here is what you can manage right away. + +## What You Can Manage After Project Creation + +Once your Foundry project is connected, Visual Studio Code becomes your operational surface for core project resources. You can validate availability, inspect configuration, and move into build workflows without leaving the editor. + +As a concrete example, a team member can confirm deployed models and then open prompt agents in the same session to start building campaign assistants. + +- **Model deployments**: View deployed models and endpoint details. +- **Prompt agents**: Create, inspect, and manage prompt-driven agents. +- **Workflows**: Manage declarative workflows that orchestrate agents and business logic. +- **Hosted resources**: Work with hosted tools, stores, and related runtime assets. +- **Legacy compatibility**: Access classic Foundry resources where needed. + +At this point, you have enough visibility to move into deeper hands-on chapters. + +## What's Next + +You now have the essential foundation for working effectively in Foundry Toolkit inside Visual Studio Code. The next step is to move from setup into active experimentation, where model comparison and prompt iteration shape your first real agent behavior. From there, you can expand into agent creation, evaluation, and deployment with a much smoother learning curve. + +In the next chapter, we will go deeper into model catalog and playground workflows so you can compare model behavior with practical, scenario-based prompts. + +## Learn more + +If you want to continue learning after this chapter, the best next step is to follow the workflow in the same order you will use in real projects. Start with setup and model exploration, then move into agent building and hosted deployment. +The references below are organized to support that progression. + +- **Foundry Toolkit quick start**: Explore first-run guidance and onboarding patterns in the toolkit experience. +- **Foundry Toolkit quick start**: [Watch the chapter walkthrough video](https://youtu.be/aQFSDGAk9DA) for first-run setup and onboarding flow. +- **Model catalog and playground**: [Explore the Model Catalog overview](https://learn.microsoft.com/azure/ai-foundry/how-to/model-catalog-overview) to compare and select models. +- **Agent Builder workflows**: [Follow the Azure AI Agents quickstart](https://learn.microsoft.com/azure/ai-services/agents/quickstart) to build and test agent workflows. +- **Hosted agent lifecycle**: [Review Azure AI Agents concepts and lifecycle guidance](https://learn.microsoft.com/azure/ai-services/agents/overview) for deployment and operations context. + diff --git a/learn/foundry-toolkit-extension/2-exploring-models.md b/learn/foundry-toolkit-extension/2-exploring-models.md new file mode 100644 index 00000000000..9ccb2f04a68 --- /dev/null +++ b/learn/foundry-toolkit-extension/2-exploring-models.md @@ -0,0 +1,216 @@ +--- +ContentId: 63378e8d-67e5-4a11-8480-aee7b7e5078f +DateApproved: 07/08/2026 +MetaDescription: Learn how to shortlist, filter, deploy, and compare models in Model Catalog using Foundry Toolkit and GitHub Copilot. +MetaSocialImage: ../images/shared/agent-first-development-social.png +Keywords: + - model catalog + - model selection + - foundry toolkit + - github copilot + - azure ai foundry + - playground comparison +--- + +# Exploring Models with Model Catalog + + + +When building AI applications, one of the biggest challenges is not implementation, it is model choice. You can have great prompts and solid workflow design, but if the model is mismatched to your scenario, quality and speed will both suffer. In this chapter, we will use Foundry Toolkit in Visual Studio Code to walk a practical selection path from recommendation to side-by-side validation. + +## Prerequisites + +Before we start comparing anything, let us ensure the environment is ready. This chapter depends on both local tooling and cloud availability, so checking setup first prevents noisy failures later. If these prerequisites are in place, every step in the chapter will map cleanly to what you see in the UI. + +- **Visual Studio Code**: Installed and updated so extension workflows and command surfaces are available. +- **Foundry Toolkit extension**: Installed and visible in the activity bar. +- **GitHub Copilot**: Enabled for recommendation-driven model shortlisting. +- **Azure subscription and region**: Selected for deployment checks and quota-aware filtering. +- **Connected Foundry project**: Available in Foundry Toolkit under your resources. + +With setup clarified, let us define exactly what this chapter teaches and how it connects to your day-to-day model work. + +## What You Will Learn + +This chapter is about building a repeatable model selection process, not making one-off guesses. We will combine GitHub Copilot recommendations, Model Catalog filtering, model-card review, deployment, and Playground comparison into one loop you can reuse for future scenarios. By the end, you should be able to justify why a model was chosen, not just that it "felt better." + +- **Shortlist generation**: Use GitHub Copilot to produce an initial set of realistic candidates. +- **Catalog refinement**: Use filters to reduce model options to a relevant subset. +- **Capability validation**: Check model cards before deployment. +- **Deployment readiness**: Push selected candidates into your Foundry project. +- **Behavior comparison**: Evaluate outputs side by side in Playground. + +Before we run the workflow, let us be explicit about why this structure matters. + +## Why Model Selection Matters + +Model selection can become overwhelming very quickly when you have multiple providers, families, sizes, and capability flags. A structured process keeps decisions grounded in evidence and prevents teams from optimizing on preference alone. It also creates traceability, which is important when results need to be explained to stakeholders. + +For example, if your scenario requires image input and deployment in Sweden Central, a model that is excellent in general but unavailable in that region is not a practical choice. This is exactly where a disciplined filter-and-validate workflow saves time. + +In practice, this chapter workflow gives you: + +- **Faster narrowing**: Reduce large candidate sets before deep testing. +- **Higher confidence**: Validate capabilities and availability before committing. +- **Cleaner trade-off analysis**: Compare speed, style, and quality with identical prompts. +- **Better production fit**: Select models that align with quota, region, and deployment constraints. + +At this point, we can begin with GitHub Copilot recommendations. + +## Step 1: Start with GitHub Copilot Recommendations + +Before browsing Model Catalog manually, ask GitHub Copilot for candidate models tied to your specific scenario. This is useful because GitHub Copilot can combine capability requirements with subscription and regional constraints when shaping recommendations. + +1. Open GitHub Copilot Chat in Visual Studio Code. +2. Paste your recommendation prompt. +3. Run the prompt in chat rather than in the terminal. + +A practical prompt from the walkthrough looks like this in spirit: recommend two models for a marketing scenario, with image input support, available in Foundry Toolkit, and deployable in my subscription and region. + +When you run this, GitHub Copilot can evaluate: + +- **Toolkit support**: Whether models are accessible through your current Foundry flow. +- **Regional deployability**: Whether your target region supports the model. +- **Capability fit**: Whether image processing or other required features are present. + +Result: you receive a shortlist, a few viable alternative pairs, and guidance on what to test next. + +From there, move into catalog-level refinement. + +## Step 2: Explore the Model Catalog + +Model Catalog is your central discovery surface for model exploration in Foundry Toolkit. It is where recommendation output turns into actionable filtering and inspection. The key value here is that models from multiple sources are visible through one interface. + +1. Open Foundry Toolkit. +2. Go to Developer Tools. +3. Select Model Catalog before reviewing any specific model. + +In the walkthrough, the ecosystem includes hosted and local options so you are not locked into a single provider strategy. + +- **Microsoft Foundry hosted models**: Cloud-managed options integrated with project workflows. +- **Provider models**: Options from OpenAI, Anthropic, Google, and others. +- **GitHub-hosted models**: Additional candidates for comparison flows. +- **Local models**: ONNX and Ollama-backed runs on your machine. +- **Custom integrations**: Bring-your-own-model extensions where needed. + +Once the catalog is open, reduce noise with focused filters. + +## Step 3: Use Filters to Narrow Candidates + +Filtering is where broad discovery turns into targeted comparison. Instead of scanning dozens of irrelevant options, you define constraints that match your scenario and deployment path. This is especially useful when business requirements include capability-specific needs such as vision input. + +1. Open the filter panel in Model Catalog. +2. Set hosting source, publisher, and image support. +3. Click into individual models only after filters are applied. + +In the video flow, filters are applied for hosting target, publisher, and image support before selecting exact models by name. + +- **Hosting source**: Limit to the hosting path you actually plan to deploy. +- **Publisher**: Compare models within a provider or across providers intentionally. +- **Feature support**: Require capabilities such as image attachment. +- **Runtime type**: Include local CPU, GPU, or NPU options when relevant. +- **Fine-tuning support**: Keep only models that match adaptation requirements. + +What you should see next: your candidate list drops to a manageable set you can inspect in minutes instead of scanning dozens of entries. + +At that point, the next step is model-card validation. + +## Step 4: Review the Model Card + +Before deployment, open each model card and verify what the provider actually guarantees. This prevents hidden mismatch later, especially for pricing, input constraints, or capability assumptions. Think of this as your pre-deployment contract check. + +1. Select one filtered model. +2. Open its model card page. +3. Check capabilities and pricing before moving to deployment. + +In practice, model-card review should answer: can this model do what we need, at acceptable cost, with the expected behavior profile? + +- **Capabilities**: Confirm required modalities and strengths. +- **Use cases**: Check whether your scenario aligns with intended usage. +- **Pricing**: Understand expected token-cost behavior. +- **Technical specs**: Review limits, context details, and operational constraints. + +After validation is complete, deploy shortlisted candidates. + +## Step 5: Deploy Shortlisted Models + +Deployment moves model comparison from theory to hands-on testing. In the walkthrough, two OpenAI candidates are deployed into the same Foundry project so they can be evaluated under identical prompt conditions. + +1. Choose Deploy from the model card. +2. Select your connected Foundry project as the deployment target. + +During deployment, configure only what you need for controlled comparison and keep naming clear so you can track outputs cleanly in Playground. + +- **Deployment name**: Use a name that clearly identifies the model variant. +- **Token throughput settings**: Adjust tokens-per-minute for practical test runs. +- **Project target**: Confirm deployment goes to the intended Foundry project. + +Result: both candidates appear in project resources and are ready for Playground testing. + +When both deployments are ready, run the actual head-to-head comparison. + +## Step 6: Compare Models in Playground + +This section is where model selection becomes evidence-based. Open compare view in Playground and run the same prompt against both models so differences are attributable to model behavior, not prompt drift. + +1. Open Playground. +2. Enable Compare mode. +3. Assign one deployed model to each response pane. + +The walkthrough uses two prompt types to surface different strengths: a marketing-text prompt and a vision extraction prompt. + +In the UI, compare mode is active when you can see two model-labeled response panes side by side under the same prompt input area. + +- **Text prompt**: Generate a short LinkedIn post for developer productivity with AI tools. +- **Vision prompt**: Extract text from an attached image. + +When you inspect outputs, evaluate a consistent set of dimensions: + +- **Latency**: Which model returns usable output faster? +- **Style**: How different are tone, fluency, and structure? +- **Verbosity**: Is the response concise or overly expansive for the task? +- **Scenario fit**: Which output is closer to what the business actually needs? + +Validation target: you can justify model selection based on observed behavior, not preference. + +After choosing a candidate, one important step remains: prompt and parameter refinement. + +## Step 7: Refine Behavior with Prompt and Parameters + +Model choice is only part of quality. You still need to shape output behavior with system instructions and generation controls. This step lets you align responses with voice, audience, and channel constraints before moving deeper into agent workflows. + +1. Add a system prompt in Playground. +2. Tune one generation setting at a time. +3. Evaluate each change before adjusting the next setting. + +A typical refinement pass adds a system prompt and tunes generation controls in small increments, then re-tests with the same scenario prompts. + +- **System prompt**: Set role, tone, and output boundaries. +- **Max response tokens**: Control response length. +- **Temperature**: Tune creativity versus determinism. +- **Top-p**: Adjust token sampling behavior. + +Validation target: selected model outputs become more consistent with your intended style and business constraints. + +Let us recap why this process works. + +## Why This Workflow Works + +The strength of this chapter flow is sequence discipline: shortlist, refine, validate, deploy, compare, and tune. Each stage removes uncertainty before the next stage adds effort. That keeps the process efficient and easier to explain when teams ask why one model was selected over another. + +Instead of relying on intuition, you now have a repeatable selection loop grounded in capability checks, regional constraints, and real prompt outcomes. + +## What's Next + +You are now ready to move from model selection into agent development. In the next chapter, we will use this model-evaluation foundation to build agents that can ask better questions, use tools effectively, and produce outputs that are easier to evaluate and ship. + +## Learn more + +If you want to reinforce this chapter, the best next step is to review the same workflow from three angles: walkthrough, product guidance, and deployment details. This combination helps you move from understanding concepts to applying them in real projects. +Use the links below in order, and you will see the same recommendation-to-comparison flow from both tutorial and reference perspectives. + +- **Chapter video walkthrough**: [Watch the full video for this chapter](https://youtu.be/92tKoJOTays). +- **Model Catalog overview**: [Review the official Model Catalog documentation](https://learn.microsoft.com/azure/ai-foundry/how-to/model-catalog-overview). +- **Foundry SDK development guide**: [Explore SDK-based development guidance for Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/sdk-overview). +- **Model deployment reference**: [See how to deploy OpenAI models in Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/deploy-models-openai). +- **Next-step agent quickstart**: [Continue into Azure AI Agents quickstart](https://learn.microsoft.com/azure/ai-services/agents/quickstart). diff --git a/learn/foundry-toolkit-extension/3-building-social-media-agent.md b/learn/foundry-toolkit-extension/3-building-social-media-agent.md new file mode 100644 index 00000000000..1e8994b1cb3 --- /dev/null +++ b/learn/foundry-toolkit-extension/3-building-social-media-agent.md @@ -0,0 +1,187 @@ +--- +ContentId: f5ce0269-bdf5-4f52-8765-dc9e25edad0f +DateApproved: 07/08/2026 +MetaDescription: Build a social media content agent with Agent Builder, connect MCP tools, and improve quality with structured evaluations. +MetaSocialImage: ../images/shared/agent-first-development-social.png +Keywords: + - agent builder + - prompt agent + - mcp tools + - evaluations + - grounded responses + - social media agent +--- + +# Building a Social Media Content Agent with Agent Builder + + + +This chapter walks through building a practical social media content agent using Agent Builder in Foundry Toolkit. The goal is not just to generate text, but to create an assistant that asks the right follow-up questions, uses trusted context, and returns output that a team can actually review and ship. By the end, you will have a repeatable workflow for moving from idea to tested prompt-agent behavior in Visual Studio Code. + +## Prerequisites + +Before we start building, let us confirm your setup is ready. This chapter combines agent authoring, tool grounding, and evaluation, so a missing prerequisite can break the flow halfway through. If everything below is already in place, you should be able to run the full chapter without detours. + +- **Visual Studio Code setup**: Visual Studio Code with Foundry Toolkit installed. +- **Project access**: A Microsoft Foundry project connected in Foundry Toolkit. +- **Model readiness**: At least one deployed model available to power the agent. +- **GitHub Copilot support**: GitHub Copilot enabled in Visual Studio Code for guided evaluation setup. +- **Evaluation data**: A JSONL dataset (or readiness to generate a synthetic one). + +With setup confirmed, we can define exactly what we are building and why the design choices matter. + +## What You Will Build + +The target outcome is a social content assistant for developer-focused marketing workflows. It will transform rough campaign inputs into structured draft content, while asking clarifying questions when required details are missing. Think of this as an early production prototype, not a one-off demo. + +For example, if the team provides a feature note plus a screenshot but no clear channel objective, the agent should ask what audience and tone are expected before finalizing copy. + +- **Content generation**: Draft LinkedIn copy, short captions, and campaign angles. +- **Input handling**: Work from brief text, feature notes, screenshots, and goals. +- **Quality guardrails**: Follow tone and structure constraints from system instructions. +- **Review readiness**: Return outputs in a format that marketers and developer advocates can validate quickly. + +Before touching configuration screens, let us make explicit why this low-code pattern is valuable. + +## Why This Agent Pattern Matters + +Teams usually need to validate role, tone, and workflow before investing in full coded implementation. Agent Builder gives you a fast validation layer where behavior can be tested in context and improved quickly. That is especially useful when requirements are still moving. + +In short, this pattern lets you answer, "Are we building the right assistant?" before asking, "How do we harden it in code?" + +- **Faster validation**: Confirm behavior without writing full application code. +- **Grounded responses**: Connect to approved sources through MCP tools. +- **Operational quality**: Use evaluation metrics early instead of relying on intuition. +- **Reusable workflow**: Move from prototype to repeatable team process. + +Next, we will walk the build sequence step by step. + +## Step 1: Create the Agent in Agent Builder + +Start in Foundry Toolkit under Developer Tools and open the build path for creating an agent. For this walkthrough, we intentionally use the low-code path first, because it lets us test behavior quickly before coding anything custom. Keep this first version simple and focused on role clarity. + +For consistency with the walkthrough, use a role-specific name and pick a model already deployed in your project. + +- **Navigation path**: Developer Tools -> Build -> Create an agent -> Open Agent Builder. +- **Agent identity**: Use a clear role-focused name such as Dev Social Content Assistant. +- **Model selection**: Choose a model suitable for concise writing, instruction following, and multimodal input. + +Once the shell is in place, the next quality lever is instruction design. + +## Step 2: Define Strong Instructions + +A strong system prompt defines role, audience, boundaries, and output shape in concrete terms. This matters because vague instructions usually produce vague marketing copy and inconsistent follow-up behavior. Here, we optimize for a credible developer-first voice and reviewable output structure. + +As a practical example, ask the agent to separate final copy from rationale so reviewers can quickly distinguish deliverable output from internal reasoning. + +- **Role clarity**: Support a social media team producing developer-facing content. +- **Behavior rules**: Ask follow-up questions when required details are missing. +- **Tone constraints**: Avoid exaggerated claims and include clear technical value. +- **Output structure**: Separate final copy from rationale and assumptions. + +After instructions look solid, save the agent so it becomes a reusable project asset. + +## Step 3: Save and Register the Prompt Agent + +After defining instructions, save the agent to your Foundry project so it appears in project resources. This turns a temporary editing session into a trackable artifact the team can revisit. It also gives you a clean base version before adding tools. + +Checkpoint: you should be able to open your project resources and find the agent under Prompt Agents. + +- **Persistence**: Save the configured prompt agent to Microsoft Foundry. +- **Resource location**: Confirm it appears under Prompt Agents in project resources. + +Now we can improve factual reliability by connecting the agent to trusted sources. + +## Step 4: Add MCP Tools for Grounded Context + +A reliable content agent should not rely only on base-model memory. In this workflow, MCP connects the agent to authoritative Microsoft documentation through the Microsoft Learn MCP server. This is the shift from plausible output to grounded output. + +For this scenario, grounding matters whenever campaign text references product capabilities, release details, or platform behavior. + +- **Tool catalog action**: Add a Foundry tool and select Microsoft Learn MCP. +- **Grounding strategy**: Use docs search to locate official sources first. +- **Content retrieval**: Use fetch tools to retrieve full documentation context. +- **Reliability rule**: Instruct the agent to avoid guessing or fabricating Microsoft facts. + +Adding tools alone is not enough, so the next step is to teach the agent when to use them. + +## Step 5: Add Tool-Use Guidance to Instructions + +Adding tools is only half the job. You also need instruction-level guidance that tells the agent when tool calls are required and how to sequence them. Without this, the agent may skip retrieval or call tools inconsistently. + +In practice, you want explicit trigger logic such as: if the prompt asks about Microsoft technologies, retrieve official docs before drafting output. + +- **Decision logic**: Detect when the user asks about Microsoft technologies. +- **Planning behavior**: Identify what information is required before generating copy. +- **Tool selection**: Route to the appropriate Microsoft Learn MCP tools. +- **Grounded output**: Base responses on validated sources rather than prior assumptions. + +At this stage, run realistic tests in the playground. + +## Step 6: Test in the Agent Playground + +With instructions and tools configured, run realistic prompts directly in Agent Builder playground. Use prompts that reflect the actual campaign requests your team receives, not synthetic one-liners. Behavior quality becomes visible quickly in this step. + +For example, ask for a LinkedIn post about the GitHub Copilot app for a developer audience and check whether the assistant both retrieves trusted context and asks useful follow-up questions. + +- **Tool verification**: Confirm docs search is invoked against Microsoft Learn. +- **Response quality**: Check draft usefulness, structure, and call-to-action placement. +- **Follow-up behavior**: Ensure the agent asks clarifying questions when needed. +- **Transparency**: Validate that rationale is shown when requested. + +Manual testing is useful, but the next step is where quality becomes measurable. + +## Step 7: Scale Validation with Evaluations + +Manual playground testing is useful, but it does not scale well for repeatable quality control. This step introduces built-in evaluation workflows so you can score behavior against clear metrics over multiple test rows. It is the difference between impression-based review and evidence-based review. + +If you do not yet have production traces, generate a synthetic dataset first and iterate from there. + +- **Evaluation setup**: Open Evaluations and select the target agent. +- **Scoring rubric**: Use metrics such as task adherence, fluency, relevance, and groundedness. +- **Dataset path**: Upload an existing JSONL dataset or generate a synthetic dataset. +- **Judge model**: Use an LLM judge to compare actual responses against expected candidates. + +UI cue: when the run is done, the evaluation status changes to Completed and the report-opening action becomes available. + +Once the run completes, the real value comes from diagnosis and iteration. + +## Step 8: Review Results and Iterate + +After the batch evaluation completes, inspect both aggregate scores and row-level details. Aggregate numbers show trend direction, but row-level analysis reveals why behavior failed. Here you find concrete fixes for instruction wording, tool routing, or output formatting. + +Treat this as an iterative loop: update, re-run, compare, and document what improved. + +- **Aggregate review**: Evaluate overall performance across each metric. +- **Row diagnostics**: Inspect output, numeric scores, and scoring rationale per test row. +- **Refinement loop**: Update prompt and tool guidance, then run evaluation again. +- **Version discipline**: Re-evaluate every major agent change or feature addition. + +We have now completed the full loop, so let us summarize why this process is effective. + +## Why This Workflow Works + +This chapter demonstrates a complete low-code lifecycle: define role, ground with tools, test behavior, and evaluate systematically. The sequence is intentionally practical and repeatable, so teams can improve quality before broad rollout. It also gives you a shared language for discussing agent quality across product and engineering roles. + +- **Prototype quickly**: Build useful behavior before pro-code investment. +- **Ground responsibly**: Connect to approved sources through MCP. +- **Measure objectively**: Use metrics and datasets to guide improvements. +- **Deploy confidently**: Share a better-tested agent with stakeholders. + +The natural next step is deeper engineering and production hardening. + +## What's Next + +After validating a prompt-based social content assistant, the next step is deeper agent engineering. You can expand into richer tool orchestration, stronger datasets, and production-focused deployment and monitoring workflows. The next chapter builds on this foundation so behavior quality remains strong as complexity increases. + +## Learn more + +If you want to deepen this chapter after the hands-on flow, use the resources below as a guided extension path. Start with agent fundamentals, then move into implementation and deployment references so each link builds on the previous one. +This order mirrors how teams usually mature from prompt-agent prototypes to production-ready agent workflows. + +- **Azure AI Foundry overview**: [Understand the broader platform and workflow surface](https://learn.microsoft.com/azure/ai-foundry/). +- **Azure AI Agents overview**: [Review core agent concepts and lifecycle guidance](https://learn.microsoft.com/azure/ai-services/agents/overview). +- **Azure AI Agents quickstart**: [Build and run a practical agent end-to-end](https://learn.microsoft.com/azure/ai-services/agents/quickstart). +- **Foundry SDK development guide**: [Explore SDK-based implementation patterns](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/sdk-overview). +- **Azure Developer CLI documentation**: [Use azd for repeatable project and deployment workflows](https://learn.microsoft.com/azure/developer/azure-developer-cli/). +- **Model deployment reference**: [Deploy OpenAI models in Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/deploy-models-openai). \ No newline at end of file diff --git a/learn/foundry-toolkit-extension/4-building-hosted-agent.md b/learn/foundry-toolkit-extension/4-building-hosted-agent.md new file mode 100644 index 00000000000..a2e5b9b4362 --- /dev/null +++ b/learn/foundry-toolkit-extension/4-building-hosted-agent.md @@ -0,0 +1,224 @@ +--- +ContentId: 48bcead9-78df-4695-9d8e-e17a8a598a7a +DateApproved: 07/08/2026 +MetaDescription: Scaffold, debug, and deploy a hosted agent with GitHub Copilot CLI, Agent Inspector, and Microsoft Foundry. +MetaSocialImage: ../images/shared/agent-first-development-social.png +Keywords: + - hosted agent + - github copilot cli + - agent inspector + - azure developer cli + - microsoft foundry + - agent deployment +--- + +# Building a Hosted Agent with GitHub Copilot and Microsoft Foundry + + + + +Low-code agents are great for proving behavior quickly, but most teams eventually need stronger control over code, deployment, and integration. In this chapter, we move into a code-first workflow and build a hosted agent that can be developed locally, debugged with tooling, and deployed into Microsoft Foundry. By the end, you will have a practical blueprint for going from prompt idea to production-oriented hosted execution. + +## Prerequisites + +Before we start, make sure your environment can support both local debugging and hosted deployment. This chapter combines GitHub Copilot CLI, Foundry Toolkit, and Azure deployment assets, so missing setup usually slows things down in the middle of the workflow. If you validate these prerequisites first, the rest of the chapter stays focused on agent engineering, not environment troubleshooting. + +- **Editor and extension**: Visual Studio Code with Foundry Toolkit installed. +- **GitHub Copilot access**: GitHub Copilot available in Visual Studio Code and terminal workflows. +- **Cloud context**: An Azure subscription and Microsoft Foundry project. +- **Model deployment**: A GPT-5 model instance already deployed in your project. +- **CLI readiness**: Azure Developer CLI and ability to sign in to Azure. + +With the environment ready, we can define what this agent actually does and why the code-first path changes your delivery options. + +## What You Will Build + +In this chapter, you create a code-based social campaign assistant for developer-focused content creation. Unlike a prompt-only prototype, this version is source-controlled, inspectable, and deployable as a hosted agent. Think of it as the bridge between experimentation and production-ready team workflows. + +For example, if your team wants custom business logic, repeatable deployment, and integration with app code, this architecture gives you a direct path without rebuilding everything from scratch. + +- **Agent scaffold**: A coded project generated with GitHub Copilot CLI prompts. +- **Reusable tools**: A Foundry toolbox with Microsoft Learn MCP and web search. +- **Local runtime**: HTTP-based local agent service for invoke and debug loops. +- **Hosted target**: Deployment path to a managed hosted agent in Foundry. + +Before we get hands-on, it helps to anchor the practical reason teams choose this model. + +## Why Move to a Code-Based Agent + +Teams choose coded agents when they need deeper control than a low-code builder can provide. That usually includes business-specific logic, deterministic configuration files, repeatable deployment, and direct integration with application code. In other words, code-based agents are not about complexity for its own sake, they are about control, reliability, and team-scale maintainability. + +If you have ever asked, "How do we make this agent predictable across environments?" this is the workflow that answers that question. + +- **Control**: Version prompts, runtime settings, and dependencies in source control. +- **Extensibility**: Add custom logic and richer tool orchestration patterns. +- **Repeatability**: Reproduce environments through config and infrastructure files. +- **Production fit**: Deploy and operate through a hosted agent lifecycle. + +The rest of the chapter follows the real delivery order most teams use, from scaffold to hosted deployment. + +## Step 1: Scaffold the Solution with GitHub Copilot CLI + +Start by launching GitHub Copilot CLI in the terminal and describing the target solution in natural language. For this chapter, the scaffold prompt includes campaign-assistant behavior, clarifying-question behavior, retrieval tools, GPT-5 model usage, and hosted deployability. The key is to be explicit in one prompt so generation stays aligned with your intended architecture. + +1. Open a terminal in your working folder. +2. Start GitHub Copilot CLI in that folder. +3. Confirm generated files are created in the intended project location. + +A practical pattern is to include both functionality and operational constraints in the same request, for example, "configure toolbox tools and open the project folder when done." + +- **Natural language spec**: Describe behavior, tools, model, and deployment intent. +- **Autopilot mode**: Allow GitHub Copilot to execute multi-step setup with fewer interruptions. +- **Expected output**: A generated project folder and initial implementation artifacts. + +At this point, you should already have a project skeleton on disk. The immediate check is whether tool strategy was scaffolded for reuse instead of hard-coded inside one file. + +## Step 2: Create and Attach a Foundry Toolbox + +The scaffold includes a toolbox so tools can be reused across agents instead of being embedded ad hoc. In this workflow, the toolbox includes Microsoft Learn MCP for official documentation and web search for fresh external context. This matters because it centralizes retrieval behavior and reduces copy-paste tool wiring across projects. + +1. Open your project in Foundry Toolkit. +2. Navigate to the tool configuration area. +3. Add Microsoft Learn MCP and web search. + +For this scenario, one tool covers trusted product facts and one tool covers current web context, which is a practical retrieval split for campaign generation. + +- **Microsoft grounding**: Use Learn MCP for validated product and docs context. +- **Freshness path**: Use web search for recent or time-sensitive information. +- **Reuse model**: Keep tool definitions portable across multiple agents. + +With tools attached, spend a minute reading the generated assets so you can predict behavior before you execute anything. + +## Step 3: Review What GitHub Copilot Generated + +After generation, inspect the project artifacts to understand runtime behavior and deployment shape. This review step is important because it lets you verify that generation used Foundry-specific context, not generic app scaffolding patterns. You should be able to explain what each core file controls before running anything. + +1. Open the generated folder in Visual Studio Code. +2. Inspect main.py. +3. Inspect agent.yaml. +4. Inspect toolbox.yaml. +5. Inspect azure.yaml. + +Use this quick map as you scan the folder: one file controls runtime behavior, one defines agent metadata, one configures tools, and one drives infrastructure. + +- **Main runtime**: `main.py` contains the core assistant logic and runtime wiring. +- **Agent config**: `agent.yaml` defines behavior, hosting, protocol, and runtime settings. +- **Tool config**: `toolbox.yaml` describes connected tools and tool endpoints. +- **Deployment config**: `azure.yaml` and `infra/` Bicep templates drive provisioning and deploy. + +If any file role looks unclear here, stop and resolve it before deployment. Ambiguity at this step usually becomes expensive once cloud resources are involved. + +## Step 4: Run and Invoke the Agent Locally + +Before deploying, validate local behavior from terminal-based commands. This gives you a fast feedback loop and catches instruction or runtime issues before cloud resources are involved. In the chapter flow, local invoke confirms the expected clarifying-question behavior. + +1. Run `azd ai agent run` from the project root. +2. Wait until the local runtime reports it is ready. +3. Invoke prompts only after the runtime is ready. + +For example, after invoking with a campaign prompt, you should see targeted follow-up questions about audience, goals, and call-to-action details. + +- **Local run**: Start the agent runtime with `azd ai agent run`. +- **Prompt test**: Invoke with `azd ai agent invoke` and a realistic campaign request. +- **Behavior check**: Confirm clarifying questions, tone control, and campaign framing. + +A clean local run proves basic behavior, but it does not prove observability. The next step adds that missing visibility. + +## Step 5: Configure Agent Inspector Integration + +To inspect and troubleshoot deeply, configure the project for Agent Inspector. The chapter flow uses GitHub Copilot to verify HTTP serving requirements, install dependencies, and prepare Visual Studio Code debug configuration. This is where your project becomes easy to debug repeatedly, not just runnable once. + +1. Open the Run and Debug panel in Visual Studio Code. +2. Confirm there is a valid launch configuration. +3. Press F5. + +A practical success signal is that pressing F5 launches the local agent plus inspector workflow without manual setup steps. If F5 fails, fix launch and environment wiring now rather than diagnosing inside hosted runs later. + +- **HTTP readiness**: Ensure the agent is served as an HTTP service. +- **Dependencies**: Install or reconcile required packages in the environment. +- **Debug config**: Add `.vscode/tasks.json` and `.vscode/launch.json`. +- **Runtime prep**: Select interpreter, activate virtual environment, and authenticate Azure. + +Once inspector wiring is in place, you can evaluate cause and effect directly instead of guessing from final output text. + +## Step 6: Debug with Agent Inspector + +Start debugging and open Agent Inspector to observe live runtime behavior. This gives you direct visibility into events, streaming deltas, metadata, traces, and tool calls. In practice, this is where agent development shifts from black-box guessing to inspectable engineering. + +1. Launch the debug session. +2. Submit one simple prompt. +3. Confirm a trace appears in the inspector timeline. + +As you test prompts, watch the event timeline and trace views to confirm that responses are progressing as expected and not silently skipping retrieval logic. + +- **Event timeline**: Inspect response lifecycle states and token progression. +- **Tool visibility**: Review each tool call input, output, and invocation reason. +- **Trace analysis**: Use tracing views to diagnose behavior divergence quickly. +- **Iteration loop**: Prompt, inspect, refine instructions, and retest. + +After one clean trace, force a prompt that cannot be answered well without retrieval so tool wiring gets a real stress test. + +## Step 7: Validate Tool Usage in Real Prompts + +Use follow-up prompts that force retrieval behavior so integrations are actually exercised. In the chapter flow, the agent invokes web search and returns multiple structured content options with call-to-action guidance. This step confirms that tool calls are not only configured but operationally useful. + +1. Submit a Microsoft product question that requires current facts. +2. Verify a tool call appears before the final response. + +For validation, do not stop at final output text. Inspect tool call inputs and outputs so you can verify retrieval quality, not just generation style. + +- **Tool invocation proof**: Confirm web search calls appear in inspector tooling views. +- **Output quality**: Check that response options remain technical and audience-specific. +- **Auditability**: Inspect each retrieval call and response shaping path. + +When retrieval behavior is stable and traceable, you are ready to spend cloud deployment effort. + +## Step 8: Deploy as a Hosted Agent + +Deploy the agent through the Foundry deployment experience after local validation is complete. The flow uses a Docker image path and Azure Container Registry, then publishes as a new hosted agent. This is the handoff from local development to cloud-hosted execution. + +1. Open the deployment flow from your project context. +2. Choose the Docker-based path. +3. Confirm the target Foundry project before publishing. + +Keep deployment settings explicit so runtime sizing and image source are traceable when debugging production behavior later. + +- **Deployment method**: Build and deploy from Docker configuration. +- **Hosting target**: Use Foundry-managed container registry defaults when appropriate. +- **Runtime sizing**: Set CPU and memory profile for the hosted agent. +- **Publish outcome**: Create the hosted agent resource in your Foundry project. + +After publish completes, run the same scenario in the cloud playground and compare behavior against your local baseline. + +## Step 9: Test the Cloud-Hosted Agent + +Open the hosted agent in Foundry project resources and test from the cloud playground. This mirrors local testing while validating the production-like hosted path. The objective is to confirm that behavior remains consistent after deployment. + +1. Run the same prompt used in local testing. +2. Compare follow-up questions between local and hosted runs. +3. Compare tool usage between local and hosted traces. + +A useful check here is to run the same prompt you used locally and compare follow-up question quality, tool usage, and output structure. + +- **Resource checks**: Verify status, details, and runtime health. +- **Cloud interaction**: Run campaign prompts against hosted endpoints. +- **Operational insight**: Review traces and behavior under hosted execution. + +At this point, you have executed the full lifecycle from scaffold to hosted runtime, so we can summarize why this flow holds up in team settings. + +## Why This Workflow Works + +This chapter demonstrates how GitHub Copilot CLI, Foundry skills, Agent Framework, Agent Inspector, and hosted deployment connect into one coherent engineering loop. Instead of treating the agent as a black box, this workflow makes behavior observable, testable, and repeatable. That combination is what turns prototypes into maintainable systems. + +In practical terms, each stage removes a specific risk before the next stage adds cost. + +- **Engineering transparency**: Inspect tool calls, events, and traces end to end. +- **Quality control**: Catch behavioral drift before shipping to stakeholders. +- **Scalable delivery**: Move from prototype to hosted deployment with fewer manual steps. +- **Team readiness**: Produce a source-controlled agent that can be evolved safely. + +From here, the next move is release hardening so future updates stay predictable. + +## What's Next + +After shipping a hosted code-based agent, the next step is hardening the lifecycle for ongoing releases. Focus on stronger evaluation pipelines, tracing-driven debugging practices, and automation for deployment and regression checks as agent scope grows. The next chapter should feel like an extension of this workflow, not a reset. \ No newline at end of file diff --git a/learn/foundry-toolkit-extension/TOC.json b/learn/foundry-toolkit-extension/TOC.json deleted file mode 100644 index 8d1c8b69c3f..00000000000 --- a/learn/foundry-toolkit-extension/TOC.json +++ /dev/null @@ -1 +0,0 @@ - diff --git a/learn/toc.json b/learn/toc.json index 45c436e5388..a51fc275b57 100644 --- a/learn/toc.json +++ b/learn/toc.json @@ -1,4 +1,16 @@ [ + { + "name": "Foundry Toolkit extension for Visual Studio Code", + "area": "foundry-toolkit-extension", + "description": "Learn how to use Foundry Toolkit in VS Code to get started, explore models, build agents, and deploy hosted agent workflows.", + + "topics": [ + ["Getting started with Foundry Toolkit in Visual Studio Code", "/learn/foundry-toolkit-extension/1-get-started"], + ["Exploring models with Model Catalog", "/learn/foundry-toolkit-extension/2-exploring-models"], + ["Building a social media content agent with Agent Builder", "/learn/foundry-toolkit-extension/3-building-social-media-agent"], + ["Building a hosted agent with GitHub Copilot and Microsoft Foundry", "/learn/foundry-toolkit-extension/4-building-hosted-agent"] + ] + }, { "name": "Agent Foundations", "area": "foundations", From 09fe9d07f490c4074dab580d9d750ee9a19c6dee Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 8 Jul 2026 13:27:46 +0000 Subject: [PATCH 3/6] removed yml issue --- learn/foundry-toolkit-extension/1-get-started.md | 12 ++++++------ .../foundry-toolkit-extension/2-exploring-models.md | 12 ++++++------ .../3-building-social-media-agent.md | 12 ++++++------ .../4-building-hosted-agent.md | 12 ++++++------ 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/learn/foundry-toolkit-extension/1-get-started.md b/learn/foundry-toolkit-extension/1-get-started.md index 2b5f06a6dc7..c47cdb0249e 100644 --- a/learn/foundry-toolkit-extension/1-get-started.md +++ b/learn/foundry-toolkit-extension/1-get-started.md @@ -4,12 +4,12 @@ DateApproved: 07/08/2026 MetaDescription: Get started with Foundry Toolkit in Visual Studio Code, connect your project resources, and prepare for model and agent workflows. MetaSocialImage: ../images/shared/agent-first-development-social.png Keywords: - - foundry toolkit - - visual studio code - - onboarding - - setup - - ai foundry - - github copilot + - foundry toolkit + - visual studio code + - onboarding + - setup + - ai foundry + - github copilot --- # Getting Started with Foundry Toolkit in Visual Studio Code diff --git a/learn/foundry-toolkit-extension/2-exploring-models.md b/learn/foundry-toolkit-extension/2-exploring-models.md index 9ccb2f04a68..32c50cdfc48 100644 --- a/learn/foundry-toolkit-extension/2-exploring-models.md +++ b/learn/foundry-toolkit-extension/2-exploring-models.md @@ -4,12 +4,12 @@ DateApproved: 07/08/2026 MetaDescription: Learn how to shortlist, filter, deploy, and compare models in Model Catalog using Foundry Toolkit and GitHub Copilot. MetaSocialImage: ../images/shared/agent-first-development-social.png Keywords: - - model catalog - - model selection - - foundry toolkit - - github copilot - - azure ai foundry - - playground comparison + - model catalog + - model selection + - foundry toolkit + - github copilot + - azure ai foundry + - playground comparison --- # Exploring Models with Model Catalog diff --git a/learn/foundry-toolkit-extension/3-building-social-media-agent.md b/learn/foundry-toolkit-extension/3-building-social-media-agent.md index 1e8994b1cb3..216c00990f5 100644 --- a/learn/foundry-toolkit-extension/3-building-social-media-agent.md +++ b/learn/foundry-toolkit-extension/3-building-social-media-agent.md @@ -4,12 +4,12 @@ DateApproved: 07/08/2026 MetaDescription: Build a social media content agent with Agent Builder, connect MCP tools, and improve quality with structured evaluations. MetaSocialImage: ../images/shared/agent-first-development-social.png Keywords: - - agent builder - - prompt agent - - mcp tools - - evaluations - - grounded responses - - social media agent + - agent builder + - prompt agent + - mcp tools + - evaluations + - grounded responses + - social media agent --- # Building a Social Media Content Agent with Agent Builder diff --git a/learn/foundry-toolkit-extension/4-building-hosted-agent.md b/learn/foundry-toolkit-extension/4-building-hosted-agent.md index a2e5b9b4362..1e844ac2cdc 100644 --- a/learn/foundry-toolkit-extension/4-building-hosted-agent.md +++ b/learn/foundry-toolkit-extension/4-building-hosted-agent.md @@ -4,12 +4,12 @@ DateApproved: 07/08/2026 MetaDescription: Scaffold, debug, and deploy a hosted agent with GitHub Copilot CLI, Agent Inspector, and Microsoft Foundry. MetaSocialImage: ../images/shared/agent-first-development-social.png Keywords: - - hosted agent - - github copilot cli - - agent inspector - - azure developer cli - - microsoft foundry - - agent deployment + - hosted agent + - github copilot cli + - agent inspector + - azure developer cli + - microsoft foundry + - agent deployment --- # Building a Hosted Agent with GitHub Copilot and Microsoft Foundry From 1d73f33fbb6aaf0861d382378e6ab8b34e86861f Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 15 Jul 2026 11:26:31 +0000 Subject: [PATCH 4/6] updating chapters to latest --- .../1-get-started.md | 175 ++++++++----- .../2-exploring-models.md | 229 ++++++++++------ .../3-building-social-media-agent.md | 197 +++++++++----- .../4-building-hosted-agent.md | 246 ++++++++++-------- 4 files changed, 530 insertions(+), 317 deletions(-) diff --git a/learn/foundry-toolkit-extension/1-get-started.md b/learn/foundry-toolkit-extension/1-get-started.md index c47cdb0249e..077983de71a 100644 --- a/learn/foundry-toolkit-extension/1-get-started.md +++ b/learn/foundry-toolkit-extension/1-get-started.md @@ -16,24 +16,67 @@ Keywords: -If you are building AI apps or agents, one of the first challenges is tool sprawl: one place for models, another for prompts, another for deployment, and yet another for monitoring. Foundry Toolkit solves that by bringing these workflows into Visual Studio Code, so your daily work can stay in one environment. In this chapter, we will walk through what Foundry Toolkit is, why this approach matters, and how to get from installation to your first connected project. +You know that moment when a prototype looks great, but the team still feels slow? Usually it is not the model quality. It is workflow sprawl: model lookup in one place, prompt testing in another, deployment checks somewhere else. + +In this chapter, we'll make that into one flow inside Visual Studio Code so day-to-day work feels clear, fast, and honestly more fun. + +No more tab Olympics, I promise. + +By the end, you will have Foundry Toolkit installed, connected, and ready for real model and agent work. You will not just know where to click, you will understand why this setup order works and why the next chapters feel lighter because of it. + +> The goal is simple: less setup friction, more building. + +Each setup step is useful on its own. +The real magic shows up when they all work together. + +## What You Will Learn + +Before we jump in, let's set a concrete target. This is not a random feature tour. It is a practical build path to a workspace you can trust for the rest of the series. + +In this chapter, you will learn to: + +- **Set up a ready workspace**: Install Foundry Toolkit and confirm key surfaces are visible. +- **Connect a cloud project**: Attach a Foundry project so you can move from local exploration to real cloud assets. +- **Run a repeatable first flow**: Follow a sequence your team can reuse for future contributors. + +Now that the destination is clear, here is the one idea that makes everything else click. + +A quick map helps you see the chapter flow before we zoom in. Think of it as your "you are here" sign while you move through setup. + +![Chapter 1 journey diagram](../images/ch01-fig01-journey.png) + +**Fig 01: Chapter 1 journey from first install to model-ready workspace.** + +## Problem Framing: Why One Workspace Changes Learning Speed + +A useful way to think about Foundry Toolkit is as a feedback-loop accelerator, not just an extension with more buttons. When discovery, prompt testing, agent setup, and deployment checks live in one place, you spend less time tab-hopping and more time improving results. + +Small shift, big payoff. Especially once more people join the project. + +**Try this** + +If you want a quick test, compare two workflows: one where you bounce between portals and docs, and one where you stay in Visual Studio Code for most tasks. The second flow usually means faster iteration, fewer handoff mistakes, and much clearer ownership when multiple people touch the same project. ## Prerequisites -Before we install anything, let us make sure your baseline setup is ready. Most onboarding friction comes from environment gaps, not product complexity. If you validate these prerequisites first, the setup flow should complete without detours. +Before we install anything, let's do a quick readiness check. Most first-run friction comes from environment gaps, not product complexity. + +If you validate these now, you avoid the annoying detours later. - **Visual Studio Code**: Installed and updated so extension installation and commands work as expected. - **Extensions access**: You can open the Extensions view and install marketplace extensions. - **Cloud account**: A Microsoft account and Azure subscription if you want to create Foundry resources in the cloud. -- **GitHub Copilot**: Optional, but recommended if you want guided prompts and setup automation. +- **GitHub Copilot**: Optional, but highly recommended if you want guided prompts and setup automation. + +With that baseline in place, we can look at what Foundry Toolkit actually gives you. -With the setup baseline in place, we can look at what Foundry Toolkit actually gives you. +Quick confidence check: if you can open Extensions, install tooling, and sign in when prompted, you are already through the hardest part. ## What Is Foundry Toolkit? -Foundry Toolkit is a Visual Studio Code extension for building, testing, evaluating, and deploying AI solutions without leaving the editor. Instead of stitching together disconnected tools, you get one integrated workflow that spans model discovery, prompt iteration, agent development, evaluation, fine-tuning, and deployment. That integration is the key value proposition for teams moving from experimentation to repeatable delivery. +Foundry Toolkit is a Visual Studio Code extension for building, testing, evaluating, and deploying AI solutions without leaving the editor. Instead of stitching together disconnected tools, you get one integrated flow for model discovery, prompt iteration, agent development, evaluation, fine-tuning, and deployment. -In practical terms, here is what that means for your day-to-day work: +To get you excited, here is a quick list of the core capabilities you will use in this chapter and beyond: - **Model discovery**: Browse models across providers from one catalog. - **Prompt experimentation**: Test and iterate prompts in playground workflows. @@ -42,32 +85,44 @@ In practical terms, here is what that means for your day-to-day work: - **Quality measurement**: Evaluate outputs using built-in metrics. - **Deployment flow**: Push solutions to production and monitor performance from the same environment. -Before we jump into setup, it is worth being explicit about what you gain from this workflow shift. +Here's the extension you're about to install. It is the one surface you will keep coming back to for most of the series. + +![Foundry Toolkit](../images/foundry-toolkit.png) -## Why It Matters +**Fig 1: Foundry Toolkit Extension in Visual Studio Code** -AI teams often lose momentum by bouncing between portals, scripts, notebooks, and separate deployment surfaces. That context switching is not just inconvenient, it introduces inconsistency and slows feedback loops. Foundry Toolkit helps by making the core workflow cohesive inside Visual Studio Code. +## Exercise - install Foundry Toolkit -For example, imagine you are testing two prompt variants for the same campaign brief. In a fragmented workflow, you might run prompts in one tool, track results in another, and deploy from a third interface. In Foundry Toolkit, those actions stay connected, which makes iteration faster and easier to audit. +Let's install Foundry Toolkit so we can get started on the next steps. You can install it from the Visual Studio Code marketplace or directly from the Extensions view. -The practical benefits show up quickly: +1. Open Visual Studio Code and then open the Extensions view from the activity bar. -- **Faster delivery**: Move from idea to a testable agent flow with fewer handoffs. -- **Shorter loops**: Run prompt tests, inspect behavior, and revise in one sitting. -- **Better consistency**: Keep local and cloud workflows aligned so team members can reproduce results. -- **Higher quality**: Catch weak outputs earlier by combining inspection, evaluation, and monitoring. +2. Search for "Foundry Toolkit" in the search bar. +3. Click "Install" on the Foundry Toolkit extension. -Next, let us open the extension and map the layout you will use most often. +That's it, you now have the extension installed and ready to use. Next, we will explore the layout and key sections of the extension. ## Extension Layout: What You Will See -Once Foundry Toolkit is installed, the UI is organized into sections that mirror how teams actually build. Understanding this structure early matters because it reduces discovery time and helps new team members orient quickly. +Once you've installed Foundry Toolkit, you should know the layout and where to find the tools you need. The extension is organized into three main sections: My Resources, Developer Tools, and Feedback. + +Once Foundry Toolkit is installed, the UI is organized into sections that mirror how teams actually build. Learning this layout early saves discovery time and helps new teammates get oriented much faster. + +Here's a diagram showing the three main sections and how they relate to each other. -As a concrete example, if you want to compare model behavior and then move directly into agent creation, you will typically move within one extension surface rather than switching tools. +![Foundry Toolkit architecture diagram](../images/ch01-fig03-toolkit-architecture.png) + +**Fig 02: Foundry Toolkit information architecture and core working areas.** + +You should now see one clean mental model: resources on one side, building tools in the middle, and support routes on demand. Once that clicks, the next steps feel way less heavy. ### My Resources -This section shows what is already available to you, both locally and from connected cloud environments. It is your operational inventory and your fastest way to confirm what is ready to use. +This section shows what is already available to you, both locally and from connected cloud environments. Think of it as your inventory and your fastest "am I good to go?" check. + +If you are unsure whether setup worked, start here first. A quick look in My Resources usually tells you whether you can continue or still need one more connection. + +If this section looks right, you are in great shape. - **Recent agents**: Quick access to recently created or edited agents. - **Local resources**: Models, tools, and assets available on your machine. @@ -76,9 +131,17 @@ This section shows what is already available to you, both locally and from conne Once resources are visible, we can move to the section where you actively build. +![Foundry Toolkit resources](../images/foundry-toolkit-resources.png) + +**Fig 03: Foundry Toolkit My Resources section showing local and cloud assets.** + ### Developer Tools -This is where most implementation work happens. You will use it to move from model exploration to agent development and then into validation. As your project grows, this section becomes a practical day-to-day control center. +This is where most implementation work happens. You will use it to move from model exploration to agent development and then into validation. + +As your project grows, this becomes your day-to-day control center. + +Think of this as your execution lane. Most of your chapter-to-chapter work starts here, so getting comfortable with it early pays off quickly. For example, a common loop is: open Model Catalog, test a prompt in Playground, then inspect behavior in Agent Inspector without leaving the same extension area. @@ -88,81 +151,53 @@ For example, a common loop is: open Model Catalog, test a prompt in Playground, After building and monitoring, you still need support and feedback channels to keep improving. +![Foundry Toolkit developer tools](../images/foundry-toolkit-developer-tools.png) + +**Fig 04: Foundry Toolkit Developer Tools section showing Discover, Build, and Monitor areas.** + ### Feedback -This section helps you close the loop when something is unclear or when you want to improve the product experience. Teams benefit from this because documentation, support, and feedback are easy to find in context. +This section helps you close the loop when something is unclear or when you want to improve the product experience. It keeps docs, support, and feedback easy to find in context. + +It is easy to ignore this section when everything works. Keep it in your routine anyway, because it shortens troubleshooting time and improves team handoffs. - **Documentation access**: Official guides for features and workflows. - **Support channels**: Paths to troubleshooting and issue resolution. - **Feedback routes**: Ways to share product feedback and improvement requests. -Let us run through the initial setup steps. - -## Getting Started in Visual Studio Code - -In this section, we will complete first-run setup and confirm the extension is ready for use. A clean first run saves time before model and agent work begins. - -Here is a quick example outcome to aim for: you can open Foundry Toolkit from the Visual Studio Code activity area and see Resources plus Developer Tools without any missing setup prompts. -If you prefer menu navigation, the same install path starts at View > Extensions. - -1. Open the Extensions panel in Visual Studio Code. -2. Search for Foundry Toolkit. -3. Install the extension. -4. Open the Foundry Toolkit view from the activity bar. -5. Confirm the key sections are visible. - -Expected result: the extension view loads with My Resources, Developer Tools, and Feedback visible, and no unresolved sign-in/install warnings. At this point, you can explore local capabilities immediately, or continue into cloud-connected setup for Foundry projects. -If those three sections are visible, your chapter-1 setup target is met. - -Next, we will use Copilot to speed up guided onboarding. - -## Using Copilot for Guided Setup - -GitHub Copilot can guide the setup workflow by asking focused follow-up questions and invoking the right actions in sequence. This reduces manual navigation, especially for first-time setup in a new subscription or resource group. - -For example, if you say you already have an Azure subscription but no Foundry project yet, Copilot can route directly into project creation steps and prompt for only the missing details. - -For a new cloud setup, the guided path usually looks like this: - -- **Authentication**: Sign in to Azure. -- **Subscription selection**: Choose the subscription to host the project. -- **Resource group choice**: Pick an existing group or create a new one. -- **Region selection**: Select the deployment region. -- **Project creation**: Name and create the Foundry project. +Let's run through the initial setup steps together. -After deployment completes, your project appears under My Resources so you can inspect and manage assets in one place. +### Try This Now (60 Seconds): Prove Your Setup Is Real -Expected result: under your Foundry resources, you should see the new project entry and be able to expand it to inspect available assets. +Before you move on, give yourself a fast win. This tiny check removes the "I think it is installed" uncertainty that slows people down later. You are looking for visible proof, not assumptions. -After the project is connected, here is what you can manage right away. +1. Open Foundry Toolkit and click into My Resources. +2. Expand one available section, even if it is currently sparse. +3. Say out loud what you can see now that you could not see five minutes ago. -## What You Can Manage After Project Creation +If you can point to those sections confidently, you are out of setup limbo. You are in active workspace mode now. -Once your Foundry project is connected, Visual Studio Code becomes your operational surface for core project resources. You can validate availability, inspect configuration, and move into build workflows without leaving the editor. +## Quick Question -As a concrete example, a team member can confirm deployed models and then open prompt agents in the same session to start building campaign assistants. +If your team can only improve one thing this week, where will you get the biggest immediate benefit: model discovery speed, prompt iteration speed, or deployment consistency? -- **Model deployments**: View deployed models and endpoint details. -- **Prompt agents**: Create, inspect, and manage prompt-driven agents. -- **Workflows**: Manage declarative workflows that orchestrate agents and business logic. -- **Hosted resources**: Work with hosted tools, stores, and related runtime assets. -- **Legacy compatibility**: Access classic Foundry resources where needed. +## Answer -At this point, you have enough visibility to move into deeper hands-on chapters. +For most teams early in the lifecycle, prompt iteration speed gives the fastest visible return because it affects daily output quality almost immediately. If your team is already producing stable prompts, deployment consistency often becomes the next bottleneck to tackle. The key is to pick the slowest repeated step in your current flow and optimize that first. ## What's Next -You now have the essential foundation for working effectively in Foundry Toolkit inside Visual Studio Code. The next step is to move from setup into active experimentation, where model comparison and prompt iteration shape your first real agent behavior. From there, you can expand into agent creation, evaluation, and deployment with a much smoother learning curve. +You now have the foundation for working effectively in Foundry Toolkit inside Visual Studio Code. Next, you'll move from setup into active experimentation, where model comparison and prompt iteration shape your first real agent behavior. From there, you can grow into agent creation, evaluation, and deployment with a much smoother learning curve. -In the next chapter, we will go deeper into model catalog and playground workflows so you can compare model behavior with practical, scenario-based prompts. +In the next chapter, we'll go deeper into model catalog and playground workflows so you can compare model behavior with practical, scenario-based prompts. That is where the really fun trade-offs begin: quality, speed, and cost. ## Learn more If you want to continue learning after this chapter, the best next step is to follow the workflow in the same order you will use in real projects. Start with setup and model exploration, then move into agent building and hosted deployment. The references below are organized to support that progression. -- **Foundry Toolkit quick start**: Explore first-run guidance and onboarding patterns in the toolkit experience. -- **Foundry Toolkit quick start**: [Watch the chapter walkthrough video](https://youtu.be/aQFSDGAk9DA) for first-run setup and onboarding flow. +- **Visual Studio Code AI app overview**: [Review the Intelligent Apps overview in Visual Studio Code docs](https://code.visualstudio.com/docs/intelligentapps/overview) for product-level context and capabilities. +- **Foundry Toolkit quick start**: [Review the Azure AI Foundry overview and onboarding guidance](https://learn.microsoft.com/azure/ai-foundry/) for first-run setup context. - **Model catalog and playground**: [Explore the Model Catalog overview](https://learn.microsoft.com/azure/ai-foundry/how-to/model-catalog-overview) to compare and select models. - **Agent Builder workflows**: [Follow the Azure AI Agents quickstart](https://learn.microsoft.com/azure/ai-services/agents/quickstart) to build and test agent workflows. - **Hosted agent lifecycle**: [Review Azure AI Agents concepts and lifecycle guidance](https://learn.microsoft.com/azure/ai-services/agents/overview) for deployment and operations context. diff --git a/learn/foundry-toolkit-extension/2-exploring-models.md b/learn/foundry-toolkit-extension/2-exploring-models.md index 32c50cdfc48..035d04b3bd5 100644 --- a/learn/foundry-toolkit-extension/2-exploring-models.md +++ b/learn/foundry-toolkit-extension/2-exploring-models.md @@ -16,11 +16,44 @@ Keywords: -When building AI applications, one of the biggest challenges is not implementation, it is model choice. You can have great prompts and solid workflow design, but if the model is mismatched to your scenario, quality and speed will both suffer. In this chapter, we will use Foundry Toolkit in Visual Studio Code to walk a practical selection path from recommendation to side-by-side validation. +When building AI applications, one of the hardest parts is not implementation, it is picking the right model. You can have strong prompts and a clean workflow, but if the model is mismatched, quality and speed both take a hit. + +In this chapter, we will use Foundry Toolkit in Visual Studio Code to walk a practical selection path from recommendations to side-by-side validation. + +Think of it as model selection with receipts. + +Each step is useful on its own. +The real magic happens when the full loop runs end to end. + +## What You Will Learn + +This chapter is about building a repeatable model-selection process, not making one-off guesses. We will combine GitHub Copilot recommendations, Model Catalog filtering, model-card review, deployment, and Playground comparison into one loop you can reuse. + +In this chapter, you will learn how to: + +- **Generate a shortlist**: Use GitHub Copilot to produce an initial set of realistic candidates. +- **Refine the catalog**: Use filters to reduce model options to a relevant subset. +- **Validate capabilities**: Check model cards before deployment. +- **Deploy selected models**: Push selected candidates into your Foundry project. +- **Compare behavior**: Evaluate outputs side by side in Playground. + +Before we run the workflow, let's be clear about why this structure matters. + +## Problem Framing: Model Selection Is a Risk-Reduction Process + +It helps to treat model selection as risk reduction, not preference testing. You are not trying to find a universally "best" model. You are trying to find the most reliable fit for your workload, constraints, and region. + +That framing changes how you evaluate results, because consistency and deployability matter just as much as output style. + +Pretty output is nice. Deployable output wins. + +A simple way to apply this is to score each candidate against four practical checks: capability fit, regional availability, cost profile, and behavior quality under the same prompts. When a model wins across those checks, your choice is easier to defend to both engineering and product stakeholders. ## Prerequisites -Before we start comparing anything, let us ensure the environment is ready. This chapter depends on both local tooling and cloud availability, so checking setup first prevents noisy failures later. If these prerequisites are in place, every step in the chapter will map cleanly to what you see in the UI. +Before we compare anything, let's make sure the environment is ready. This chapter depends on local tooling and cloud availability, so a quick setup check now saves annoying failures later. + +If these prerequisites are in place, every step in this chapter should map cleanly to what you see in the UI. - **Visual Studio Code**: Installed and updated so extension workflows and command surfaces are available. - **Foundry Toolkit extension**: Installed and visible in the activity bar. @@ -28,82 +61,92 @@ Before we start comparing anything, let us ensure the environment is ready. This - **Azure subscription and region**: Selected for deployment checks and quota-aware filtering. - **Connected Foundry project**: Available in Foundry Toolkit under your resources. -With setup clarified, let us define exactly what this chapter teaches and how it connects to your day-to-day model work. +With setup confirmed, let's define exactly what this chapter teaches and how it maps to day-to-day model work. -## What You Will Learn - -This chapter is about building a repeatable model selection process, not making one-off guesses. We will combine GitHub Copilot recommendations, Model Catalog filtering, model-card review, deployment, and Playground comparison into one loop you can reuse for future scenarios. By the end, you should be able to justify why a model was chosen, not just that it "felt better." - -- **Shortlist generation**: Use GitHub Copilot to produce an initial set of realistic candidates. -- **Catalog refinement**: Use filters to reduce model options to a relevant subset. -- **Capability validation**: Check model cards before deployment. -- **Deployment readiness**: Push selected candidates into your Foundry project. -- **Behavior comparison**: Evaluate outputs side by side in Playground. - -Before we run the workflow, let us be explicit about why this structure matters. +You are about to replace guesswork with a repeatable loop. ## Why Model Selection Matters -Model selection can become overwhelming very quickly when you have multiple providers, families, sizes, and capability flags. A structured process keeps decisions grounded in evidence and prevents teams from optimizing on preference alone. It also creates traceability, which is important when results need to be explained to stakeholders. +Model selection can get overwhelming fast when you have multiple providers, model families, sizes, and capability flags. A structured process keeps decisions grounded in evidence and prevents teams from optimizing on preference alone. + +It also creates traceability, which matters when you need to explain results to stakeholders. For example, if your scenario requires image input and deployment in Sweden Central, a model that is excellent in general but unavailable in that region is not a practical choice. This is exactly where a disciplined filter-and-validate workflow saves time. -In practice, this chapter workflow gives you: +In practice, this workflow gives you: - **Faster narrowing**: Reduce large candidate sets before deep testing. - **Higher confidence**: Validate capabilities and availability before committing. - **Cleaner trade-off analysis**: Compare speed, style, and quality with identical prompts. - **Better production fit**: Select models that align with quota, region, and deployment constraints. -At this point, we can begin with GitHub Copilot recommendations. +Let's talk about how to run this workflow in practice. ## Step 1: Start with GitHub Copilot Recommendations -Before browsing Model Catalog manually, ask GitHub Copilot for candidate models tied to your specific scenario. This is useful because GitHub Copilot can combine capability requirements with subscription and regional constraints when shaping recommendations. +It's a good idea to start with GitHub Copilot recommendations before you dive into the catalog. This is because Copilot can combine capability requirements with subscription and regional constraints while shaping recommendations. + +For this step, let's ask for a shortlist of models that meet three practical criteria: + +- **Toolkit support**: Whether models are accessible through your current Foundry flow. +- **Regional deployability**: Whether your target region supports the model. +- **Capability fit**: Whether image processing or other required features are present. + +Therefore, a suitable prompt to Copilot is one that combines these three constraints into a single request like the below: + +```text +Recommend two models for a marketing scenario that require image input support and are deployable in my subscription and region. +``` + +Next, let's use this prompt: 1. Open GitHub Copilot Chat in Visual Studio Code. 2. Paste your recommendation prompt. 3. Run the prompt in chat rather than in the terminal. -A practical prompt from the walkthrough looks like this in spirit: recommend two models for a marketing scenario, with image input support, available in Foundry Toolkit, and deployable in my subscription and region. + Here's an example prompt you can use: -When you run this, GitHub Copilot can evaluate: + ```text + Recommend two models for a marketing scenario that require image input support and are deployable in my subscription and region. + ``` -- **Toolkit support**: Whether models are accessible through your current Foundry flow. -- **Regional deployability**: Whether your target region supports the model. -- **Capability fit**: Whether image processing or other required features are present. + ![Example prompt asking Copilot for recommendations](../images/ch2-prompt-recommendation.png) + + **Fig 1: Example prompt asking GitHub Copilot for model recommendations.** + +4. Review the response and note the recommended models. + + ![Example result from Copilot recommendations](../images/ch2-example-result.png) + + **Fig 2: Example result from GitHub Copilot recommendations.** -Result: you receive a shortlist, a few viable alternative pairs, and guidance on what to test next. +That is a much better starting line than scrolling hundreds of models cold. -From there, move into catalog-level refinement. +Now that we have a starting point, let's move into the catalog to see how to filter and validate candidates. ## Step 2: Explore the Model Catalog -Model Catalog is your central discovery surface for model exploration in Foundry Toolkit. It is where recommendation output turns into actionable filtering and inspection. The key value here is that models from multiple sources are visible through one interface. +Model Catalog is your central discovery surface in Foundry Toolkit. You can use it to compare models from multiple providers, check capabilities, and validate deployment constraints before you commit to a candidate. + +Next, let's open the catalog and see how we can reduce the candidate set to a manageable number for deeper inspection. 1. Open Foundry Toolkit. 2. Go to Developer Tools. 3. Select Model Catalog before reviewing any specific model. -In the walkthrough, the ecosystem includes hosted and local options so you are not locked into a single provider strategy. +Now you should see a list of models that includes multiple providers and hosting paths, something like the below image: -- **Microsoft Foundry hosted models**: Cloud-managed options integrated with project workflows. -- **Provider models**: Options from OpenAI, Anthropic, Google, and others. -- **GitHub-hosted models**: Additional candidates for comparison flows. -- **Local models**: ONNX and Ollama-backed runs on your machine. -- **Custom integrations**: Bring-your-own-model extensions where needed. +![Model Catalog in Foundry Toolkit](../images/ch2-model-catalog.png) -Once the catalog is open, reduce noise with focused filters. +**Fig 3: Model Catalog in Foundry Toolkit.** -## Step 3: Use Filters to Narrow Candidates +In the next step, we will apply filters to narrow this list to a manageable set of candidates. -Filtering is where broad discovery turns into targeted comparison. Instead of scanning dozens of irrelevant options, you define constraints that match your scenario and deployment path. This is especially useful when business requirements include capability-specific needs such as vision input. +## Step 3: Use Filters to Narrow Candidates -1. Open the filter panel in Model Catalog. -2. Set hosting source, publisher, and image support. -3. Click into individual models only after filters are applied. +Filtering helps us narrow down the candidate list to a manageable set of models that meet our requirements. This is especially useful when requirements include capability-specific needs such as vision input. -In the video flow, filters are applied for hosting target, publisher, and image support before selecting exact models by name. +Here's all the filtering criteria you could apply to reduce candidates to a manageable set: - **Hosting source**: Limit to the hosting path you actually plan to deploy. - **Publisher**: Compare models within a provider or across providers intentionally. @@ -111,17 +154,29 @@ In the video flow, filters are applied for hosting target, publisher, and image - **Runtime type**: Include local CPU, GPU, or NPU options when relevant. - **Fine-tuning support**: Keep only models that match adaptation requirements. -What you should see next: your candidate list drops to a manageable set you can inspect in minutes instead of scanning dozens of entries. +Next, let's go from "interesting list" to "actual candidates." -At that point, the next step is model-card validation. +1. Open the filter panel in Model Catalog. +2. Set the filter like so: + + Hosted BY: **Foundry** + Publisher: **OpenAI** + + You should see a reduced candidate list similar to below. + + ![Model filter panel in Foundry Toolkit](../images/ch2-model-filter.png) + + **Fig 4: Model filter panel in Foundry Toolkit. Here we select Hosted By: Foundry, Publisher: OpenAI** + + Your candidate list drops to a manageable set you can inspect in minutes instead of scanning dozens of entries. + +At that point, the next step is to review the model cards for each candidate to confirm capabilities, pricing, and constraints before deployment. ## Step 4: Review the Model Card -Before deployment, open each model card and verify what the provider actually guarantees. This prevents hidden mismatch later, especially for pricing, input constraints, or capability assumptions. Think of this as your pre-deployment contract check. +Before deployment, open each model card and verify what the provider actually guarantees. This prevents hidden mismatch later, especially around pricing, input constraints, and capability assumptions. -1. Select one filtered model. -2. Open its model card page. -3. Check capabilities and pricing before moving to deployment. +Think of this as your pre-deployment check. In practice, model-card review should answer: can this model do what we need, at acceptable cost, with the expected behavior profile? @@ -130,39 +185,58 @@ In practice, model-card review should answer: can this model do what we need, at - **Pricing**: Understand expected token-cost behavior. - **Technical specs**: Review limits, context details, and operational constraints. -After validation is complete, deploy shortlisted candidates. +To review a model card: + +1. Select one filtered model. +2. Open its model card page. +3. Check capabilities and pricing before moving to deployment. + +![Model card review details](../images/ch2-model-card.png) + +After you're satisfied with the model card review, you are ready to deploy the candidates into your Foundry project for side-by-side comparison. ## Step 5: Deploy Shortlisted Models -Deployment moves model comparison from theory to hands-on testing. In the walkthrough, two OpenAI candidates are deployed into the same Foundry project so they can be evaluated under identical prompt conditions. +Deployment moves model comparison from theory to hands-on testing. In this step, two OpenAI candidates are deployed into the same Foundry project so they can be evaluated under identical prompts. + +Great, let's kick off a deployment. 1. Choose Deploy from the model card. 2. Select your connected Foundry project as the deployment target. -During deployment, configure only what you need for controlled comparison and keep naming clear so you can track outputs cleanly in Playground. +![Deployment in Foundry Playground](../images/ch2-deploy.png) -- **Deployment name**: Use a name that clearly identifies the model variant. -- **Token throughput settings**: Adjust tokens-per-minute for practical test runs. -- **Project target**: Confirm deployment goes to the intended Foundry project. +This should kick off a deployment process that takes a few minutes. Once complete, you will see the deployed model in your Foundry project. -Result: both candidates appear in project resources and are ready for Playground testing. - -When both deployments are ready, run the actual head-to-head comparison. +For our next step, we will compare the two deployed models side by side in Playground to evaluate their behavior under identical prompts. ## Step 6: Compare Models in Playground -This section is where model selection becomes evidence-based. Open compare view in Playground and run the same prompt against both models so differences are attributable to model behavior, not prompt drift. +An important step in model selection is to compare outputs under identical prompts. This ensures that differences in output are due to model behavior, not prompt drift. -1. Open Playground. -2. Enable Compare mode. -3. Assign one deployed model to each response pane. +This comparison uses two prompt types to surface different strengths: a marketing-text prompt and a vision extraction prompt. + +Here are the two prompts we will use for comparison: + +**Text prompt**: + +```text +Generate a short LinkedIn post for developer productivity with AI tools. +``` -The walkthrough uses two prompt types to surface different strengths: a marketing-text prompt and a vision extraction prompt. +**Vision prompt**: -In the UI, compare mode is active when you can see two model-labeled response panes side by side under the same prompt input area. +```text +Extract text from an attached image. +``` -- **Text prompt**: Generate a short LinkedIn post for developer productivity with AI tools. -- **Vision prompt**: Extract text from an attached image. +Next, we will use Playground's Compare mode to evaluate the two deployed models side by side. + +To do this comparison, follow the steps below: + +1. Open Playground. +2. Enable Compare mode. +3. Assign one deployed model to each response pane. When you inspect outputs, evaluate a consistent set of dimensions: @@ -171,17 +245,13 @@ When you inspect outputs, evaluate a consistent set of dimensions: - **Verbosity**: Is the response concise or overly expansive for the task? - **Scenario fit**: Which output is closer to what the business actually needs? -Validation target: you can justify model selection based on observed behavior, not preference. - After choosing a candidate, one important step remains: prompt and parameter refinement. ## Step 7: Refine Behavior with Prompt and Parameters -Model choice is only part of quality. You still need to shape output behavior with system instructions and generation controls. This step lets you align responses with voice, audience, and channel constraints before moving deeper into agent workflows. +Model choice is only part of quality. You still need to shape output behavior with system instructions and generation controls. -1. Add a system prompt in Playground. -2. Tune one generation setting at a time. -3. Evaluate each change before adjusting the next setting. +This step aligns responses with voice, audience, and channel constraints before you move deeper into agent workflows. A typical refinement pass adds a system prompt and tunes generation controls in small increments, then re-tests with the same scenario prompts. @@ -190,26 +260,33 @@ A typical refinement pass adds a system prompt and tunes generation controls in - **Temperature**: Tune creativity versus determinism. - **Top-p**: Adjust token sampling behavior. -Validation target: selected model outputs become more consistent with your intended style and business constraints. +Here's a simple refinement loop you can use to tune behavior: -Let us recap why this process works. +1. Add a system prompt in Playground. +2. Tune one generation setting at a time. +3. Evaluate each change before adjusting the next setting. -## Why This Workflow Works +## Quick Question -The strength of this chapter flow is sequence discipline: shortlist, refine, validate, deploy, compare, and tune. Each stage removes uncertainty before the next stage adds effort. That keeps the process efficient and easier to explain when teams ask why one model was selected over another. +If two models produce similarly good text but one is unavailable in your target region, which one is the better production choice and why? -Instead of relying on intuition, you now have a repeatable selection loop grounded in capability checks, regional constraints, and real prompt outcomes. +## Answer + +The better production choice is the model that can be deployed in your target region with acceptable behavior and cost. A slightly better output that cannot be deployed where you need it creates delivery risk you cannot hide later. Production fit always includes availability, not just raw output quality. ## What's Next -You are now ready to move from model selection into agent development. In the next chapter, we will use this model-evaluation foundation to build agents that can ask better questions, use tools effectively, and produce outputs that are easier to evaluate and ship. +You are now ready to move from model selection into agent development. In the next chapter, we will use this model-evaluation foundation to build agents that ask better questions, use tools effectively, and produce outputs that are easier to evaluate and ship. + +You now have signal, not vibes, driving the model decision. ## Learn more -If you want to reinforce this chapter, the best next step is to review the same workflow from three angles: walkthrough, product guidance, and deployment details. This combination helps you move from understanding concepts to applying them in real projects. +If you want to reinforce this chapter, the best next step is to review the same workflow from three angles: this written guide, product guidance, and deployment details. This combination helps you move from understanding concepts to applying them in real projects. Use the links below in order, and you will see the same recommendation-to-comparison flow from both tutorial and reference perspectives. -- **Chapter video walkthrough**: [Watch the full video for this chapter](https://youtu.be/92tKoJOTays). +- **GitHub Copilot in Visual Studio Code**: [Review Copilot capabilities and workflows in Visual Studio Code docs](https://code.visualstudio.com/docs/copilot/overview). +- **Optional companion video**: [Watch the full video for this chapter](https://youtu.be/92tKoJOTays). - **Model Catalog overview**: [Review the official Model Catalog documentation](https://learn.microsoft.com/azure/ai-foundry/how-to/model-catalog-overview). - **Foundry SDK development guide**: [Explore SDK-based development guidance for Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/develop/sdk-overview). - **Model deployment reference**: [See how to deploy OpenAI models in Azure AI Foundry](https://learn.microsoft.com/azure/ai-foundry/how-to/deploy-models-openai). diff --git a/learn/foundry-toolkit-extension/3-building-social-media-agent.md b/learn/foundry-toolkit-extension/3-building-social-media-agent.md index 216c00990f5..b8b3ef61442 100644 --- a/learn/foundry-toolkit-extension/3-building-social-media-agent.md +++ b/learn/foundry-toolkit-extension/3-building-social-media-agent.md @@ -14,13 +14,31 @@ Keywords: # Building a Social Media Content Agent with Agent Builder + +This chapter walks through building a practical social media content agent using Agent Builder in Foundry Toolkit. The goal is not just to generate text, but to create an assistant that asks the right follow-up questions, uses trusted context, and returns output a team can actually review and ship. -This chapter walks through building a practical social media content agent using Agent Builder in Foundry Toolkit. The goal is not just to generate text, but to create an assistant that asks the right follow-up questions, uses trusted context, and returns output that a team can actually review and ship. By the end, you will have a repeatable workflow for moving from idea to tested prompt-agent behavior in Visual Studio Code. +By the end, you will have a repeatable workflow for moving from idea to tested prompt-agent behavior in Visual Studio Code. + +## Problem Framing: Grounded Agents Are Decision Systems + +A useful perspective is to treat this agent as a decision system, not just a text generator. Output quality depends on three linked decisions: + +- **When to ask clarifying questions**: For example, if the prompt is missing audience or tone, the agent should ask before drafting copy. +- **When to call tools**: If the prompt references Microsoft technologies, the agent should retrieve official documentation before drafting copy. +- **How to shape final content for review**: The agent should format drafts according to team style guides and include references to supporting materials. + +When those decisions are explicit, your team gets more predictable and trustworthy behavior. + +That is the difference between "sounds smart" and "safe to publish." + +You can see this in practice when the same prompt is run with and without grounding. The grounded version usually gives fewer vague claims and better traceability, which is exactly what content teams need when publishing technical messages. ## Prerequisites -Before we start building, let us confirm your setup is ready. This chapter combines agent authoring, tool grounding, and evaluation, so a missing prerequisite can break the flow halfway through. If everything below is already in place, you should be able to run the full chapter without detours. +Before we start building, let's confirm your setup is ready. This chapter combines agent authoring, tool grounding, and evaluation, so a missing prerequisite can break the flow halfway through. + +If everything below is already in place, you should be able to run the full chapter without detours. - **Visual Studio Code setup**: Visual Studio Code with Foundry Toolkit installed. - **Project access**: A Microsoft Foundry project connected in Foundry Toolkit. @@ -30,84 +48,101 @@ Before we start building, let us confirm your setup is ready. This chapter combi With setup confirmed, we can define exactly what we are building and why the design choices matter. -## What You Will Build +Now we move from setup mode into build mode. -The target outcome is a social content assistant for developer-focused marketing workflows. It will transform rough campaign inputs into structured draft content, while asking clarifying questions when required details are missing. Think of this as an early production prototype, not a one-off demo. +## What You Will Learn -For example, if the team provides a feature note plus a screenshot but no clear channel objective, the agent should ask what audience and tone are expected before finalizing copy. +The target outcome is a social content assistant for developer-focused marketing workflows. It transforms rough campaign inputs into structured draft content, while asking clarifying questions when required details are missing. -- **Content generation**: Draft LinkedIn copy, short captions, and campaign angles. -- **Input handling**: Work from brief text, feature notes, screenshots, and goals. -- **Quality guardrails**: Follow tone and structure constraints from system instructions. -- **Review readiness**: Return outputs in a format that marketers and developer advocates can validate quickly. +You will learn how to: -Before touching configuration screens, let us make explicit why this low-code pattern is valuable. +- **Generate content drafts**: Produce LinkedIn copy, short captions, and campaign angles. +- **Handle varied inputs**: Work from brief text, feature notes, screenshots, and goals. +- **Apply quality guardrails**: Follow tone and structure constraints from system instructions. +- **Return review-ready output**: Format responses so marketers and developer advocates can validate quickly. -## Why This Agent Pattern Matters +Before touching configuration screens, let's make explicit why this low-code pattern is valuable. -Teams usually need to validate role, tone, and workflow before investing in full coded implementation. Agent Builder gives you a fast validation layer where behavior can be tested in context and improved quickly. That is especially useful when requirements are still moving. +## Step 1: Create the Agent in Agent Builder -In short, this pattern lets you answer, "Are we building the right assistant?" before asking, "How do we harden it in code?" +Start in Foundry Toolkit under Developer Tools and open the build path for creating an agent. In this chapter, we intentionally use the low-code path first because it lets us test behavior quickly before coding anything custom. -- **Faster validation**: Confirm behavior without writing full application code. -- **Grounded responses**: Connect to approved sources through MCP tools. -- **Operational quality**: Use evaluation metrics early instead of relying on intuition. -- **Reusable workflow**: Move from prototype to repeatable team process. +> TIP: For consistency in your implementation, use a role-specific name and pick a model already deployed in your project. -Next, we will walk the build sequence step by step. +Follow these steps to create the agent: -## Step 1: Create the Agent in Agent Builder +1. Navigate to Developer Tools -> Build -> Create an agent -> Open Agent Builder. +2. Assign a clear role-focused name such as **Dev Social Content Assistant**. +3. Select a model suitable for concise writing, instruction following, and multi-modal input. -Start in Foundry Toolkit under Developer Tools and open the build path for creating an agent. For this walkthrough, we intentionally use the low-code path first, because it lets us test behavior quickly before coding anything custom. Keep this first version simple and focused on role clarity. +Here's what you should see once you kick off a create-agent flow in Agent Builder. -For consistency with the walkthrough, use a role-specific name and pick a model already deployed in your project. +![Placeholder image: Agent creation in Agent Builder](../images/ch3-create-agent.png) -- **Navigation path**: Developer Tools -> Build -> Create an agent -> Open Agent Builder. -- **Agent identity**: Use a clear role-focused name such as Dev Social Content Assistant. -- **Model selection**: Choose a model suitable for concise writing, instruction following, and multimodal input. +**Fig 01: Create a new agent in Agent Builder.** -Once the shell is in place, the next quality lever is instruction design. +Next, we need to set up instructions that define the agent's role, audience, and output expectations. ## Step 2: Define Strong Instructions -A strong system prompt defines role, audience, boundaries, and output shape in concrete terms. This matters because vague instructions usually produce vague marketing copy and inconsistent follow-up behavior. Here, we optimize for a credible developer-first voice and reviewable output structure. +A strong system prompt defines role, audience, boundaries, and output shape in concrete terms. This matters because vague instructions usually produce vague copy and inconsistent follow-up behavior. -As a practical example, ask the agent to separate final copy from rationale so reviewers can quickly distinguish deliverable output from internal reasoning. +Here's what to consider when crafting instructions for a social content agent: - **Role clarity**: Support a social media team producing developer-facing content. - **Behavior rules**: Ask follow-up questions when required details are missing. - **Tone constraints**: Avoid exaggerated claims and include clear technical value. - **Output structure**: Separate final copy from rationale and assumptions. +Below is an example of a system prompt that captures these requirements. You can adapt it to your own style and team needs. + +![System prompt configuration](../images/ch3-system-prompt.png) + +**Fig 02: Define system prompt instructions for the social content agent.** + After instructions look solid, save the agent so it becomes a reusable project asset. ## Step 3: Save and Register the Prompt Agent -After defining instructions, save the agent to your Foundry project so it appears in project resources. This turns a temporary editing session into a trackable artifact the team can revisit. It also gives you a clean base version before adding tools. +After defining instructions, save the agent to your Foundry project so it appears in project resources. This turns a temporary editing session into a trackable artifact the team can revisit. + +It also gives you a clean base version before adding tools. + +Select the Save button, it should given you two options: Save to Foundry or Save to local file. Choose **Save to Foundry**. -Checkpoint: you should be able to open your project resources and find the agent under Prompt Agents. +![Save to Microsoft Foundry](../images/ch3-save.png) -- **Persistence**: Save the configured prompt agent to Microsoft Foundry. -- **Resource location**: Confirm it appears under Prompt Agents in project resources. +**Fig 03: Save the agent to project resources for reuse and versioning.** -Now we can improve factual reliability by connecting the agent to trusted sources. +Once we've saved the agent, we can add tools to connect it to authoritative Microsoft documentation. ## Step 4: Add MCP Tools for Grounded Context -A reliable content agent should not rely only on base-model memory. In this workflow, MCP connects the agent to authoritative Microsoft documentation through the Microsoft Learn MCP server. This is the shift from plausible output to grounded output. +A reliable content agent should not rely only on base-model memory. In this workflow, MCP connects the agent to authoritative Microsoft documentation through the Microsoft Learn MCP server. For this scenario, grounding matters whenever campaign text references product capabilities, release details, or platform behavior. -- **Tool catalog action**: Add a Foundry tool and select Microsoft Learn MCP. -- **Grounding strategy**: Use docs search to locate official sources first. -- **Content retrieval**: Use fetch tools to retrieve full documentation context. -- **Reliability rule**: Instruct the agent to avoid guessing or fabricating Microsoft facts. +1. In the Tool section, click "+" and select MCP Server + + ![Add MCP Server](../images/ch3-mcp-server.png) + + **Fig 04: Select MCP Server in Tools** -Adding tools alone is not enough, so the next step is to teach the agent when to use them. + Next, we will need to select which MCP Server. + +2. Select the Microsoft Learn MCP server from the list of available servers. + + ![MCP tool setup](../images/ch3-mcp.png) + + **Fig 05: Add MCP server tools to the agent for grounded responses.** + +Adding tools alone is not enough, so the next step is teaching the agent when to use them. ## Step 5: Add Tool-Use Guidance to Instructions -Adding tools is only half the job. You also need instruction-level guidance that tells the agent when tool calls are required and how to sequence them. Without this, the agent may skip retrieval or call tools inconsistently. +Adding tools is only half the job. You also need instruction-level guidance that tells the agent when tool calls are required and how to sequence them. + +Without this, the agent may skip retrieval or call tools inconsistently. In practice, you want explicit trigger logic such as: if the prompt asks about Microsoft technologies, retrieve official docs before drafting output. @@ -116,69 +151,103 @@ In practice, you want explicit trigger logic such as: if the prompt asks about M - **Tool selection**: Route to the appropriate Microsoft Learn MCP tools. - **Grounded output**: Base responses on validated sources rather than prior assumptions. +Here's an example of how to phrase this in the system prompt so the agent knows when to call tools and how to use retrieved context. You're asking the agent to think in steps, analyze intent, and then decide what tool to call and possible additional tool calls. Finally, add guidance to constrain what the agent can and can't do with the retrieved context. + +![Tool instructions](../images/ch3-tool-guidance.png) + +**Fig 05: Add tool-use guidance to the agent instructions.** + At this stage, run realistic tests in the playground. +This is where the agent shows you what it can really do. + ## Step 6: Test in the Agent Playground -With instructions and tools configured, run realistic prompts directly in Agent Builder playground. Use prompts that reflect the actual campaign requests your team receives, not synthetic one-liners. Behavior quality becomes visible quickly in this step. +With instructions and tools configured, run realistic prompts directly in Agent Builder playground. Use prompts that reflect actual campaign requests your team receives, not synthetic one-liners. + +Behavior quality becomes visible quickly in this step. For example, ask for a LinkedIn post about the GitHub Copilot app for a developer audience and check whether the assistant both retrieves trusted context and asks useful follow-up questions. +Here's what to look for when testing: + - **Tool verification**: Confirm docs search is invoked against Microsoft Learn. - **Response quality**: Check draft usefulness, structure, and call-to-action placement. - **Follow-up behavior**: Ensure the agent asks clarifying questions when needed. - **Transparency**: Validate that rationale is shown when requested. +See below image that shows a typed prompt, which tools are invoked and the final output from the agent. + +![Testing in Playground](../images/ch3-testing.png) + +**Fig 05: Test the agent in the playground with realistic prompts.** + Manual testing is useful, but the next step is where quality becomes measurable. ## Step 7: Scale Validation with Evaluations -Manual playground testing is useful, but it does not scale well for repeatable quality control. This step introduces built-in evaluation workflows so you can score behavior against clear metrics over multiple test rows. It is the difference between impression-based review and evidence-based review. +Evaluations are a repeatable way to measure behavior quality across multiple test rows. They let you score the agent against clear metrics and identify where improvements are needed. + +Manual playground testing is useful, but it does not scale well for repeatable quality control. This step introduces built-in evaluation workflows so you can score behavior against clear metrics over multiple test rows. + +There are two major concepts we need to understand before moving further: -If you do not yet have production traces, generate a synthetic dataset first and iterate from there. +- **Evaluation**: A structured process that scores agent behavior against a dataset of test rows. Each row has an input prompt and expected output, and the evaluation compares actual responses to expected ones. +- **Evaluator**: A scoring mechanism that applies metrics to judge the quality of agent responses. Examples of evaluator metrics include task adherence, fluency, relevance, and groundedness. -- **Evaluation setup**: Open Evaluations and select the target agent. -- **Scoring rubric**: Use metrics such as task adherence, fluency, relevance, and groundedness. -- **Dataset path**: Upload an existing JSONL dataset or generate a synthetic dataset. -- **Judge model**: Use an LLM judge to compare actual responses against expected candidates. +Foundry Toolkit has great built-in support for evaluations, so let's walk through the steps to set one up. -UI cue: when the run is done, the evaluation status changes to Completed and the report-opening action becomes available. +When you create an Agent, there's also an evaluation area that helps you set up evaluations. The idea is to create a dataset of test prompts and expected outputs, then run the evaluation to see how well the agent performs. -Once the run completes, the real value comes from diagnosis and iteration. +Let's say you have an Agent like this, then here's how you set up evaluation. -## Step 8: Review Results and Iterate +1. Select evaluation area and select to generate a dataset (top left button) -After the batch evaluation completes, inspect both aggregate scores and row-level details. Aggregate numbers show trend direction, but row-level analysis reveals why behavior failed. Here you find concrete fixes for instruction wording, tool routing, or output formatting. + See "Evaluation" tab" in below image. Select that. -Treat this as an iterative loop: update, re-run, compare, and document what improved. + ![Evaluation area from Agent creation](../images/ch3-evaluation-area.png) -- **Aggregate review**: Evaluate overall performance across each metric. -- **Row diagnostics**: Inspect output, numeric scores, and scoring rationale per test row. -- **Refinement loop**: Update prompt and tool guidance, then run evaluation again. -- **Version discipline**: Re-evaluate every major agent change or feature addition. +2. Select to generate a dataset by clicking the top left button. -We have now completed the full loop, so let us summarize why this process is effective. + You should first be met with a modal that shows you a prompt template for generating a dataset. Confirm the prompt and select to generate a dataset. This will create a JSONL file with test rows that you can use for evaluation. -## Why This Workflow Works + Here's a set of generated prompts it can run against your model. -This chapter demonstrates a complete low-code lifecycle: define role, ground with tools, test behavior, and evaluate systematically. The sequence is intentionally practical and repeatable, so teams can improve quality before broad rollout. It also gives you a shared language for discussing agent quality across product and engineering roles. + ![Generate dataset modal](../images/ch3-dataset.png) -- **Prototype quickly**: Build useful behavior before pro-code investment. -- **Ground responsibly**: Connect to approved sources through MCP. -- **Measure objectively**: Use metrics and datasets to guide improvements. -- **Deploy confidently**: Share a better-tested agent with stakeholders. -The natural next step is deeper engineering and production hardening. +3. Test your Agent by running an evaluation (select Play icon) + + You should see how each prompt is run agains your Agent and you can provide a thumbs up/thumbs down on the result. + + ![Evaluation result](../images/ch3-evaluation-result.png) + + **Fig 06: Configure evaluation settings for the agent.** + +This is a great way to get a quick sense of how your Agent is performing against the generated dataset. You can adjust the Agent's instructions, tools, or other settings and re-run the evaluation to see if performance improves. + +## Quick Question + +If an agent gives polished output but cannot explain where key product facts came from, would you trust it for external publishing? + +## Answer + +In most production teams, the answer is no. Polished wording without traceable grounding creates review risk, especially for technical claims. Reliable publication workflows need both quality language and verifiable source usage. ## What's Next -After validating a prompt-based social content assistant, the next step is deeper agent engineering. You can expand into richer tool orchestration, stronger datasets, and production-focused deployment and monitoring workflows. The next chapter builds on this foundation so behavior quality remains strong as complexity increases. +After validating a prompt-based social content assistant, the next step is deeper agent engineering. You can expand into richer tool orchestration, stronger datasets, and production-focused deployment and monitoring workflows. + +The next chapter builds on this foundation so behavior quality stays strong as complexity increases. + +You are building reliability now, not patching it later. ## Learn more If you want to deepen this chapter after the hands-on flow, use the resources below as a guided extension path. Start with agent fundamentals, then move into implementation and deployment references so each link builds on the previous one. This order mirrors how teams usually mature from prompt-agent prototypes to production-ready agent workflows. +- **Copilot Chat workflows**: [Review Copilot Chat guidance in Visual Studio Code docs](https://code.visualstudio.com/docs/copilot/chat/copilot-chat). - **Azure AI Foundry overview**: [Understand the broader platform and workflow surface](https://learn.microsoft.com/azure/ai-foundry/). - **Azure AI Agents overview**: [Review core agent concepts and lifecycle guidance](https://learn.microsoft.com/azure/ai-services/agents/overview). - **Azure AI Agents quickstart**: [Build and run a practical agent end-to-end](https://learn.microsoft.com/azure/ai-services/agents/quickstart). diff --git a/learn/foundry-toolkit-extension/4-building-hosted-agent.md b/learn/foundry-toolkit-extension/4-building-hosted-agent.md index 1e844ac2cdc..ddf25c1ff6e 100644 --- a/learn/foundry-toolkit-extension/4-building-hosted-agent.md +++ b/learn/foundry-toolkit-extension/4-building-hosted-agent.md @@ -14,39 +14,61 @@ Keywords: # Building a Hosted Agent with GitHub Copilot and Microsoft Foundry - - + -Low-code agents are great for proving behavior quickly, but most teams eventually need stronger control over code, deployment, and integration. In this chapter, we move into a code-first workflow and build a hosted agent that can be developed locally, debugged with tooling, and deployed into Microsoft Foundry. By the end, you will have a practical blueprint for going from prompt idea to production-oriented hosted execution. +https://youtu.be/pxG-9Lh_a44 + +Low-code agents are great for proving behavior quickly, but most teams eventually need stronger control over code, deployment, and integration. In this chapter, we move into a code-first workflow and build a hosted agent that can be developed locally, debugged with tooling, and deployed into Microsoft Foundry. + +By the end, you will have a practical blueprint for going from prompt idea to production-oriented hosted execution. + +This is where agent development starts to feel like real engineering. + +Every part of this flow is useful on its own. +The real magic happens when scaffold, debug, tools, and deploy all connect into one repeatable system. + +## Problem Framing: Code-First Agents Improve Operational Reliability + +The biggest shift in this chapter is not just writing code instead of prompts, it is moving to an operationally reliable lifecycle. In low-code mode, behavior can be validated quickly, but deployment shape, tooling integration, and debugging depth are often constrained. + +In code-first mode, you gain repeatability: the same repo defines runtime behavior, tool wiring, and deployment flow. + +One repo. One source of truth. Fewer surprises. + +An easy way to see the value is to compare how issues are diagnosed. In a code-first workflow, traces, config, and source changes can be reviewed together, which usually shortens time-to-fix when behavior drifts in hosted environments. ## Prerequisites -Before we start, make sure your environment can support both local debugging and hosted deployment. This chapter combines GitHub Copilot CLI, Foundry Toolkit, and Azure deployment assets, so missing setup usually slows things down in the middle of the workflow. If you validate these prerequisites first, the rest of the chapter stays focused on agent engineering, not environment troubleshooting. +Before we start, make sure your environment can support both local debugging and hosted deployment. This chapter combines GitHub Copilot CLI, Foundry Toolkit, and Azure deployment assets, so missing setup usually slows things down in the middle. + +If you validate these prerequisites first, the rest of the chapter stays focused on agent engineering, not environment troubleshooting. - **Editor and extension**: Visual Studio Code with Foundry Toolkit installed. - **GitHub Copilot access**: GitHub Copilot available in Visual Studio Code and terminal workflows. - **Cloud context**: An Azure subscription and Microsoft Foundry project. - **Model deployment**: A GPT-5 model instance already deployed in your project. -- **CLI readiness**: Azure Developer CLI and ability to sign in to Azure. +- **CLI readiness**: [Azure Developer CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd?tabs=winget-windows%2Cbrew-mac%2Cscript-linux&pivots=os-windows) and ability to sign in to Azure. -With the environment ready, we can define what this agent actually does and why the code-first path changes your delivery options. +## What You Will Learn -## What You Will Build +In this chapter, you create a code-based social campaign assistant for developer-focused content creation. Unlike a prompt-only prototype, this version is source-controlled, inspectable, and deployable as a hosted agent. -In this chapter, you create a code-based social campaign assistant for developer-focused content creation. Unlike a prompt-only prototype, this version is source-controlled, inspectable, and deployable as a hosted agent. Think of it as the bridge between experimentation and production-ready team workflows. +Think of it as the bridge between experimentation and production-ready team workflows. -For example, if your team wants custom business logic, repeatable deployment, and integration with app code, this architecture gives you a direct path without rebuilding everything from scratch. +You will learn how to: -- **Agent scaffold**: A coded project generated with GitHub Copilot CLI prompts. -- **Reusable tools**: A Foundry toolbox with Microsoft Learn MCP and web search. -- **Local runtime**: HTTP-based local agent service for invoke and debug loops. -- **Hosted target**: Deployment path to a managed hosted agent in Foundry. +- **Scaffold an agent project**: Generate a coded project with GitHub Copilot CLI prompts. +- **Attach reusable tools**: Configure a Foundry toolbox with Microsoft Learn MCP and web search. +- **Run a local runtime loop**: Use an HTTP-based local agent service for invoke and debug cycles. +- **Deploy to a hosted target**: Publish to a managed hosted agent in Foundry. Before we get hands-on, it helps to anchor the practical reason teams choose this model. ## Why Move to a Code-Based Agent -Teams choose coded agents when they need deeper control than a low-code builder can provide. That usually includes business-specific logic, deterministic configuration files, repeatable deployment, and direct integration with application code. In other words, code-based agents are not about complexity for its own sake, they are about control, reliability, and team-scale maintainability. +Teams choose coded agents when they need deeper control than a low-code builder can provide. That usually includes business-specific logic, deterministic configuration files, repeatable deployment, and direct integration with application code. + +In other words, code-based agents are not about complexity for its own sake. They are about control, reliability, and team-scale maintainability. If you have ever asked, "How do we make this agent predictable across environments?" this is the workflow that answers that question. @@ -55,99 +77,106 @@ If you have ever asked, "How do we make this agent predictable across environmen - **Repeatability**: Reproduce environments through config and infrastructure files. - **Production fit**: Deploy and operate through a hosted agent lifecycle. -The rest of the chapter follows the real delivery order most teams use, from scaffold to hosted deployment. - ## Step 1: Scaffold the Solution with GitHub Copilot CLI -Start by launching GitHub Copilot CLI in the terminal and describing the target solution in natural language. For this chapter, the scaffold prompt includes campaign-assistant behavior, clarifying-question behavior, retrieval tools, GPT-5 model usage, and hosted deployability. The key is to be explicit in one prompt so generation stays aligned with your intended architecture. +Start by launching GitHub Copilot CLI in the terminal and describing the target solution in natural language. For this chapter, the scaffold prompt includes campaign-assistant behavior, clarifying-question behavior, retrieval tools, GPT-5 model usage, and hosted deployability. + +Here's what we need to think about first. + +- **The prompt**: Describe behavior, tools, model, and deployment intent. +- **GitHub Copilot CLI**: Allow GitHub Copilot to execute multi-step setup with fewer interruptions. To do this, use Autopilot mode. + +Let's walk through the steps to scaffold a new agent project: 1. Open a terminal in your working folder. 2. Start GitHub Copilot CLI in that folder. -3. Confirm generated files are created in the intended project location. +3. Enter a natural language prompt that describes the agent behavior, tools, and deployment intent. +4. Confirm generated files are created in the intended project location. -A practical pattern is to include both functionality and operational constraints in the same request, for example, "configure toolbox tools and open the project folder when done." +See the example prompt below: -- **Natural language spec**: Describe behavior, tools, model, and deployment intent. -- **Autopilot mode**: Allow GitHub Copilot to execute multi-step setup with fewer interruptions. -- **Expected output**: A generated project folder and initial implementation artifacts. +![GitHub Copilot CLI scaffold prompt and generated project output](../images/ch4-agent-creation.png) -At this point, you should already have a project skeleton on disk. The immediate check is whether tool strategy was scaffolded for reuse instead of hard-coded inside one file. +**Fig 01: GitHub Copilot CLI scaffold prompt and generated project output.** -## Step 2: Create and Attach a Foundry Toolbox +At this point, you should already have a project skeleton on disk. Next, let's take a look at what was generated and confirm that it matches your intent. -The scaffold includes a toolbox so tools can be reused across agents instead of being embedded ad hoc. In this workflow, the toolbox includes Microsoft Learn MCP for official documentation and web search for fresh external context. This matters because it centralizes retrieval behavior and reduces copy-paste tool wiring across projects. +## Step 2: Review What GitHub Copilot Generated -1. Open your project in Foundry Toolkit. -2. Navigate to the tool configuration area. -3. Add Microsoft Learn MCP and web search. +Let's see what was generated. Here's what you should expect to see in the project folder: -For this scenario, one tool covers trusted product facts and one tool covers current web context, which is a practical retrieval split for campaign generation. +- **Main runtime**: `main.py` contains the core assistant logic and runtime wiring. +- **Agent config**: `agent.yaml` defines behavior, hosting, protocol, and runtime settings. +- **Tool config**: `toolbox.yaml` describes connected tools and tool endpoints. +- **Deployment config**: `azure.yaml` and `infra/` Bicep templates drive provisioning and deploy. -- **Microsoft grounding**: Use Learn MCP for validated product and docs context. -- **Freshness path**: Use web search for recent or time-sensitive information. -- **Reuse model**: Keep tool definitions portable across multiple agents. +If any file role looks unclear here, stop and resolve it before deployment. Ambiguity at this step usually becomes expensive once cloud resources are involved. -With tools attached, spend a minute reading the generated assets so you can predict behavior before you execute anything. +## Step 3: Verify Creation and Setup of Tools -## Step 3: Review What GitHub Copilot Generated +Now that you saw what was scaffolded at high level, let's dive into the tools that were setup as part of the scaffold. -After generation, inspect the project artifacts to understand runtime behavior and deployment shape. This review step is important because it lets you verify that generation used Foundry-specific context, not generic app scaffolding patterns. You should be able to explain what each core file controls before running anything. +In your open project, open the `toolbox.yaml` file and confirm that at least two tools were created: one for Microsoft Learn MCP and one for web search. -1. Open the generated folder in Visual Studio Code. -2. Inspect main.py. -3. Inspect agent.yaml. -4. Inspect toolbox.yaml. -5. Inspect azure.yaml. +Here's what they will do for us: -Use this quick map as you scan the folder: one file controls runtime behavior, one defines agent metadata, one configures tools, and one drives infrastructure. +- **Web Search**: Retrieve current web context for time-sensitive or trending information. +- **Microsoft Learn MCP**: Retrieve trusted product facts and documentation context. -- **Main runtime**: `main.py` contains the core assistant logic and runtime wiring. -- **Agent config**: `agent.yaml` defines behavior, hosting, protocol, and runtime settings. -- **Tool config**: `toolbox.yaml` describes connected tools and tool endpoints. -- **Deployment config**: `azure.yaml` and `infra/` Bicep templates drive provisioning and deploy. +See below how these tools are configured: -If any file role looks unclear here, stop and resolve it before deployment. Ambiguity at this step usually becomes expensive once cloud resources are involved. +![Foundry Toolbox configuration](../images/ch4-toolbox-configuration.png) + +**Fig 02: Foundry Toolbox configuration.** + +With tools attached, spend a minute reading the generated assets so you can predict behavior before you execute anything. ## Step 4: Run and Invoke the Agent Locally -Before deploying, validate local behavior from terminal-based commands. This gives you a fast feedback loop and catches instruction or runtime issues before cloud resources are involved. In the chapter flow, local invoke confirms the expected clarifying-question behavior. +Before deploying, validate local behavior from terminal-based commands. This gives you a fast feedback loop and catches instruction or runtime issues before cloud resources are involved. + +In the chapter flow, local invoke confirms expected clarifying-question behavior. 1. Run `azd ai agent run` from the project root. -2. Wait until the local runtime reports it is ready. -3. Invoke prompts only after the runtime is ready. -For example, after invoking with a campaign prompt, you should see targeted follow-up questions about audience, goals, and call-to-action details. + This command installs needed dependencies, starts the local runtime, and serves the agent as an HTTP service. + +2. Wait until the local runtime reports it is ready and then open a new terminal to invoke the agent. +3. Run the agent in a separate terminal with `azd ai agent invoke` and a realistic campaign prompt. + + You should see a result similar to: -- **Local run**: Start the agent runtime with `azd ai agent run`. -- **Prompt test**: Invoke with `azd ai agent invoke` and a realistic campaign request. -- **Behavior check**: Confirm clarifying questions, tone control, and campaign framing. + ![Local agent run](../images/ch4-local-invoke.png) -A clean local run proves basic behavior, but it does not prove observability. The next step adds that missing visibility. + **Fig 03: Local agent run and prompt invocation.** ## Step 5: Configure Agent Inspector Integration -To inspect and troubleshoot deeply, configure the project for Agent Inspector. The chapter flow uses GitHub Copilot to verify HTTP serving requirements, install dependencies, and prepare Visual Studio Code debug configuration. This is where your project becomes easy to debug repeatedly, not just runnable once. +To inspect and troubleshoot deeply, configure the project for Agent Inspector. The chapter flow uses GitHub Copilot to verify HTTP serving requirements, install dependencies, and prepare Visual Studio Code debug configuration. -1. Open the Run and Debug panel in Visual Studio Code. -2. Confirm there is a valid launch configuration. -3. Press F5. +This is where your project becomes easy to debug repeatedly, not just runnable once. -A practical success signal is that pressing F5 launches the local agent plus inspector workflow without manual setup steps. If F5 fails, fix launch and environment wiring now rather than diagnosing inside hosted runs later. +1. Set up the inspector by running a prompt in GitHub Copilot Chat that describes how to wire the local agent to the inspector. -- **HTTP readiness**: Ensure the agent is served as an HTTP service. -- **Dependencies**: Install or reconcile required packages in the environment. -- **Debug config**: Add `.vscode/tasks.json` and `.vscode/launch.json`. -- **Runtime prep**: Select interpreter, activate virtual environment, and authenticate Azure. + See below image, but in short, you need to tell it to install a tool and configure tasks.json and launch.json for Visual Studio Code. + + ![Setup Agent Inspector](../images/ch4-setup-inspector.png) Once inspector wiring is in place, you can evaluate cause and effect directly instead of guessing from final output text. ## Step 6: Debug with Agent Inspector -Start debugging and open Agent Inspector to observe live runtime behavior. This gives you direct visibility into events, streaming deltas, metadata, traces, and tool calls. In practice, this is where agent development shifts from black-box guessing to inspectable engineering. +Now it's time to run the inspector: + +Start debugging and open Agent Inspector to observe live runtime behavior. This gives you direct visibility into events, streaming deltas, metadata, traces, and tool calls. + +You should see a playground you can interact with and traces on the right side. What you see should look similar to the image below. + +![Agent Inspector debug session](../images/ch4-inspector-debug.png) + +**Fig 04: Agent Inspector debug session with event timeline and trace views.** -1. Launch the debug session. -2. Submit one simple prompt. -3. Confirm a trace appears in the inspector timeline. +This is where agent development shifts from black-box guessing to inspectable engineering. As you test prompts, watch the event timeline and trace views to confirm that responses are progressing as expected and not silently skipping retrieval logic. @@ -156,69 +185,72 @@ As you test prompts, watch the event timeline and trace views to confirm that re - **Trace analysis**: Use tracing views to diagnose behavior divergence quickly. - **Iteration loop**: Prompt, inspect, refine instructions, and retest. -After one clean trace, force a prompt that cannot be answered well without retrieval so tool wiring gets a real stress test. +> TIP: After one clean trace, force a prompt that cannot be answered well without retrieval so tool wiring gets a real stress test. -## Step 7: Validate Tool Usage in Real Prompts +## Step 7: Follow up prompt to confirm retrieval behavior -Use follow-up prompts that force retrieval behavior so integrations are actually exercised. In the chapter flow, the agent invokes web search and returns multiple structured content options with call-to-action guidance. This step confirms that tool calls are not only configured but operationally useful. +At this point, the Agent is started and it's asking you follow up questions. Now we want to answer something back while also ensuring the agent is actually using the retrieval tools we configured. -1. Submit a Microsoft product question that requires current facts. -2. Verify a tool call appears before the final response. +Type a prompt like so: -For validation, do not stop at final output text. Inspect tool call inputs and outputs so you can verify retrieval quality, not just generation style. +```text +Highlight the mobile chat feature, drive installs, general dev audience, technical tone, #github copilot +``` -- **Tool invocation proof**: Confirm web search calls appear in inspector tooling views. -- **Output quality**: Check that response options remain technical and audience-specific. -- **Auditability**: Inspect each retrieval call and response shaping path. +Now you should see tools being invoked and a response being produced like so: -When retrieval behavior is stable and traceable, you are ready to spend cloud deployment effort. +![Follow-up prompt response](../images/ch4-follow-up.png) + +**Fig 05: Follow-up prompt response with tool invocation and structured output.** ## Step 8: Deploy as a Hosted Agent -Deploy the agent through the Foundry deployment experience after local validation is complete. The flow uses a Docker image path and Azure Container Registry, then publishes as a new hosted agent. This is the handoff from local development to cloud-hosted execution. +Next, deploy the agent to a hosted environment. This step uses the same project assets you just debugged locally, so you can be confident that behavior will be consistent. -1. Open the deployment flow from your project context. -2. Choose the Docker-based path. -3. Confirm the target Foundry project before publishing. +1. Click Deploy button in the Agent Inspector in top right corner. -Keep deployment settings explicit so runtime sizing and image source are traceable when debugging production behavior later. + You should see the following screen: -- **Deployment method**: Build and deploy from Docker configuration. -- **Hosting target**: Use Foundry-managed container registry defaults when appropriate. -- **Runtime sizing**: Set CPU and memory profile for the hosted agent. -- **Publish outcome**: Create the hosted agent resource in your Foundry project. + ![Deploy via Agent Inspector](../images/ch4-deploy.png) -After publish completes, run the same scenario in the cloud playground and compare behavior against your local baseline. + **Fig 06: Deploy via Agent Inspector.** -## Step 9: Test the Cloud-Hosted Agent +2. Click Next. +3. In Review and Deploy, choose Select Existing Dockerfile and locate it in your computer. Finally click Deploy to start the deployment process. -Open the hosted agent in Foundry project resources and test from the cloud playground. This mirrors local testing while validating the production-like hosted path. The objective is to confirm that behavior remains consistent after deployment. +## Quick Question -1. Run the same prompt used in local testing. -2. Compare follow-up questions between local and hosted runs. -3. Compare tool usage between local and hosted traces. +If local runs look correct but hosted responses drift, what should you check first: prompt wording, tool calls, or runtime/deployment configuration? -A useful check here is to run the same prompt you used locally and compare follow-up question quality, tool usage, and output structure. +## Answer -- **Resource checks**: Verify status, details, and runtime health. -- **Cloud interaction**: Run campaign prompts against hosted endpoints. -- **Operational insight**: Review traces and behavior under hosted execution. +Start with runtime and deployment configuration plus tool-call traces, then revisit prompt wording. Hosted drift often comes from environment or integration differences that are invisible in prompt text alone. Once runtime parity is confirmed, prompt refinements become much more reliable. -At this point, you have executed the full lifecycle from scaffold to hosted runtime, so we can summarize why this flow holds up in team settings. +## What's Next -## Why This Workflow Works +After shipping a hosted code-based agent, the next step is hardening the lifecycle for ongoing releases. Focus on stronger evaluation pipelines, tracing-driven debugging practices, and automation for deployment and regression checks as agent scope grows. -This chapter demonstrates how GitHub Copilot CLI, Foundry skills, Agent Framework, Agent Inspector, and hosted deployment connect into one coherent engineering loop. Instead of treating the agent as a black box, this workflow makes behavior observable, testable, and repeatable. That combination is what turns prototypes into maintainable systems. +The next chapter should feel like an extension of this workflow, not a reset. -In practical terms, each stage removes a specific risk before the next stage adds cost. +## Your Challenge -- **Engineering transparency**: Inspect tool calls, events, and traces end to end. -- **Quality control**: Catch behavioral drift before shipping to stakeholders. -- **Scalable delivery**: Move from prototype to hosted deployment with fewer manual steps. -- **Team readiness**: Produce a source-controlled agent that can be evolved safely. +Now that you have seen the full hosted flow, try a small production-style exercise on your own. The goal is to prove that you can move from scaffold to repeatable validation without guessing. +Use this checklist as your action plan. -From here, the next move is release hardening so future updates stay predictable. +1. Scaffold a new hosted agent for a different scenario using GitHub Copilot CLI. +2. Add at least one grounding tool and one instruction rule for when it must be used. +3. Validate behavior locally with at least two prompts that force tool usage. +4. Deploy the agent and compare one local trace to one hosted trace. +5. Document one behavior difference and the fix you applied. -## What's Next +Success target: you can explain the full path from prompt input to hosted output and show evidence for each stage. + +## Learn more + +If you want to go deeper after this chapter, the best path is to pair platform guidance with hosted-agent deployment references. This gives you production context and practical next steps for what to do next. +Use the links below as a practical continuation path. -After shipping a hosted code-based agent, the next step is hardening the lifecycle for ongoing releases. Focus on stronger evaluation pipelines, tracing-driven debugging practices, and automation for deployment and regression checks as agent scope grows. The next chapter should feel like an extension of this workflow, not a reset. \ No newline at end of file +- **GitHub Copilot in Visual Studio Code**: [Review Copilot workflows in Visual Studio Code docs](https://code.visualstudio.com/docs/copilot/overview). +- **Azure AI Foundry overview**: [Understand the broader Azure AI Foundry platform and workflows](https://learn.microsoft.com/azure/ai-foundry/). +- **Azure AI Agents overview**: [Review hosted-agent concepts and lifecycle guidance](https://learn.microsoft.com/azure/ai-services/agents/overview). +- **Azure Developer CLI documentation**: [Use azd for repeatable setup and deployment workflows](https://learn.microsoft.com/azure/developer/azure-developer-cli/). \ No newline at end of file From d25777aae5954560e42b9af6573d4bf9f8812c60 Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 15 Jul 2026 11:53:57 +0000 Subject: [PATCH 5/6] adding images, renaming them and updating references --- .../1-get-started.md | 10 +++++----- .../2-exploring-models.md | 12 +++++------ .../3-building-social-media-agent.md | 20 +++++++++---------- .../4-building-hosted-agent.md | 14 ++++++------- .../foundry-toolkit/ch1-fig01-journey.png | 3 +++ .../ch1-fig03-toolkit-architecture.png | 3 +++ .../ch1-foundry-toolkit-developer-tools.png | 3 +++ .../ch1-foundry-toolkit-resources.png | 3 +++ .../foundry-toolkit/ch1-foundry-toolkit.png | 3 +++ learn/images/foundry-toolkit/ch2-deploy.png | 3 +++ .../foundry-toolkit/ch2-example-result.png | 3 +++ .../images/foundry-toolkit/ch2-model-card.png | 3 +++ .../foundry-toolkit/ch2-model-catalog.png | 3 +++ .../foundry-toolkit/ch2-model-filter.png | 3 +++ .../ch2-prompt-recommendation.png | 3 +++ .../foundry-toolkit/ch3-create-agent.png | 3 +++ learn/images/foundry-toolkit/ch3-dataset.png | 3 +++ .../foundry-toolkit/ch3-evaluation-area.png | 3 +++ .../foundry-toolkit/ch3-evaluation-result.png | 3 +++ .../images/foundry-toolkit/ch3-mcp-server.png | 3 +++ learn/images/foundry-toolkit/ch3-mcp.png | 3 +++ learn/images/foundry-toolkit/ch3-save.png | 3 +++ .../foundry-toolkit/ch3-system-prompt.png | 3 +++ learn/images/foundry-toolkit/ch3-testing.png | 3 +++ .../foundry-toolkit/ch3-tool-guidance.png | 3 +++ .../foundry-toolkit/ch4-agent-creation.png | 3 +++ learn/images/foundry-toolkit/ch4-deploy.png | 3 +++ .../images/foundry-toolkit/ch4-follow-up.png | 3 +++ .../foundry-toolkit/ch4-inspector-debug.png | 3 +++ .../foundry-toolkit/ch4-local-invoke.png | 3 +++ .../foundry-toolkit/ch4-setup-inspector.png | 3 +++ .../ch4-toolbox-configuration.png | 3 +++ 32 files changed, 112 insertions(+), 28 deletions(-) create mode 100644 learn/images/foundry-toolkit/ch1-fig01-journey.png create mode 100644 learn/images/foundry-toolkit/ch1-fig03-toolkit-architecture.png create mode 100644 learn/images/foundry-toolkit/ch1-foundry-toolkit-developer-tools.png create mode 100644 learn/images/foundry-toolkit/ch1-foundry-toolkit-resources.png create mode 100644 learn/images/foundry-toolkit/ch1-foundry-toolkit.png create mode 100644 learn/images/foundry-toolkit/ch2-deploy.png create mode 100644 learn/images/foundry-toolkit/ch2-example-result.png create mode 100644 learn/images/foundry-toolkit/ch2-model-card.png create mode 100644 learn/images/foundry-toolkit/ch2-model-catalog.png create mode 100644 learn/images/foundry-toolkit/ch2-model-filter.png create mode 100644 learn/images/foundry-toolkit/ch2-prompt-recommendation.png create mode 100644 learn/images/foundry-toolkit/ch3-create-agent.png create mode 100644 learn/images/foundry-toolkit/ch3-dataset.png create mode 100644 learn/images/foundry-toolkit/ch3-evaluation-area.png create mode 100644 learn/images/foundry-toolkit/ch3-evaluation-result.png create mode 100644 learn/images/foundry-toolkit/ch3-mcp-server.png create mode 100644 learn/images/foundry-toolkit/ch3-mcp.png create mode 100644 learn/images/foundry-toolkit/ch3-save.png create mode 100644 learn/images/foundry-toolkit/ch3-system-prompt.png create mode 100644 learn/images/foundry-toolkit/ch3-testing.png create mode 100644 learn/images/foundry-toolkit/ch3-tool-guidance.png create mode 100644 learn/images/foundry-toolkit/ch4-agent-creation.png create mode 100644 learn/images/foundry-toolkit/ch4-deploy.png create mode 100644 learn/images/foundry-toolkit/ch4-follow-up.png create mode 100644 learn/images/foundry-toolkit/ch4-inspector-debug.png create mode 100644 learn/images/foundry-toolkit/ch4-local-invoke.png create mode 100644 learn/images/foundry-toolkit/ch4-setup-inspector.png create mode 100644 learn/images/foundry-toolkit/ch4-toolbox-configuration.png diff --git a/learn/foundry-toolkit-extension/1-get-started.md b/learn/foundry-toolkit-extension/1-get-started.md index 077983de71a..f89735ad597 100644 --- a/learn/foundry-toolkit-extension/1-get-started.md +++ b/learn/foundry-toolkit-extension/1-get-started.md @@ -43,7 +43,7 @@ Now that the destination is clear, here is the one idea that makes everything el A quick map helps you see the chapter flow before we zoom in. Think of it as your "you are here" sign while you move through setup. -![Chapter 1 journey diagram](../images/ch01-fig01-journey.png) +![Chapter 1 journey diagram](../images/foundry-toolkit/ch1-fig01-journey.png) **Fig 01: Chapter 1 journey from first install to model-ready workspace.** @@ -87,7 +87,7 @@ To get you excited, here is a quick list of the core capabilities you will use i Here's the extension you're about to install. It is the one surface you will keep coming back to for most of the series. -![Foundry Toolkit](../images/foundry-toolkit.png) +![Foundry Toolkit](../images/foundry-toolkit/ch1-foundry-toolkit.png) **Fig 1: Foundry Toolkit Extension in Visual Studio Code** @@ -110,7 +110,7 @@ Once Foundry Toolkit is installed, the UI is organized into sections that mirror Here's a diagram showing the three main sections and how they relate to each other. -![Foundry Toolkit architecture diagram](../images/ch01-fig03-toolkit-architecture.png) +![Foundry Toolkit architecture diagram](../images/foundry-toolkit/ch1-fig03-toolkit-architecture.png) **Fig 02: Foundry Toolkit information architecture and core working areas.** @@ -131,7 +131,7 @@ If this section looks right, you are in great shape. Once resources are visible, we can move to the section where you actively build. -![Foundry Toolkit resources](../images/foundry-toolkit-resources.png) +![Foundry Toolkit resources](../images/foundry-toolkit/ch1-foundry-toolkit-resources.png) **Fig 03: Foundry Toolkit My Resources section showing local and cloud assets.** @@ -151,7 +151,7 @@ For example, a common loop is: open Model Catalog, test a prompt in Playground, After building and monitoring, you still need support and feedback channels to keep improving. -![Foundry Toolkit developer tools](../images/foundry-toolkit-developer-tools.png) +![Foundry Toolkit developer tools](../images/foundry-toolkit/ch1-foundry-toolkit-developer-tools.png) **Fig 04: Foundry Toolkit Developer Tools section showing Discover, Build, and Monitor areas.** diff --git a/learn/foundry-toolkit-extension/2-exploring-models.md b/learn/foundry-toolkit-extension/2-exploring-models.md index 035d04b3bd5..9d321286f99 100644 --- a/learn/foundry-toolkit-extension/2-exploring-models.md +++ b/learn/foundry-toolkit-extension/2-exploring-models.md @@ -110,13 +110,13 @@ Next, let's use this prompt: Recommend two models for a marketing scenario that require image input support and are deployable in my subscription and region. ``` - ![Example prompt asking Copilot for recommendations](../images/ch2-prompt-recommendation.png) + ![Example prompt asking Copilot for recommendations](../images/foundry-toolkit/ch2-prompt-recommendation.png) **Fig 1: Example prompt asking GitHub Copilot for model recommendations.** 4. Review the response and note the recommended models. - ![Example result from Copilot recommendations](../images/ch2-example-result.png) + ![Example result from Copilot recommendations](../images/foundry-toolkit/ch2-example-result.png) **Fig 2: Example result from GitHub Copilot recommendations.** @@ -136,7 +136,7 @@ Next, let's open the catalog and see how we can reduce the candidate set to a ma Now you should see a list of models that includes multiple providers and hosting paths, something like the below image: -![Model Catalog in Foundry Toolkit](../images/ch2-model-catalog.png) +![Model Catalog in Foundry Toolkit](../images/foundry-toolkit/ch2-model-catalog.png) **Fig 3: Model Catalog in Foundry Toolkit.** @@ -164,7 +164,7 @@ Next, let's go from "interesting list" to "actual candidates." You should see a reduced candidate list similar to below. - ![Model filter panel in Foundry Toolkit](../images/ch2-model-filter.png) + ![Model filter panel in Foundry Toolkit](../images/foundry-toolkit/ch2-model-filter.png) **Fig 4: Model filter panel in Foundry Toolkit. Here we select Hosted By: Foundry, Publisher: OpenAI** @@ -191,7 +191,7 @@ To review a model card: 2. Open its model card page. 3. Check capabilities and pricing before moving to deployment. -![Model card review details](../images/ch2-model-card.png) +![Model card review details](../images/foundry-toolkit/ch2-model-card.png) After you're satisfied with the model card review, you are ready to deploy the candidates into your Foundry project for side-by-side comparison. @@ -204,7 +204,7 @@ Great, let's kick off a deployment. 1. Choose Deploy from the model card. 2. Select your connected Foundry project as the deployment target. -![Deployment in Foundry Playground](../images/ch2-deploy.png) +![Deployment in Foundry Playground](../images/foundry-toolkit/ch2-deploy.png) This should kick off a deployment process that takes a few minutes. Once complete, you will see the deployed model in your Foundry project. diff --git a/learn/foundry-toolkit-extension/3-building-social-media-agent.md b/learn/foundry-toolkit-extension/3-building-social-media-agent.md index b8b3ef61442..3f9fab6a871 100644 --- a/learn/foundry-toolkit-extension/3-building-social-media-agent.md +++ b/learn/foundry-toolkit-extension/3-building-social-media-agent.md @@ -77,7 +77,7 @@ Follow these steps to create the agent: Here's what you should see once you kick off a create-agent flow in Agent Builder. -![Placeholder image: Agent creation in Agent Builder](../images/ch3-create-agent.png) +![Placeholder image: Agent creation in Agent Builder](../images/foundry-toolkit/ch3-create-agent.png) **Fig 01: Create a new agent in Agent Builder.** @@ -96,7 +96,7 @@ Here's what to consider when crafting instructions for a social content agent: Below is an example of a system prompt that captures these requirements. You can adapt it to your own style and team needs. -![System prompt configuration](../images/ch3-system-prompt.png) +![System prompt configuration](../images/foundry-toolkit/ch3-system-prompt.png) **Fig 02: Define system prompt instructions for the social content agent.** @@ -110,7 +110,7 @@ It also gives you a clean base version before adding tools. Select the Save button, it should given you two options: Save to Foundry or Save to local file. Choose **Save to Foundry**. -![Save to Microsoft Foundry](../images/ch3-save.png) +![Save to Microsoft Foundry](../images/foundry-toolkit/ch3-save.png) **Fig 03: Save the agent to project resources for reuse and versioning.** @@ -124,7 +124,7 @@ For this scenario, grounding matters whenever campaign text references product c 1. In the Tool section, click "+" and select MCP Server - ![Add MCP Server](../images/ch3-mcp-server.png) + ![Add MCP Server](../images/foundry-toolkit/ch3-mcp-server.png) **Fig 04: Select MCP Server in Tools** @@ -132,7 +132,7 @@ For this scenario, grounding matters whenever campaign text references product c 2. Select the Microsoft Learn MCP server from the list of available servers. - ![MCP tool setup](../images/ch3-mcp.png) + ![MCP tool setup](../images/foundry-toolkit/ch3-mcp.png) **Fig 05: Add MCP server tools to the agent for grounded responses.** @@ -153,7 +153,7 @@ In practice, you want explicit trigger logic such as: if the prompt asks about M Here's an example of how to phrase this in the system prompt so the agent knows when to call tools and how to use retrieved context. You're asking the agent to think in steps, analyze intent, and then decide what tool to call and possible additional tool calls. Finally, add guidance to constrain what the agent can and can't do with the retrieved context. -![Tool instructions](../images/ch3-tool-guidance.png) +![Tool instructions](../images/foundry-toolkit/ch3-tool-guidance.png) **Fig 05: Add tool-use guidance to the agent instructions.** @@ -178,7 +178,7 @@ Here's what to look for when testing: See below image that shows a typed prompt, which tools are invoked and the final output from the agent. -![Testing in Playground](../images/ch3-testing.png) +![Testing in Playground](../images/foundry-toolkit/ch3-testing.png) **Fig 05: Test the agent in the playground with realistic prompts.** @@ -205,7 +205,7 @@ Let's say you have an Agent like this, then here's how you set up evaluation. See "Evaluation" tab" in below image. Select that. - ![Evaluation area from Agent creation](../images/ch3-evaluation-area.png) + ![Evaluation area from Agent creation](../images/foundry-toolkit/ch3-evaluation-area.png) 2. Select to generate a dataset by clicking the top left button. @@ -213,14 +213,14 @@ Let's say you have an Agent like this, then here's how you set up evaluation. Here's a set of generated prompts it can run against your model. - ![Generate dataset modal](../images/ch3-dataset.png) + ![Generate dataset modal](../images/foundry-toolkit/ch3-dataset.png) 3. Test your Agent by running an evaluation (select Play icon) You should see how each prompt is run agains your Agent and you can provide a thumbs up/thumbs down on the result. - ![Evaluation result](../images/ch3-evaluation-result.png) + ![Evaluation result](../images/foundry-toolkit/ch3-evaluation-result.png) **Fig 06: Configure evaluation settings for the agent.** diff --git a/learn/foundry-toolkit-extension/4-building-hosted-agent.md b/learn/foundry-toolkit-extension/4-building-hosted-agent.md index ddf25c1ff6e..ed8a02d2445 100644 --- a/learn/foundry-toolkit-extension/4-building-hosted-agent.md +++ b/learn/foundry-toolkit-extension/4-building-hosted-agent.md @@ -95,7 +95,7 @@ Let's walk through the steps to scaffold a new agent project: See the example prompt below: -![GitHub Copilot CLI scaffold prompt and generated project output](../images/ch4-agent-creation.png) +![GitHub Copilot CLI scaffold prompt and generated project output](../images/foundry-toolkit/ch4-agent-creation.png) **Fig 01: GitHub Copilot CLI scaffold prompt and generated project output.** @@ -125,7 +125,7 @@ Here's what they will do for us: See below how these tools are configured: -![Foundry Toolbox configuration](../images/ch4-toolbox-configuration.png) +![Foundry Toolbox configuration](../images/foundry-toolkit/ch4-toolbox-configuration.png) **Fig 02: Foundry Toolbox configuration.** @@ -146,7 +146,7 @@ In the chapter flow, local invoke confirms expected clarifying-question behavior You should see a result similar to: - ![Local agent run](../images/ch4-local-invoke.png) + ![Local agent run](../images/foundry-toolkit/ch4-local-invoke.png) **Fig 03: Local agent run and prompt invocation.** @@ -160,7 +160,7 @@ This is where your project becomes easy to debug repeatedly, not just runnable o See below image, but in short, you need to tell it to install a tool and configure tasks.json and launch.json for Visual Studio Code. - ![Setup Agent Inspector](../images/ch4-setup-inspector.png) + ![Setup Agent Inspector](../images/foundry-toolkit/ch4-setup-inspector.png) Once inspector wiring is in place, you can evaluate cause and effect directly instead of guessing from final output text. @@ -172,7 +172,7 @@ Start debugging and open Agent Inspector to observe live runtime behavior. This You should see a playground you can interact with and traces on the right side. What you see should look similar to the image below. -![Agent Inspector debug session](../images/ch4-inspector-debug.png) +![Agent Inspector debug session](../images/foundry-toolkit/ch4-inspector-debug.png) **Fig 04: Agent Inspector debug session with event timeline and trace views.** @@ -199,7 +199,7 @@ Highlight the mobile chat feature, drive installs, general dev audience, technic Now you should see tools being invoked and a response being produced like so: -![Follow-up prompt response](../images/ch4-follow-up.png) +![Follow-up prompt response](../images/foundry-toolkit/ch4-follow-up.png) **Fig 05: Follow-up prompt response with tool invocation and structured output.** @@ -211,7 +211,7 @@ Next, deploy the agent to a hosted environment. This step uses the same project You should see the following screen: - ![Deploy via Agent Inspector](../images/ch4-deploy.png) + ![Deploy via Agent Inspector](../images/foundry-toolkit/ch4-deploy.png) **Fig 06: Deploy via Agent Inspector.** diff --git a/learn/images/foundry-toolkit/ch1-fig01-journey.png b/learn/images/foundry-toolkit/ch1-fig01-journey.png new file mode 100644 index 00000000000..1e68b942e26 --- /dev/null +++ b/learn/images/foundry-toolkit/ch1-fig01-journey.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:44bc020189f3648fd5e3125ca66f2944a0316a0140512cd71667efd7dbae82ff +size 11738 diff --git a/learn/images/foundry-toolkit/ch1-fig03-toolkit-architecture.png b/learn/images/foundry-toolkit/ch1-fig03-toolkit-architecture.png new file mode 100644 index 00000000000..bf30140d933 --- /dev/null +++ b/learn/images/foundry-toolkit/ch1-fig03-toolkit-architecture.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:fc3a5d0295ebcf1e526bc1144a3301d938ddd9a8f796cda84171d26fa7da7fdc +size 33050 diff --git a/learn/images/foundry-toolkit/ch1-foundry-toolkit-developer-tools.png b/learn/images/foundry-toolkit/ch1-foundry-toolkit-developer-tools.png new file mode 100644 index 00000000000..fe7355481cd --- /dev/null +++ b/learn/images/foundry-toolkit/ch1-foundry-toolkit-developer-tools.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b372a5a0a5aec809937a1c12a7a661f7a86e4e4f87e0b1f813e48b5f81181d56 +size 17949 diff --git a/learn/images/foundry-toolkit/ch1-foundry-toolkit-resources.png b/learn/images/foundry-toolkit/ch1-foundry-toolkit-resources.png new file mode 100644 index 00000000000..4c0e7ce4405 --- /dev/null +++ b/learn/images/foundry-toolkit/ch1-foundry-toolkit-resources.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4db7b1c96ef017def0a7043c758718433fa85ed3b9651c4e6df17b40bd7464ba +size 17633 diff --git a/learn/images/foundry-toolkit/ch1-foundry-toolkit.png b/learn/images/foundry-toolkit/ch1-foundry-toolkit.png new file mode 100644 index 00000000000..509a2eed7ea --- /dev/null +++ b/learn/images/foundry-toolkit/ch1-foundry-toolkit.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:975a33626632237cc9fc869d5c5fd2eed2b2827ddbd46298c9069606672e7e5e +size 227878 diff --git a/learn/images/foundry-toolkit/ch2-deploy.png b/learn/images/foundry-toolkit/ch2-deploy.png new file mode 100644 index 00000000000..4c94e44f824 --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-deploy.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c8f519f1350823ceb6e23ded73cfb52c9bf621faf387dd4eeb0bfec8a4320f85 +size 17524 diff --git a/learn/images/foundry-toolkit/ch2-example-result.png b/learn/images/foundry-toolkit/ch2-example-result.png new file mode 100644 index 00000000000..97be73cbd7e --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-example-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:4c69fcff55255191874e450fc62137bbaec9209cd1e96a84c98f9981a6aa017e +size 306190 diff --git a/learn/images/foundry-toolkit/ch2-model-card.png b/learn/images/foundry-toolkit/ch2-model-card.png new file mode 100644 index 00000000000..98692deaf30 --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-model-card.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:df684fdd41a0f1126302ddfd6f1a31a49ad563b50ab4477458452965216399e6 +size 17408 diff --git a/learn/images/foundry-toolkit/ch2-model-catalog.png b/learn/images/foundry-toolkit/ch2-model-catalog.png new file mode 100644 index 00000000000..8e37a1ba93e --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-model-catalog.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c11aeb8268230dd0f8cd2a7e328cf75c211680851e4929cdeca9606cb3009c09 +size 132429 diff --git a/learn/images/foundry-toolkit/ch2-model-filter.png b/learn/images/foundry-toolkit/ch2-model-filter.png new file mode 100644 index 00000000000..729cb832884 --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-model-filter.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2c1a9cf97c43282bf77997570a0a0c29962a38b62ed089db2ac23012a3266f06 +size 105230 diff --git a/learn/images/foundry-toolkit/ch2-prompt-recommendation.png b/learn/images/foundry-toolkit/ch2-prompt-recommendation.png new file mode 100644 index 00000000000..90ef23df9b1 --- /dev/null +++ b/learn/images/foundry-toolkit/ch2-prompt-recommendation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:1075cbe60149b977dd030133914ddf4438bf0047e1a5f764ad325876bf2cbfe9 +size 117646 diff --git a/learn/images/foundry-toolkit/ch3-create-agent.png b/learn/images/foundry-toolkit/ch3-create-agent.png new file mode 100644 index 00000000000..d458ebccc4c --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-create-agent.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:96ec988793a9402443cf21fc156351392c9bb60502cf4a23a9e76f3d9bdb06a1 +size 64352 diff --git a/learn/images/foundry-toolkit/ch3-dataset.png b/learn/images/foundry-toolkit/ch3-dataset.png new file mode 100644 index 00000000000..b89afee4ec8 --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-dataset.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ca01ae99371af93c5f61056a796353f015b32bb3c89eb2b95ac84c6381ec4f82 +size 52881 diff --git a/learn/images/foundry-toolkit/ch3-evaluation-area.png b/learn/images/foundry-toolkit/ch3-evaluation-area.png new file mode 100644 index 00000000000..99ffcc4f605 --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-evaluation-area.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:8a57ca0a53786e2df954dad9ab7b0d489b7d4da331b94bac08e1fa3ff73066dd +size 31173 diff --git a/learn/images/foundry-toolkit/ch3-evaluation-result.png b/learn/images/foundry-toolkit/ch3-evaluation-result.png new file mode 100644 index 00000000000..d170660fc90 --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-evaluation-result.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:22b00b93d2227178331c0ec623c6fbc2f2b9e8501a25fbe5f2b57f2d6a7402b2 +size 76116 diff --git a/learn/images/foundry-toolkit/ch3-mcp-server.png b/learn/images/foundry-toolkit/ch3-mcp-server.png new file mode 100644 index 00000000000..d0fb720266d --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-mcp-server.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:82abb86d557f5f1255179531d5d6c7ecf9739d2029838633d35f849d5530b3bc +size 27490 diff --git a/learn/images/foundry-toolkit/ch3-mcp.png b/learn/images/foundry-toolkit/ch3-mcp.png new file mode 100644 index 00000000000..b2322cace1c --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-mcp.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:42b51d3605599fb673e18cfb47de86aedbf3ae4598ed5c5996b423c5a4efd861 +size 231047 diff --git a/learn/images/foundry-toolkit/ch3-save.png b/learn/images/foundry-toolkit/ch3-save.png new file mode 100644 index 00000000000..32fea36941f --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-save.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b88ebc5442f0655e0a39755f91d4c0c396a2770cd84313d05098747203c51b04 +size 37060 diff --git a/learn/images/foundry-toolkit/ch3-system-prompt.png b/learn/images/foundry-toolkit/ch3-system-prompt.png new file mode 100644 index 00000000000..843d2d4c75c --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-system-prompt.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:432bca7c7330b5ff09aed6b5c71aea344c8a58c45a1e19532f26af843a78fbe2 +size 276869 diff --git a/learn/images/foundry-toolkit/ch3-testing.png b/learn/images/foundry-toolkit/ch3-testing.png new file mode 100644 index 00000000000..3a043cc946c --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-testing.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:b7b2a42537c24d6ea33aa8ce0f0ad8cc45f2f8a080123a3977feb7ace2dd93a8 +size 171883 diff --git a/learn/images/foundry-toolkit/ch3-tool-guidance.png b/learn/images/foundry-toolkit/ch3-tool-guidance.png new file mode 100644 index 00000000000..0dae8a2bd5f --- /dev/null +++ b/learn/images/foundry-toolkit/ch3-tool-guidance.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:c5f308c0bb0fc7e9850040a6a0feac5b2dd6155be1952d2ca4a94b4705aadf38 +size 358965 diff --git a/learn/images/foundry-toolkit/ch4-agent-creation.png b/learn/images/foundry-toolkit/ch4-agent-creation.png new file mode 100644 index 00000000000..b455d24d28b --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-agent-creation.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:7e8e9b9860f20241d866350b22354094e47da262697969f29afe9406541d9a6a +size 291170 diff --git a/learn/images/foundry-toolkit/ch4-deploy.png b/learn/images/foundry-toolkit/ch4-deploy.png new file mode 100644 index 00000000000..4be55de407d --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-deploy.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e910db667f24a60d4c68b8465779cf3e7281ae6fe3b88619db2f43da64739bc1 +size 157164 diff --git a/learn/images/foundry-toolkit/ch4-follow-up.png b/learn/images/foundry-toolkit/ch4-follow-up.png new file mode 100644 index 00000000000..1987de8c5bc --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-follow-up.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6fa5e5c81b4d9fd4142dccce86c4522bb226a042d99b2f15ad9f5f7864b6e306 +size 405735 diff --git a/learn/images/foundry-toolkit/ch4-inspector-debug.png b/learn/images/foundry-toolkit/ch4-inspector-debug.png new file mode 100644 index 00000000000..376485460ab --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-inspector-debug.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:e90442b69771bf8ed6068c01fa7bd9a93af5ec3622563bcde9283e6e4bef6203 +size 302077 diff --git a/learn/images/foundry-toolkit/ch4-local-invoke.png b/learn/images/foundry-toolkit/ch4-local-invoke.png new file mode 100644 index 00000000000..e1fc21176ed --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-local-invoke.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:158ec82acc4cc09a7c2b2a7b98aa37fc09ea9bab4b64762a984d90c4530748e3 +size 158975 diff --git a/learn/images/foundry-toolkit/ch4-setup-inspector.png b/learn/images/foundry-toolkit/ch4-setup-inspector.png new file mode 100644 index 00000000000..bd48ea9322a --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-setup-inspector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2fb4b7968a5f0ee401867a92d12cf6fed3eaf91d05394ad9908fd1e16f1e41d2 +size 124495 diff --git a/learn/images/foundry-toolkit/ch4-toolbox-configuration.png b/learn/images/foundry-toolkit/ch4-toolbox-configuration.png new file mode 100644 index 00000000000..02b11d047cf --- /dev/null +++ b/learn/images/foundry-toolkit/ch4-toolbox-configuration.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:df81319bea0af4f70bdcd802a3a1fec41393ac0e8f76217bc4631f3a9ba6b548 +size 541302 From 1e16796886d22370fe1ad45ff90ea3fa7c1830d9 Mon Sep 17 00:00:00 2001 From: chris Date: Wed, 15 Jul 2026 12:02:02 +0000 Subject: [PATCH 6/6] adding editorial fixes --- .../1-get-started.md | 2 +- .../2-exploring-models.md | 2 +- .../3-building-social-media-agent.md | 14 +++++++------- .../4-building-hosted-agent.md | 19 +++++++++++++------ 4 files changed, 22 insertions(+), 15 deletions(-) diff --git a/learn/foundry-toolkit-extension/1-get-started.md b/learn/foundry-toolkit-extension/1-get-started.md index f89735ad597..e1374a96f1d 100644 --- a/learn/foundry-toolkit-extension/1-get-started.md +++ b/learn/foundry-toolkit-extension/1-get-started.md @@ -20,7 +20,7 @@ You know that moment when a prototype looks great, but the team still feels slow In this chapter, we'll make that into one flow inside Visual Studio Code so day-to-day work feels clear, fast, and honestly more fun. -No more tab Olympics, I promise. +No more jumping between disconnected tools. By the end, you will have Foundry Toolkit installed, connected, and ready for real model and agent work. You will not just know where to click, you will understand why this setup order works and why the next chapters feel lighter because of it. diff --git a/learn/foundry-toolkit-extension/2-exploring-models.md b/learn/foundry-toolkit-extension/2-exploring-models.md index 9d321286f99..4512e9291cf 100644 --- a/learn/foundry-toolkit-extension/2-exploring-models.md +++ b/learn/foundry-toolkit-extension/2-exploring-models.md @@ -159,7 +159,7 @@ Next, let's go from "interesting list" to "actual candidates." 1. Open the filter panel in Model Catalog. 2. Set the filter like so: - Hosted BY: **Foundry** + Hosted By: **Foundry** Publisher: **OpenAI** You should see a reduced candidate list similar to below. diff --git a/learn/foundry-toolkit-extension/3-building-social-media-agent.md b/learn/foundry-toolkit-extension/3-building-social-media-agent.md index 3f9fab6a871..2b7345ca9c5 100644 --- a/learn/foundry-toolkit-extension/3-building-social-media-agent.md +++ b/learn/foundry-toolkit-extension/3-building-social-media-agent.md @@ -14,7 +14,7 @@ Keywords: # Building a Social Media Content Agent with Agent Builder - + This chapter walks through building a practical social media content agent using Agent Builder in Foundry Toolkit. The goal is not just to generate text, but to create an assistant that asks the right follow-up questions, uses trusted context, and returns output a team can actually review and ship. @@ -108,7 +108,7 @@ After defining instructions, save the agent to your Foundry project so it appear It also gives you a clean base version before adding tools. -Select the Save button, it should given you two options: Save to Foundry or Save to local file. Choose **Save to Foundry**. +Select the Save button. It should give you two options: Save to Foundry or Save to local file. Choose **Save to Foundry**. ![Save to Microsoft Foundry](../images/foundry-toolkit/ch3-save.png) @@ -155,7 +155,7 @@ Here's an example of how to phrase this in the system prompt so the agent knows ![Tool instructions](../images/foundry-toolkit/ch3-tool-guidance.png) -**Fig 05: Add tool-use guidance to the agent instructions.** +**Fig 06: Add tool-use guidance to the agent instructions.** At this stage, run realistic tests in the playground. @@ -180,7 +180,7 @@ See below image that shows a typed prompt, which tools are invoked and the final ![Testing in Playground](../images/foundry-toolkit/ch3-testing.png) -**Fig 05: Test the agent in the playground with realistic prompts.** +**Fig 07: Test the agent in the playground with realistic prompts.** Manual testing is useful, but the next step is where quality becomes measurable. @@ -203,7 +203,7 @@ Let's say you have an Agent like this, then here's how you set up evaluation. 1. Select evaluation area and select to generate a dataset (top left button) - See "Evaluation" tab" in below image. Select that. + See the "Evaluation" tab in the image below. Select that. ![Evaluation area from Agent creation](../images/foundry-toolkit/ch3-evaluation-area.png) @@ -218,11 +218,11 @@ Let's say you have an Agent like this, then here's how you set up evaluation. 3. Test your Agent by running an evaluation (select Play icon) - You should see how each prompt is run agains your Agent and you can provide a thumbs up/thumbs down on the result. + You should see how each prompt is run against your Agent and you can provide a thumbs up/thumbs down on the result. ![Evaluation result](../images/foundry-toolkit/ch3-evaluation-result.png) - **Fig 06: Configure evaluation settings for the agent.** + **Fig 08: Configure evaluation settings for the agent.** This is a great way to get a quick sense of how your Agent is performing against the generated dataset. You can adjust the Agent's instructions, tools, or other settings and re-run the evaluation to see if performance improves. diff --git a/learn/foundry-toolkit-extension/4-building-hosted-agent.md b/learn/foundry-toolkit-extension/4-building-hosted-agent.md index ed8a02d2445..e411d6a92a6 100644 --- a/learn/foundry-toolkit-extension/4-building-hosted-agent.md +++ b/learn/foundry-toolkit-extension/4-building-hosted-agent.md @@ -14,9 +14,7 @@ Keywords: # Building a Hosted Agent with GitHub Copilot and Microsoft Foundry - - -https://youtu.be/pxG-9Lh_a44 + Low-code agents are great for proving behavior quickly, but most teams eventually need stronger control over code, deployment, and integration. In this chapter, we move into a code-first workflow and build a hosted agent that can be developed locally, debugged with tooling, and deployed into Microsoft Foundry. @@ -89,9 +87,18 @@ Here's what we need to think about first. Let's walk through the steps to scaffold a new agent project: 1. Open a terminal in your working folder. -2. Start GitHub Copilot CLI in that folder. -3. Enter a natural language prompt that describes the agent behavior, tools, and deployment intent. -4. Confirm generated files are created in the intended project location. +2. Start GitHub Copilot CLI in that folder. Run `copilot`. +3. Enable Autopilot mode (/autopilot on) so setup can run with fewer interruptions. +4. Confirm you see the message **Autopilot mode enabled with all permissions.** +5. Enter a natural language prompt that describes the agent behavior, tools, and deployment intent. + + Use this prompt from the example image: + + ```text + Create a Foundry agent solution for a developer social media campaign assistant promoting developer productivity tools. The agent should ask clarifying questions, use data retrieval tools to extract the right context for the campaign and generate social post options. The agent should be configured to use a Foundry toolbox, including the MS MCP Learn server to retrieve Microsoft official documentation and the web search tool to access fresh data. It should be deployable as a hosted agent. Use a gpt-5 model instance. Open project folder when done. + ``` + +6. Confirm generated files are created in the intended project location. See the example prompt below: