[bradygaster]

Summary

Adds the missing MAF integration guide at docs/src/content/docs/guide/agent-framework-integration.md.

Closes #1565

---

Revised by CONTROL (third independent revision) after FIDO rejection of CAPCOM's original and Handbook's revision. CAPCOM and Handbook are locked out for this cycle.

CONTROL revision notes (post-Handbook/FIDO cycle)

Three factual corrections applied — all grounded in source evidence:

1. 0.5.6-rc1+ → plain English in troubleshooting table

Problem: The troubleshooting table used Squad.Agents.AI 0.5.6-rc1+ as if + is a NuGet "or newer" operator. It is not — NuGet does not recognize + as a range operator; it is used only in build metadata (SemVer 2.0) and is ignored or rejected by the package manager.

Fix: Changed to Squad.Agents.AI version 0.5.6-rc1 or later (plain English, no version literal syntax).

Evidence: Copilot reviewer comment on line 236; NuGet SemVer spec.

---

2. Fabricated GITHUB_COPILOT_CLI_PATH env var removed; SquadAgentOptions.CliPath documented

Problem: The Hosting section stated "Set the GITHUB_COPILOT_CLI_PATH environment variable to the CLI binary path". No such environment variable exists in the source code or the GitHub.Copilot SDK.

Source evidence:

• src/Squad.Agents.AI/SquadAgentOptions.cs:28 — public string? CliPath { get; set; }
• src/Squad.Agents.AI/SquadAgent.cs:298-300 — if (!string.IsNullOrEmpty(options.CliPath) || combinedCliArgs.Count > 0) { clientOptions.Connection = RuntimeConnection.ForStdio(options.CliPath, combinedCliArgs); }

Fix: Removed GITHUB_COPILOT_CLI_PATH entirely. Replaced with accurate prose describing SquadAgentOptions.CliPath as a DI-time property, with a minimal compilable example:

builder.Services.AddSquadAgent(o =>
{
    o.SquadFolderPath = "/teams/main";
    o.CliPath = "/usr/local/bin/copilot"; // absolute path inside the container
});

---

3. Streaming snippet made self-contained

Problem: The streaming snippet used host without defining it, making it non-compilable if copied in isolation.

Fix: Added a single comment: // Assumes host is the IHost built in the DI registration step above. This explicitly cross-references the preceding host setup without duplicating the full build boilerplate.

---

Verified retained content

Claim	Evidence
Squad.Agents.AI version is 0.5.6-rc1	<Version>0.5.6-rc1</Version> in src/Squad.Agents.AI/Squad.Agents.AI.csproj line 31
buildTransitive bridge ships in that package	PackagePath="buildTransitive\Squad.Agents.AI.props" in csproj item group
PermissionHandler.ApproveAll is set by default	SquadAgent.cs line 132
SquadAgentOptions.CliPath is the correct DI-time property	SquadAgentOptions.cs:28, SquadAgent.cs:298-300
No nav changes	Only agent-framework-integration.md touched

Validation

• Docs build passes: 166 pages indexed
• CSpell: 0 issues in 0 files
• Page-local <!-- cspell:ignore nupkgs devblogs --> directive preserved (not in global cspell.json)

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit be33558

PR Scope: 🔧 Infrastructure

⚠️ 4 item(s) to address before review

Status	Check	Details
❌	Single commit	3 commits — consider squashing before review
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	No source files changed — changeset not required
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
❌	Copilot threads resolved	3 unresolved Copilot thread(s) — fix and resolve before merging
❌	CI passing	1 check(s) failing: docs-quality

Files Changed (1 file, +251 −0)

File	+/−
docs/src/content/docs/guide/agent-framework-integration.md	+251 −0

Total: +251 −0

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🟢 Impact Analysis — PR #1574

Risk tier: 🟢 LOW

📊 Summary

Metric	Count
Files changed	1
Files added	1
Files modified	0
Files deleted	0
Modules touched	1

🎯 Risk Factors

• 1 files changed (≤5 → LOW)
• 1 module(s) touched (≤1 → LOW)

📦 Modules Affected

docs (1 file)

• docs/src/content/docs/guide/agent-framework-integration.md

---

This report is generated automatically for every PR. See #733 for details.

[Copilot]

Pull request overview

Adds a new docs guide describing how to integrate Squad.Agents.AI with Microsoft Agent Framework (MAF) so a Squad team can be used as a .NET AIAgent, including DI registration, invocation, observability (Aspire/OpenTelemetry), security considerations, hosting notes, troubleshooting, and reference links.

Changes:

• New MAF integration guide page under docs/src/content/docs/guide/.
• Documents install + transitive GitHub.Copilot.SDK workaround context and upgrade guidance.
• Includes DI, invocation (sync + streaming), and Aspire tracing wiring examples.

Show a summary per file

File	Description
docs/src/content/docs/guide/agent-framework-integration.md	New integration guide for Squad.Agents.AI + MAF, including install/DI/examples/observability/security/troubleshooting.

Review details

Suppressed comments (2)

docs/src/content/docs/guide/agent-framework-integration.md:236

• 0.5.6-rc1+ isn’t a valid NuGet package version (the + suffix is not a usable “or newer” notation). Use explicit wording like “0.5.6-rc1 or later” instead.

| `InvalidOperationException: Copilot runtime not found` | Native CLI binary not in output; old package version | Upgrade to `Squad.Agents.AI 0.5.6-rc1+`; if still failing, add direct `GitHub.Copilot.SDK` reference |

docs/src/content/docs/guide/agent-framework-integration.md:127

• The streaming snippet has the same issue as the non-streaming example: host isn’t defined, so the snippet won’t compile if copied as-is. Make it standalone (or explicitly reference the earlier snippet) so it’s usable.

```csharp
var squad = host.Services.GetRequiredService<SquadAgent>();
var session = await squad.CreateSessionAsync();

await foreach (var update in squad.RunStreamingAsync("Summarize the team.", session))
{
    Console.Write(update.Text);
}
Console.WriteLine();

</details>


- **Files reviewed:** 1/1 changed files
- **Comments generated:** 4
- **Review effort level:** Lite