Text of code.visualstudio.com › learn › foundry-toolkit-extension › 4-building-hosted-agent as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Building a Hosted Agent with GitHub Copilot and Microsoft Foundry

AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. 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. 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.

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. What You Will Learn 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. You will learn how to: 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. 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. 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. 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: Open a terminal in your working folder.

Start GitHub Copilot CLI in that folder. Run copilot . Enable Autopilot mode (/autopilot on) so setup can run with fewer interruptions. Confirm you see the message Autopilot mode enabled with all permissions. Enter a natural language prompt that describes the agent behavior, tools, and deployment intent. Use this prompt from the example image: 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.

Confirm generated files are created in the intended project location. See the example prompt below: Fig 01: GitHub Copilot CLI scaffold prompt and generated project output. 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. Step 2: Review What GitHub Copilot Generated Let's see what was generated. Here's what you should expect to see in the project folder: 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 3: Verify Creation and Setup of Tools Now that you saw what was scaffolded at high level, let's dive into the tools that were setup as part of the scaffold.

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. Here's what they will do for us: Web Search : Retrieve current web context for time-sensitive or trending information. Microsoft Learn MCP : Retrieve trusted product facts and documentation context. See below how these tools are configured: 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 expected clarifying-question behavior.

Run azd ai agent run from the project root. This command installs needed dependencies, starts the local runtime, and serves the agent as an HTTP service. Wait until the local runtime reports it is ready and then open a new terminal to invoke the agent. Run the agent in a separate terminal with azd ai agen

The rest of this page is on the live site.