Create and deploy a hosted agent in Foundry Toolkit for VS Code
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. Create and deploy a hosted agent in Foundry Toolkit for VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders Hosted agents run your agent code in Microsoft Foundry Agent Service.
Choose a hosted agent when you need custom logic, code-based orchestration, or control over dependencies that a prompt-agent definition doesn't provide. You maintain and test the code and its dependencies. Foundry manages the hosting infrastructure and scaling. For a comparison with prompt agents, see Choose an agent type . In this article, you use Foundry Toolkit for Visual Studio Code to create a Python Agent Framework sample, test it locally with Agent Inspector , and deploy its source code to Foundry.
The sample uses the Responses protocol for conversational requests. After deployment, you test the remote agent and inspect its status, versions, and logs. Prerequisites For the Python walkthrough, prepare: Visual Studio Code with the current public Foundry Toolkit extension. See Install Foundry Toolkit . Python 3.13 and the Python extension , including Python debugger support. Use a Python environment for the sample's dependencies.
An Azure subscription and a Foundry project in a region that supports hosted agents. A deployed Foundry model compatible with the sample's chat client. The basic sample is configured for gpt-5.4-mini , so use an existing deployment of that model for this walkthrough. See Deploy a model to Microsoft Foundry . Other samples can have different model requirements. The Azure CLI for local authentication, and permission to deploy to the project.
The hosted-agent permissions reference explains deployment, registry, and runtime permissions. The main source-code deployment path doesn't require a local Docker build. Container images and Activity Protocol samples have additional requirements, described in their branches below. GitHub Copilot is optional for the project validation step. Create a new hosted agent Create a local project from a sample before changing its behavior.
This gives you agent code, dependency declarations, and a deployment configuration that you can keep in source control. For a comparison of samples, Agent Builder, and Copilot-assisted coding, see Choose a creation route . Select Foundry Toolkit in the Activity Bar. Under Developer Tools > Build , select Create Agent . Under Code an agent from samples , choose one of three hello-world starters: Agent Framework , Copilot SDK , or LangGraph .
For this walkthrough, select Agent Framework to open the Create tab with the basic Responses sample selected. To explore more options, select Browse all samples instead. In Create Hosted Agent from Sample , search or filter by Language , Framework , and Protocol Type . To follow this walkthrough from the gallery, select the Python Agent Framework Basic Hosted Agent sample, then select Next . The catalog can refresh independently of the extension.
If the sample is labeled Basic , select the Agent Framework Responses sample for basic requests and multi-turn conversations. On the Create tab, select Workspace Folder . If the selected folder already contains files, enter a Folder Name for a new child folder. Review the destination shown in the form. If Environment Setup is shown, select Setup with Microsoft Foundry , then select your subscription and project. When a default project is already selected in the Toolkit, the form uses that project.
Select an existing compatible Model Deployment . For this walkthrough, reuse the model prepared in the prerequisites. Skip for now lets you generate code without finishing model setup. You must complete the model configuration before running the agent. Selecting Deploy & use new model , when offered, provisions a model deployment, not the hosted agent. The following screenshot shows example settings with local paths redacted.
Use your own destination and the model deployment prepared for this walkthrough. Select Create and open the generated project's README.md . The Toolkit can reuse the current window or open another window, depending on the destination and open workspace. For this sample, keep the folder that contains azure.yaml open as the workspace root. The generated project separates deployment settings from agent source: Artifact Purpose azure.yaml Declares the hosted-agent service, source directory, runtime, protocols, and deployment configuration. src/agent-framework-agent-basic-responses/main.py Implements the agent and starts its Responses server. requirements.txt and .env in that source directory Declare Python dependencies and local project and model configuration.
The Toolkit creates .env from the sample's .env.example . .vscode/launch.json and .vscode/tasks.json Configure local launch, debugger attachment, and Agent Inspector. Creating these files is not cloud deployment. Other samples can have different layouts. Use their README.md and the service's project path in azure.yaml to locate the source. Choose another protocol or sample The sample gallery also offers other frameworks, C#, and custom-code starting points.
Filters show compatible sample combinations, not a promise that every framework supports every protocol. Selecting a sample chooses an implementation. Changing a protocol name in a configuration file doesn't add that protocol to your server. Use the following table to decide when to take a different path. See Hosted-agent protocols for the service contracts. Protocol Use it for Local testing Responses Conversational requests, streaming responses, and multi-turn interactions.
Use Agent Inspector with the running Responses server. This is the walkthrough's path. Invocations Custom JSON payloads, webhooks, or non-conversational processing. Use the HTTP Invocations view in Agent Inspector with the sample's request format. Invocations (WebSocket) Bidirectional streaming, such as real-time voice. Use the sample's WebSocket client. The HTTP Invocations view isn't a WebSocket client. Activity Agents that handle Microsoft 365 or Teams activities.
Python Activity scaffolds use Microsoft 365 Agents Playground. Follow the sample's platform and tool prerequisites. For C#, install the SDK and debugger required by the selected sample and use its generated launch configuration. See C# debugging for debugger controls and configuration. A Toolbox-connected sample also needs tool configuration and runtime access. Follow Tool Catalog setup rather than treating model setup as tool authentication.
Run and test locally Test the basic agent before adding custom behavior or deploying it. Its server runs on your computer, but model requests go to the configured Foundry deployment and can incur charges. The steps below use this sample's generated configuration. For the shared playground and inspection controls, see Use the Inspector . In the generated workspace, use Python: Create Environment or Python: Select Interpreter to select a Python 3.13 environment.
See Create environments or Select an environment for setup details. Open a terminal with that environment active. Change to the sample's source directory, src/agent-framework-agent-basic-responses , and install its dependencies: python -m pip install -r requirements.txt The sample includes debugpy for debugging. Check the source directory's .env . Set FOUNDRY_PROJECT_ENDPOINT to your project endpoint and AZURE_AI_MODEL_DEPLOYMENT_NAME to the compatible deployment name if setup didn't fill them in.
Sign in for the local agent's Azure credentials: az login In Run and Debug , select Debug Local Agent HTTP Server and press F5 . Keep the generated workspace root open. The tasks start the server on port 8088, open Agent Inspector, and attach the debugger. Send a message such as Sug
The rest of this page is on the live site.