[Plan] Consolidated Foundry + Copilot SDK Integration Strategy

[jongio]

Summary

Foundry-related skills are spread across multiple surfaces with no unified integration strategy. This issue consolidates findings from a code review of all Foundry-related code in this repo, the microsoft/skills repo, open issues, and cross-team discussions into an actionable plan.

The critical gap: There is no bridge between GitHub Copilot SDK applications and Foundry hosted agents. The azure-hosted-copilot-sdk skill deploys to Azure Container Apps, but cannot deploy as a Foundry hosted agent. The microsoft-foundry/create skill supports Agent Framework, LangGraph, and Custom frameworks — but not Copilot SDK.

Current State

Skills in This Repo

Skill	Status	Coverage
microsoft-foundry (9 sub-skills: create, deploy, invoke, troubleshoot, models/deploy-model, quota, rbac, resource/create, project/create)	✅ Merged (#865)	Full Foundry agent lifecycle + model deployment
azure-hosted-copilot-sdk (scaffold, deploy-existing, model-config, integrate)	✅ Merged (#880)	Copilot SDK → Azure Container Apps only
azure-aigateway	✅ Exists	APIM as AI Gateway, references Foundry
azure-prepare	✅ Exists	Foundry region-availability reference

MCP Servers (plugin/.mcp.json)

• foundry-mcp → https://mcp.ai.azure.com (Foundry MCP, HTTP remote)
• azure → @azure/mcp@latest

microsoft/skills Repo

• .github/skills/copilot-sdk/SKILL.md — 28KB monolithic SDK API reference (4 languages), no Azure hosting content
• .github/plugins/azure-skills/ — Plugin synced from this repo (18 sub-skills)
• No standalone Foundry skill in microsoft/skills

Related Open Issues

#	Title	Priority
#927	Convert foundry skill samples to use MS Learn MCP server	Medium
#929	Foundry MCP opens browser to authenticate unexpectedly	High (UX)
#935	Fix integration test report routing issues	High
#936	v1 to v2 migration support	Medium

Gaps Identified

1. No Copilot SDK → Foundry hosted agent path — azure-hosted-copilot-sdk explicitly says DO NOT USE FOR: Foundry agent hosting but doesn't route users to the right skill. microsoft-foundry/create doesn't list Copilot SDK as a supported framework.

2. Missing agentserver adapter for Copilot SDK — UPDATE: azure-ai-agentserver-copilot now exists on a fork branch by @tonybaloney (last commit Feb 22, 2026). This package wraps GitHub Copilot SDK sessions as Foundry hosted agents via from_copilot(), following the same pattern as from_langgraph() and from_agent_framework(). It includes:

   • RAPI ↔ Copilot SDK event translation (streaming + non-streaming)
   • YAML-based Tool Access Control List (ACL) for security gating
   • Session management for multi-turn conversations
   • OpenTelemetry tracing
   • BYOK support for Azure AI Foundry models
   • Two samples: basic_simple and hosted_agent (with Dockerfile, ACL, env config)
   • Thorough DESIGN.md and ARCHITECTURE.md documenting event mapping, RAPI limitations, and A2A comparison
   • Known issue: Platform streaming bug — Foundry + Container Apps ingress drops final SSE events (response.completed, [DONE]), affecting ALL hosted agent adapters. Non-streaming works.
   • Status: Fork branch, not yet in official azure-sdk-for-python or on PyPI. Needs validation, review, and upstream merge.

3. Agent Framework + Copilot SDK dependency conflicts — The Semantic Kernel blog post describes integration, but dependency issues have been reported when combining the two.

4. Bloated reference content — Per #927, reference files under microsoft-foundry contain content that could be retrieved dynamically from the MS Learn MCP server, violating the ≤1000 token reference file guideline.

5. Integration test routing inconsistency — Per #935, quota/documentation prompts are routed to azure-documentation or azure-quota instead of microsoft-foundry, causing 60% confidence on some tests.

6. Cross-repo SDK skill overlap — copilot-sdk in microsoft/skills (SDK API ref, 4 languages, ~7000 tokens) overlaps with azure-hosted-copilot-sdk here (Azure hosting, TS only, ~500 tokens). Comparison analysis at docs/spec/copilot-sdk-skill-comparison.md.

7. No v1→v2 migration — #936 tracks this. Current skills assume v2 SDK references. No detection logic for v1 codebases exists.

Proposed Plan

Guiding Principles

1. Foundry MCP First — Skills orchestrate workflows; Foundry MCP tools do the work
2. Clear Skill Boundaries — microsoft-foundry owns Foundry agent lifecycle; azure-hosted-copilot-sdk owns Copilot SDK → Azure hosting; a bridge handles the intersection
3. MS Learn MCP for Reference — Replace static reference content with dynamic MS Learn lookups
4. Don't Duplicate agentserver — Wait for redesign; build a thin routing bridge now

Phase 1: Fix Quality & Routing

Item	Description	Owner	Related
1.1 Fix integration test routing	Fix skill routing for quota/doc prompts bypassing microsoft-foundry. Improve trigger keywords, add negative triggers.	@tendau	#935
1.2 Slim references with MS Learn MCP	Audit agentframework.md and other reference files. Replace inline content with MS Learn MCP fetch instructions. Keep only workflow logic.	@tendau	#927
1.3 Address Foundry MCP auth UX	Document workaround for headless/CI environments. Add troubleshooting entry.	@tendau	#929

Phase 2: Copilot SDK ↔ Foundry Bridge

Key discovery: The azure-ai-agentserver-copilot adapter already exists (fork branch by @tonybaloney). This changes Phase 2 from "design from scratch" to "validate, adopt, and integrate."

Item	Description	Owner	Related
2.1a Add Foundry routing to azure-hosted-copilot-sdk	Add a row to Step 1 routing table: "Deploy as Foundry hosted agent → Delegate to microsoft-foundry/deploy". Currently the skill says "DO NOT USE FOR" but doesn't route.	@jongio	—
2.1b Add Copilot SDK entry to microsoft-foundry/create	Add Copilot SDK as a framework in foundry-agent/create/create.md using the azure-ai-agentserver-copilot adapter (from_copilot()). Include the hosted_agent sample as reference.	@tonybaloney / @tendau	—
2.2 Validate and upstream the adapter	Test azure-ai-agentserver-copilot end-to-end (local + Foundry hosted deploy). Validate streaming bug workarounds. Coordinate upstream merge to Azure/azure-sdk-for-python and PyPI publish.	@tonybaloney	—
2.3 Add Tool ACL documentation	The adapter introduces a YAML-based Tool ACL security layer for gating shell/read/write/URL/MCP tool invocations. Document ACL patterns in a reference file for the microsoft-foundry/create skill.	@tonybaloney / @tendau	—
2.4 Document Agent Framework + Copilot SDK integration	Create references/copilot-sdk-bridge.md documenting both paths: (a) direct via azure-ai-agentserver-copilot, (b) via Agent Framework per the SK blog post. Note known dependency issues and tradeoffs.	TBD	—
2.5 Address RAPI streaming platform bug	The adapter's ARCHITECTURE.md documents a platform bug where Foundry + Container Apps ingress drops final SSE events. This affects ALL adapters. Needs upstream Foundry platform fix.	Foundry platform team	—

Phase 3: v1 → v2 Migration

Item	Description	Owner	Related
3.1 Create microsoft-foundry/migrate/ sub-skill	Detection logic for v1 patterns, code migration mapping (SDK imports, API signatures), resource migration docs. Keep lightweight, point to official migration tool when available.	@tendau	#936

Phase 4: Cross-Repo Alignment

Item	Description	Owner	Related
4.1 Reconcile with microsoft/skills copilot-sdk	Remove SDK API overlap from azure-hosted-copilot-sdk. Add cross-references in both directions. Propose refactoring microsoft/skills to modular structure (currently 28KB/~7000 tokens vs 500-token guideline).	@jongio	—
4.2 Verify azure-skills plugin sync	Ensure microsoft-foundry is included in the synced plugin at microsoft/skills.	TBD	microsoft/skills#140

Phase 5: Testing

Item	Description	Owner	Related
5.1 Add Copilot SDK → Foundry routing tests	Integration tests for bridge scenario: "deploy my copilot sdk app as a foundry hosted agent". Fix existing per #935. ≥60% invocation rate.	@jongio	#935
5.2 Foundry MCP tool usage tests	Validate skills call MCP tools correctly. Test MS Learn MCP lookups return usable content.	@tendau	#927

Open Questions

These need team input before implementation proceeds on the affected phases.

Q1: azure-ai-agentserver-copilot adoption path (blocks Phase 2)

The Copilot SDK agentserver adapter already exists on @tonybaloney's fork. What's the path to production?

Options:

• A) Validate + adopt now — Test end-to-end, reference from skills immediately (pointing at fork), coordinate upstream merge in parallel
• B) Wait for upstream merge — Don't reference until it's in official Azure/azure-sdk-for-python and published to PyPI
• C) Fork into foundry-samples — Copy the hosted_agent sample into microsoft-foundry/foundry-samples for immediate use, track upstream merge separately

