docs: Squad.Agents.AI + Microsoft Agent Framework integration guide #1565

Problem

Squad ships a Squad.Agents.AI NuGet (at src/Squad.Agents.AI/ in this repo) that exposes any Squad team as a Microsoft Agent Framework (MAF) AIAgent, enabling composition into durable .NET workflows with DTS checkpointing, Aspire dashboard observability, and multi-model mixing. This integration is documented by Tamir Dresher's blog post and 10-minute gist, and cross-posted on Microsoft devblogs — but the Squad docs site has no recipe, guide, or scenario covering it. There is also an active mandatory workaround (GitHub.Copilot.SDK direct reference) that users hit immediately and have no official guidance for.

Parent issue: #1564

What the Package Actually Does (Verified Against Source)

SquadAgent is a sealed class SquadAgent : DelegatingAIAgent, IAsyncDisposable (from Microsoft.Agents.AI). The inner agent is created via client.AsAIAgent(...) on a CopilotClient from the GitHub.Copilot namespace — there is no named GitHubCopilotAgent type or static factory. SessionConfig sets EnableConfigDiscovery = true so the CLI auto-loads .squad/ charters, skills, and MCP servers at session start. DI is handled via AddSquadAgent and AddKeyedSquadAgent extension methods.

Fact-check note: The Squad.Agents.AI source does not contain SerializeSessionAsync / DeserializeSessionAsync methods. DTS checkpoint/restore operates through MAF's base-class mechanisms. Docs should describe that behavior without attributing it to non-existent Squad-specific methods.

Scope

New page: docs/src/content/docs/guide/agent-framework-integration.md
or cookbook recipe: docs/src/content/docs/cookbook/recipe-squad-agents-ai.md + cross-link from recipes.md

Content required:

• Prerequisites: GitHub Copilot subscription, copilot --version check, .NET 8/9/10 SDK, initialized .squad/ folder
• Install: dotnet add package Squad.Agents.AI --prerelease (minimum v0.5.1 for observability + Aspire flow)
• Active workaround: Without a direct PackageReference to GitHub.Copilot.SDK, the SDK's MSBuild targets that copy copilot.exe into bin/ don't fire, causing a runtime crash: InvalidOperationException: Copilot runtime not found. The buildTransitive fix was merged in microsoft/agent-framework#6457 (2026-06-10) but has not shipped in a MAF NuGet preview yet. Until it does, the direct reference is mandatory.
• DI registration: AddSquadAgent and AddKeyedSquadAgent overloads; keyed and non-keyed can coexist for multi-team applications
• Basic prompt: RunAsync / RunStreamingAsync with working C# example
• Aspire dashboard observability: squad.subagent {Name} OTel spans; link to scenarios/aspire-dashboard.md
• Security callout: PermissionHandler.ApproveAll silently approves every permission request. It is appropriate for local dev or fully-trusted automated pipelines. It must not be used in public-facing or multi-tenant server deployments. Use a scoped handler that explicitly allows only the operations the workflow requires.
• Hosting notes: Copilot CLI runs as a subprocess — it must be co-located in the deployment environment. The MSBuild targets copy the correct RID binary at build time; verify the target RID matches the container OS/arch. For ACA/AKS: set GITHUB_COPILOT_CLI_PATH.
• Preview status callout on Squad.Agents.AI package
• Decision matrix: SDK programmatic vs CLI subprocess vs Agent Framework host — when to choose each

Acceptance Criteria

• Working C# "Hello World": register Squad agent via DI, send a turn, get response
• Mandatory GitHub.Copilot.SDK workaround documented and linked to microsoft/agent-framework#6457
• PermissionHandler.ApproveAll security warning present
• Telemetry section cross-links to Squad telemetry from embedded host processes (Agent Framework wrappers, no REPL): how should it reach Aspire? #1144 (or documents resolved outcome)
• Links to all source references below
• Preview banner on the page
• Aspire AppHost registration (Step 10 of Tamir's gist) covered inline or linked to scenarios/aspire-dashboard.md
• Does not mention non-existent SerializeSessionAsync/DeserializeSessionAsync methods
• Does not refer to a GitHubCopilotAgent type or static factory — use accurate client.AsAIAgent() description

Non-Goals

• Covering DTS/durable workflow design beyond Squad's role in it
• Documenting MAF providers other than the GitHub Copilot provider
• Replacing the MAF documentation on learn.microsoft.com

Source / Inspiration

Tamir Dresher published a verified, technically accurate blog post and companion gist demonstrating this integration. The pattern is co-authored with Brady Gaster. These are inspiration and citation sources — content must be summarized in Squad voice, not copied.

Relation to Existing Issues

• Squad telemetry from embedded host processes (Agent Framework wrappers, no REPL): how should it reach Aspire? #1144 — Companion (not duplicate). Squad telemetry from embedded host processes (Agent Framework wrappers, no REPL): how should it reach Aspire? #1144 = telemetry implementation; this issue = user-facing docs. Both should move together; cross-link both ways.
• Community contribution: Squad.Agents.AI - .NET adapter for Microsoft Agent Framework #1205 — Closed ("Community contribution: Squad.Agents.AI"). Not a duplicate; that issue tracked the PR; this issue tracks the missing docs page.
• docs milestone: real-world Squad hosting, integrations, and operations #1564 — Parent umbrella.

Priority

P0 — Active workaround + open companion issue + co-authored with Brady Gaster → highest visibility gap.