Build AI Agents in VS Code with Foundry Toolkit (2026 Guide)

TL;DR: Microsoft Foundry Toolkit for VS Code reached GA at Build 2026 (early June). Create agents from templates, debug locally with full trace visualization, connect to Toolboxes (managed tool endpoints, public preview), and deploy to Foundry Agent Service (hosted agents GA by early July 2026).

This guide walks the full loop in ~30 minutes.

Who Should Read This

• VS Code users who want to build agents without leaving their editor
• Teams evaluating agent platforms — compare Foundry vs. rolling your own
• Devs adding agent features to existing apps via Toolboxes + MCP
• Anyone prototyping — template → local run in 5 minutes, deploy in 30

What You’ll Learn

• Install Foundry Toolkit 1.0+ and authenticate with Azure
• Scaffold an agent from a template (Basic, Toolbox, Voice, Multi-Agent)
• Debug runs locally with the Trace View — model calls, tool invocations, memory reads
• Connect to Toolboxes for governed tool access (MCP, built-in, custom)
• Deploy to Foundry Agent Service for production sandboxed sessions

Prerequisites

Time to first local agent: ~15 minutes
Time to deployed agent: ~30 minutes (with Azure setup)

Quick self-check before starting:
– [ ] VS Code 1.90+ installed? → Help → About shows version
– [ ] GitHub Copilot subscription active? → Ctrl+Shift+P → "Copilot: Open Chat" works
– [ ] Azure free tier or paid subscription? → Portal shows subscription ID
– [ ] Ready to install extension? → Marketplace search works

Step 1: Install Foundry Toolkit (GA at Build 2026)

Goal: Get the GA extension installed and signed in.

1. Open VS Code → Extensions (Ctrl+Shift+X)
2. Search “Foundry Toolkit” (publisher: Microsoft)
3. Verify version shows 1.0.0 or higher — that’s the GA Build 2026 release
4. Click Install
5. Command Palette (Ctrl+Shift+P) → Foundry: Sign In
6. Authenticate with your Azure account (must match your Foundry project tenant)

[IMAGE: screenshot-step-1-foundry-toolkit-install]
Caption: Foundry Toolkit in VS Code Marketplace — GA badge confirms Build 2026 release — Source: VS Code Marketplace, June 2026

Expected result: Status bar shows “Foundry: Signed in as ” and Command Palette lists 8+ Foundry commands.

⚠️ Common mistake: Installing a pre-1.0.0 preview version from an old link.
Fix: Uninstall any “Foundry Toolkit (Preview)” first. GA is 1.0.0+.

Step 2: Create an Agent from a Template

Goal: Scaffold a working project in under 2 minutes.

1. Command Palette → Foundry: Create Agent

2. Choose a template:

3. Basic Agent — minimal harness, good for learning
4. Agent with Toolbox — pre-wired to a managed Toolbox endpoint
5. Voice Agent — includes Voice Live integration (GA)

6. Multi-Agent (Magentic-One) — orchestration pattern

7. Select Basic Agent for this walkthrough

8. Pick folder → project scaffolds with:

9. agent.py — your agent logic (inherits AgentBase)
10. foundry.yaml — declarative config (model, tools, memory, toolboxes)
11. requirements.txt — deps (microsoft-agent-framework, azure-ai-foundry)
12. .vscode/launch.json — debug config for Trace View

[IMAGE: screenshot-step-2-create-agent-template]
Caption: Template selection dialog in Foundry Toolkit 1.0 — four GA templates — Source: VS Code with Foundry Toolkit, June 2026

Expected result: Folder contains 4+ files; agent.py has a working on_message stub; Terminal shows “Foundry project created at “.

Step 3: Understand the Generated Project

Key files at a glance:

Generated foundry.yaml (trimmed):

project:
  name: "my-first-agent"
  runtime: "python"
agent:
  class: "agent.MyAgent"
  model:
    deployment: "gpt-4o"
    provider: "azure_openai"
  tools: []
  toolboxes: []
  memory:
    type: "session"

Concrete agent.py example — adds a web search tool:

from microsoft.agentframework import AgentBase, ToolboxClient

class MyAgent(AgentBase):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # Toolbox client configured via foundry.yaml
        self.toolbox = ToolboxClient()

    async def on_message(self, message: str) -> str:
        # Route to toolbox for web search if query needs current info
        if "search" in message.lower() or "latest" in message.lower():
            results = await self.toolbox.search_web(message)
            return f"Found: {results}"
        return f"You said: {message}"

This pattern — check intent → call toolbox → return result — is the core loop for any tool-using agent.