Recommendation: Option A — the adapter is functional and well-documented. Reference it now, upstream merge can happen in parallel. The hosted_agent sample already includes Dockerfile, ACL, and env config ready for Foundry deployment.

Q2: Agent Framework vs agentserver-copilot path (blocks Phase 2.4)

Now that azure-ai-agentserver-copilot exists as a direct adapter, should the Copilot SDK → Foundry path go through it directly, through Microsoft Agent Framework (via the SK integration), or both?

Options:

• A) agentserver-copilot only — Simpler, purpose-built, already has ACL + OTel + session management
• B) Agent Framework only — Promotes AF adoption, but has reported dependency conflicts and adds indirection
• C) Document both — Let users choose; agentserver-copilot for direct path, AF for users already in the AF ecosystem

Recommendation: Option C — document both paths with clear tradeoffs. agentserver-copilot is the simpler default.

Q3: v1 migration priority (blocks Phase 3)

Is #936 blocking users today, or can it wait for the official migration tool?

Needs input from: Foundry Agents team — are users hitting v1→v2 issues in the wild?

Q4: copilot-sdk sample in foundry-samples

The hosted_agent sample in azure-ai-agentserver-copilot is already Foundry-deployment-ready (Dockerfile, ACL, env config). Should this sample also be added to microsoft-foundry/foundry-samples alongside the existing Agent Framework and LangGraph samples?