Step 4: Run & Debug Locally with Trace View

Goal: Execute the agent and see every reasoning step.

1. Open agent.py — starter on_message echoes input
2. Press F5 → selects “Foundry: Debug Agent”
3. Foundry Debug Console opens — type:
   "Hello, agent. What can you do?"
4. Watch the Trace View (side panel) — shows:
5. Model calls (prompt → response)
6. Tool invocations (if any)
7. Memory reads/writes
8. Latency per step

[IMAGE: screenshot-step-4-debug-trace-view]
Caption: Foundry Debug Console with Trace View — model call + response visible — Source: VS Code Foundry Toolkit 1.0, June 2026

Expected output in Trace View:

[Model Call] gpt-4o | Input: "Hello, agent..." | Output: "I'm a Foundry agent..."
[Latency] 1.2s
[Memory] Session: 1 message stored

Verification checklist for Step 4:
– [ ] Trace View opens automatically when debug starts
– [ ] Model call row appears with input/output preview
– [ ] Latency measured in seconds (not milliseconds)
– [ ] Session memory count increments per turn
– [ ] Second message shows conversation history in memory reads

⚠️ Debug console missing?
Ensure .vscode/launch.json has "type": "foundry" and you selected “Foundry: Debug Agent” from the debug dropdown.

Verification: Type a second message — Trace View should show conversation history in memory reads.

Step 5

Goal: Connect governed, reusable tool endpoints without writing tool code.

Toolboxes (public preview, Build 2026) are managed endpoints for built-in tools, MCP servers, custom skills, and enterprise data — with access control, rate limits, and audit built in.

Connect once, access everything.

Real-World Example: A fintech team connects their internal transaction API as a Toolbox MCP server. Agents can now query live transaction data, flag anomalies, and generate compliance reports — all governed by Azure RBAC policies.

1. Azure Portal → Foundry → Toolboxes → Create
2. Name it (e.g., “my-agent-tools”), pick region
3. Add tools:
4. Built-in: Web search, code execution, file ops
5. MCP: Any MCP server (GitHub, Slack, custom)
6. Custom: Your Python functions as tools
7. Copy the Toolbox endpoint URL (https://<name>.foundry.azure.com/toolbox/<id>)
8. In foundry.yaml, add:

agent:
  toolboxes:
    - endpoint: "https://my-agent-tools.foundry.azure.com/toolbox/abc123"
      auth:
        type: "managed_identity"

1. Restart debug (F5) — agent now has all Toolbox tools

[IMAGE: screenshot-step-5-toolbox-config]
Caption: Toolbox creation in Azure Portal + foundry.yaml config — Source: Azure Portal + VS Code, June 2026

Expected result: Toolbox shows “Healthy” status in Azure Portal; Trace View now lists Toolbox tools under “Available Tools”; agent can invoke search_web or run_code from the Toolbox.

Verification checklist for Step 5:
– [ ] Toolbox resource created in Azure Portal (same region as Foundry project)
– [ ] At least one tool added (built-in web search recommended for testing)
– [ ] Toolbox endpoint URL copied correctly (format: https://<name>.foundry.azure.com/toolbox/<id>)
– [ ] foundry.yaml updated with endpoint + auth.type: "managed_identity"
– [ ] Debug restart (F5) shows Toolbox tools under “Available Tools” in Trace View
– [ ] Test invocation: “Search for Foundry Agent Service pricing” → Trace View shows Toolbox search_web call + results

Mini walkthrough — real query end-to-end:

1. You type: “What’s the current price of Azure Container Apps in East US?”

2. Agent’s on_message detects “price” + “current” → routes to toolbox

3. Toolbox search_web executes with query

4. Trace View shows: Toolbox call → search results → model summarizes

5. You get: “As of June 2026, Azure Container Apps in East US starts at $0.000036/vCPU-second…”

This is the complete loop: user intent → toolbox tool → grounded result → cited answer.

Verification: Ask agent “Search for Foundry Agent Service pricing” — should trigger Toolbox web search tool and return results.

Why this matters: Toolboxes eliminate the #1 operational burden of custom agents — writing and maintaining tool wrappers. One governed endpoint gives you web search, code execution, file ops, MCP servers, and custom skills with audit trails built in.

Step 6

Goal: Persistent context across sessions.

In foundry.yaml:

agent:
  memory:
    type: "procedural"
    store: "foundry"

Procedural memory automatically extracts patterns from successful runs and re-applies them.

No code changes needed.

Real-World Example: A support agent learns that “refund requests for digital goods” always follow a 3-step verification pattern. After 50 successful runs, it auto-applies this pattern to new tickets — cutting handling time from 8 min to 2 min.

Verification checklist for Step 6:
– [ ] foundry.yaml has memory.type: "procedural" and memory.store: "foundry"
– [ ] Agent runs 10+ successful task completions in debug
– [ ] Trace View shows “Procedural Memory” entries being written
– [ ] Subsequent runs show pattern reuse (fewer model calls, faster completion)

Why this matters: Procedural memory is the difference between an agent that repeats the same mistakes and one that gets better over time. Microsoft reports +7–14% success rate gains — it’s free to enable and compounds with every run.

Step 7: Deploy to Foundry Agent Service (GA Early July 2026)

Goal: Production hosting with sandboxed sessions, state, and auto-scaling.

Prereqs: Azure subscription, Foundry resource, agent tested locally.

1. Command Palette → Foundry: Deploy Agent
2. Target: Foundry Agent Service
3. Select subscription + resource group
4. Configure:
5. Session isolation: Each user = dedicated sandbox (compute, memory, filesystem)
6. Protocol: Responses API (OpenAI-compatible) or Invocations protocol
7. Scaling: Auto-scale by concurrent sessions
8. Click Deploy → Output panel shows progress
9. On success you get:
10. Endpoint: https://<agent>.foundry.azure.com/agent/<id>
11. API Key: For client auth

[IMAGE: screenshot-step-7-deploy-dialog]
Caption: Deploy dialog in Foundry Toolkit — Foundry Agent Service target — Source: VS Code Foundry Toolkit 1.0, June 2026

Expected Output panel during deploy:

[Deploy] Starting deployment to Foundry Agent Service...
[Deploy] Provisioning Container Apps environment... done (45s)
[Deploy] Building container image... done (2m 12s)
[Deploy] Configuring session isolation... done
[Deploy] Agent endpoint ready: https://my-agent.foundry.azure.com/agent/abc123
[Deploy] API key generated: sk-foundry-**** (save this!)
[Deploy] Deployment complete in 3m 8s

Verification: Copy the endpoint + API key → run Step 8 test call immediately.

Verification checklist for Step 7:
– [ ] Deploy command completes without errors (watch Output panel)
– [ ] Endpoint URL returned follows format https://<agent>.foundry.azure.com/agent/<id>
– [ ] API key generated and saved securely
– [ ] Step 8 test call succeeds within 30 seconds

Why this matters: Foundry Agent Service is the first GA platform offering sandboxed per-session isolation — every user gets their own compute, memory, and filesystem. No container orchestration, no Kubernetes, no cold-start tuning. Just deploy and it scales.

Step 8: Call Your Deployed Agent

Python (Invocations protocol):

import requests

endpoint = "https://my-agent.foundry.azure.com/agent/abc123"
api_key = "your-api-key"

resp = requests.post(
    f"{endpoint}/invocations",
    headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
    json={"input": "Analyze this week's sales data and email me a summary"}
)
print(resp.json())

Expected Invocations response:

{
  "output": "Sales analysis complete. Total revenue: $247K (+12% WoW). Top product: Enterprise tier. Email sent to sales@company.com. Full report: https://blob.storage/report-2026-06-16.pdf",
  "trace_id": "tr-abc123",
  "session_id": "sess-xyz789"
}

OpenAI-compatible Responses API:

from openai import OpenAI

client = OpenAI(
    base_url="https://my-agent.foundry.azure.com/agent/abc123/v1",
    api_key="your-api-key"
)

response = client.responses.create(
    model="agent",
    input="Analyze this week's sales data and email me a summary"
)
print(response.output_text)

Expected Responses API output:

Sales analysis complete. Total revenue: $247K (+12% WoW). Top product: Enterprise tier. Email sent to sales@company.com. Full report: https://blob.storage/report-2026-06-16.pdf

Verification checklist for Step 8:
– [ ] Python requests call returns 200 OK with JSON containing output, trace_id, session_id
– [ ] OpenAI-compatible client returns text response matching expected format
– [ ] Response includes traceable trace_id for debugging
– [ ] Latency < 10 seconds for typical task

Community-Reported Metrics (Build 2026 Preview)

Multiple developers tested the Foundry Toolkit preview (March–June 2026). Here’s what the community measured:

Test environments: VS Code 1.90–1.92, Windows 11/macOS 14/Ubuntu 24.04, Azure Free Tier + Foundry preview.

Source: Community reports from GitHub microsoft/agent-framework discussions and Foundry Toolkit Marketplace reviews, March–June 2026.

Real-World Walkthrough: Fintech Team Automates Transaction Analysis

To make this concrete, here’s how a fintech team used Foundry Toolkit to build a transaction-analysis agent in 45 minutes:

Scenario: A 12-person fintech startup needed to flag anomalous transactions and generate compliance reports daily.

What they built:
1. Toolbox (2 min): Connected their internal PostgreSQL transaction DB as an MCP server + added web search for regulatory updates
2. Agent template (1 min): “Agent with Toolbox” → scaffolded agent.py + foundry.yaml
3. Custom logic (15 min): Added analyze_batch() method that queries last 24h transactions, checks against rules engine, calls web search for new FinCEN guidance
4. Procedural memory (30 sec): Enabled memory.type: "procedural" so the agent learns recurring anomaly patterns
5. Deploy (3 min): Foundry: Deploy Agent → Foundry Agent Service (preview)
6. Schedule (1 min): Added Routine (public preview) to run daily at 2 AM UTC

Result: What took a senior analyst 2 hours/day now runs autonomously. The agent catches 94% of flagged transactions that human review confirms, and surfaces novel patterns (e.g., “micro-structuring across 3 corridors”) the team hadn’t coded rules for.

Source: Anonymized case study shared in Microsoft Agent Framework discussions #312, May 2026.

Tool Comparison: Foundry vs. Alternatives

Bottom line: Foundry wins for governed enterprise agents needing managed tooling, sandboxing, and Azure identity. LangGraph wins for custom orchestration without platform lock-in. Copilot SDK wins for in-editor coding agents only.

Complete Workflow Diagram

[IMAGE: flowchart-foundry-agent-lifecycle]
Caption: Template → local debug → Toolbox → memory → deploy → client — Source: Original diagram based on Microsoft Foundry Build 2026 architecture

Troubleshooting

FAQ

Q: When does Foundry Agent Service reach GA?
A: Early July 2026 per Build 2026 announcement. Public preview available now.

Q: Can I use non-Azure models?
A: Yes — Fireworks AI is GA on Foundry, plus MAI models (Thinking, Image, Transcribe, Voice). Set model.provider in foundry.yaml.

Q: Does this work with LangGraph?
A: Yes — Hosted agents are framework-agnostic. Microsoft Agent Framework, GitHub Copilot SDK, LangGraph, or custom SDKs deploy without rewrites.

Q: What’s the pricing?
A: Pay for Azure Container Apps compute + Agent Service meter. No per-agent charge. Free tier includes dev sandbox.

Quick Checklist (Copy-Paste)

[ ] Foundry Toolkit 1.0+ installed in VS Code
[ ] Signed in with correct Azure tenant
[ ] Agent created from "Basic Agent" template
[ ] Local debug works (F5 → Trace View shows model calls)
[ ] Toolbox created in Azure Portal + endpoint in foundry.yaml
[ ] Memory type configured (session/user/procedural)
[ ] Deployed to Foundry Agent Service (early July 2026 GA)
[ ] Production endpoint responds to test invocation
[ ] Client integration tested (Python + Responses API)

Decision Framework — Choose Your Path

Bottom Line

Foundry Toolkit + Agent Service = the first GA platform for building, debugging, and hosting AI agents end-to-end. The template → local trace → Toolbox → deploy loop removes the infra burden. GA at Build 2026 means the APIs are stable — what you build today won’t break at GA.

Verdict: Should You Use It?

Start here: Install the extension, run the Basic Agent template, hit F5. You’ll have a traced agent run in 5 minutes.

Source List

1. Microsoft Foundry Build 2026 Announcement
   devblogs.microsoft.com/foundry/whats-new-in-microsoft-foundry-build-2026/
   Build 2026 (early June 2026), official GA/preview status matrix

2. Foundry Toolkit for VS Code
   marketplace.visualstudio.com/items?itemName=ms-azuretools.foundry-toolkit
   GA version 1.0.0+, commands, templates

3. Microsoft Agent Framework Stable Release
   github.com/microsoft/agent-framework
   Harness, skills, memory, middleware, Magentic-One orchestration

4. Foundry Agent Service Docs
   learn.microsoft.com/en-us/azure/ai-foundry/agent-service/
   Hosted agents, sandboxing, Responses/Invocations protocols, scaling

5. Toolboxes Public Preview
   learn.microsoft.com/en-us/azure/ai-foundry/toolboxes/
   Managed endpoints, MCP, governance

6. Voice Live GA
   learn.microsoft.com/en-us/azure/ai-services/speech-service/voice-live
   Real-time voice agents

Image Plan