Needs input from: @tonybaloney, Foundry Samples team

Dependencies & Blockers

Dependency	Status	Blocks
azure-ai-agentserver-copilot upstream merge + PyPI publish	Fork branch, not yet in official SDK	Phase 2.2 (production readiness)
agentserver redesign proposal	In flight	May affect adapter API surface
RAPI streaming platform bug (Foundry + ACA ingress drops final SSE events)	Documented in adapter, no workaround	Streaming mode for ALL hosted agents
Foundry invoke API changes	Coming	May require skill updates
Agent Framework + Copilot SDK dep resolution	Unknown	Phase 2.4 (AF path only)
Foundry MCP auth fix (#929)	Open	UX for all Foundry skills

Files Affected

File	Change	Phase
plugin/skills/microsoft-foundry/SKILL.md	Improve triggers, add routing	1.1
plugin/skills/microsoft-foundry/foundry-agent/create/references/agentframework.md	Slim down, add MS Learn MCP refs	1.2
plugin/skills/microsoft-foundry/foundry-agent/create/create.md	Add Copilot SDK framework entry	2.1
plugin/skills/azure-hosted-copilot-sdk/SKILL.md	Add Foundry routing in Step 1	2.1
plugin/skills/microsoft-foundry/foundry-agent/create/references/copilot-sdk-bridge.md	New — integration guide	2.2
plugin/skills/microsoft-foundry/migrate/migrate.md	New — v1→v2 migration sub-skill	3.1
docs/spec/copilot-sdk-skill-comparison.md	Update with decisions	4.1
tests/microsoft-foundry/foundry-agent/create/integration.test.ts	Add routing tests	5.1

---

References

Issues in this repo

• #927 — Convert foundry skill samples to use MS Learn MCP server
• #929 — Foundry MCP opens browser to authenticate unexpectedly
• #935 — Fix integration test report routing issues
• #936 — v1 to v2 migration support

PRs in this repo

• #865 — Skills to containerize, deploy and invoke hosted agents + Foundry MCP (merged)
• #880 — Add azure-hosted-copilot-sdk skill (merged)

Issues in microsoft/skills

• microsoft/skills#140 — Azure-Skills Plugin: Docs Site, README, and Distribution Strategy

Key files in this repo

• plugin/skills/microsoft-foundry/SKILL.md
• plugin/skills/azure-hosted-copilot-sdk/SKILL.md
• docs/spec/copilot-sdk-skill-comparison.md
• docs/spec/azure-hosted-copilot-sdk.md
• plugin/.mcp.json

External references

• azure-ai-agentserver-copilot — Copilot SDK adapter for Foundry Agent Server ⭐ Key discovery
• azure-ai-agentserver-copilot ARCHITECTURE.md
• azure-ai-agentserver-copilot DESIGN.md
• azure-ai-agentserver-copilot hosted_agent sample
• microsoft/skills — copilot-sdk skill
• microsoft/skills — azure-skills plugin
• microsoft-foundry/foundry-samples — hosted agents
• Build AI Agents with GitHub Copilot SDK and Microsoft Agent Framework (Semantic Kernel blog)
• Foundry Hosted Agents docs

/cc @kvenkatrajan @ankitbko @jongio @tonybaloney

[github-actions]

Thanks for putting together this thorough consolidated plan, @jongio! 🙏

This has been labeled enhancement since it outlines new capabilities and improvements, skills as it directly concerns the skills architecture in this repo, and requires-design because the cross-skill routing, Copilot SDK → Foundry hosted agent path, and agentserver adapter work involve architectural decisions that benefit from design review before implementation. Given that this is a high-level strategy and planning issue requiring human judgment on priorities and approach, it hasn't been assigned to a coding agent — individual work items that emerge from this plan can be tracked separately and assigned as appropriate.

Generated by Issue Triage for issue #1020