Squad.Agents.AI: .NET and Agent Framework Integration

Squad.Agents.AI is a preview NuGet package that exposes a Squad team as a Microsoft Agent Framework AIAgent. It wraps the Squad CLI through the GitHub Copilot SDK, delegates MAF sessions, runs, and streaming to the inner Copilot-backed agent, and gives .NET consumers a DI-friendly wrapper instead of hand-rolling CLI process setup. SquadAgent extends DelegatingAIAgent — so it fits naturally anywhere that AIAgent is expected, including Semantic Kernel pipelines and ASP.NET Core minimal API endpoints.

Squad.Agents.AI is a 0.1.0-preview package targeting net10.0. It depends on preview Microsoft Agent Framework and GitHub Copilot SDK packages. APIs may change before a stable release. The default DI lifetime is scoped, and multi-targeting is a candidate for a later preview.

Prerequisites

Prerequisite	Details
.NET 10 SDK	`dotnet --version` must print `10.x.x`
GitHub Copilot CLI on `PATH`	Install from github.com/github/copilot-cli; verify with `copilot --version`
Squad CLI and initialized team root	Follow the Squad install guide; run `squad init` in your team directory
GitHub authentication	Run `gh auth login` or `copilot auth login` once before starting the app

Installation

dotnet add package Squad.Agents.AI --prerelease

If you are consuming a local build before publish, pack the project and point the CLI at the output directory:

dotnet pack src/Squad.Agents.AI/Squad.Agents.AI.csproj -c Release -o nupkgs
dotnet add package Squad.Agents.AI --prerelease --source ./nupkgs

Five-line quickstart

using Microsoft.Agents.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Squad.Agents.AI;

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddSquadAgent(o =>
{
    o.SquadFolderPath = @"C:\path\to\your\team-root";
});

using var host = builder.Build();
var squad  = host.Services.GetRequiredService<AIAgent>();
var session  = await squad.CreateSessionAsync();
var response = await squad.RunAsync("What can this Squad team do?", session);
Console.WriteLine(response.Text);

AddSquadAgent registers both SquadAgent and the base AIAgent type in the service container so you can inject either in your application code.

Streaming

SquadAgent supports streaming via the MAF RunStreamingAsync method. Response fragments arrive as AgentResponseUpdate items the moment the CLI process emits them:

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);  // live, token-by-token output
}

Keyed DI

Register multiple Squad teams in the same DI container using .NET 8+ keyed services. Keyed and non-keyed registrations coexist without conflict.

AddSquadAgent (non-keyed)
AddKeyedSquadAgent

// Single team — resolve by base type
builder.Services.AddSquadAgent(o =>
{
    o.SquadFolderPath = @"C:\team";
});

// Resolution
var agent = host.Services.GetRequiredService<AIAgent>();

// Two teams — resolve by key
builder.Services.AddKeyedSquadAgent("research", o =>
{
    o.SquadFolderPath = @"C:\research-team";
});

builder.Services.AddKeyedSquadAgent("platform", o =>
{
    o.SquadFolderPath = @"C:\platform-team";
});

// Resolution in a minimal API endpoint
app.MapGet("/ask-research", async (
    [FromKeyedServices("research")] SquadAgent agent) =>
{
    var session  = await agent.CreateSessionAsync();
    var response = await agent.RunAsync("What's the latest?", session);
    return response.Text;
});

BYOK / ConfigureCopilotClient

Use the ConfigureCopilotClient delegate to customize the underlying CopilotClientOptions after Squad applies its standard values. This is the extension point for injecting a BYOK token from Key Vault, adding custom environment variables, or tuning SDK settings:

builder.Services.AddSquadAgent(o =>
{
    o.SquadFolderPath = @"C:\team";
    o.ConfigureCopilotClient = clientOpts =>
    {
        // Inject a BYOK token from your own credential store
        clientOpts.GitHubToken = myVault.GetSecret("copilot-token");

        // Add custom environment variables for the CLI process
        clientOpts.Environment = new Dictionary<string, string>
        {
            ["MY_CUSTOM_VAR"] = "value"
        };
    };
});

Routing guard: Squad enforces a hard routing gate inside the delegate. If the delegate changes Cwd, CliPath, or CliArgs, the original values are silently restored and a warning is logged. Configure those properties on SquadAgentOptions directly, not through ConfigureCopilotClient.

SquadAgentOptions reference

All configuration lives on SquadAgentOptions. Fields marked [JsonIgnore] are excluded from JSON serialization to prevent accidental credential leakage.

Option	Type	Default	Purpose
`SquadFolderPath`	`string?`	—	Required. Path to the initialized Squad team root. PATH connection strings set this and `Cwd`.
`CliPath`	`string?`	`PATH`	Override the Copilot CLI executable. When unset, the SDK resolves the default CLI from `PATH`.
`CliArgs`	`IList<string>`	`[]`	Additional CLI arguments appended when the process starts.
`Cwd`	`string?`	`SquadFolderPath`	Working directory for the CLI process. Defaults to `SquadFolderPath`.
`Environment`	`IDictionary<string, string?>`	`{}`	Additional environment variables for the CLI process. `[JsonIgnore]`; token-pattern keys are redacted in `ToString()`.
`GitHubToken`	`string?`	—	Direct token escape hatch. `[JsonIgnore]` and always shown as `[REDACTED]` in logs. Use `GitHubTokenProvider` for production.
`GitHubTokenProvider`	`Func<CancellationToken, ValueTask<string?>>?`	—	Async callback for secure token retrieval. Takes precedence over `GitHubToken`. `[JsonIgnore]`.
`ConfigureCopilotClient`	`Action<CopilotClientOptions>?`	—	Advanced delegate to customize `CopilotClientOptions`. Subject to routing guard. `[JsonIgnore]`.
`ConfigureSession`	`Action<SessionConfig>?`	—	Advanced delegate to customize the inner `SessionConfig` after Squad applies its defaults. `[JsonIgnore]`.
`TraceEvents`	`bool`	`false`	Enables verbose Copilot SDK logging. Emits a startup warning when enabled.
`AgentName`	`string`	`"Squad"`	Display name for the resulting `AIAgent`.
`AgentFileName`	`string?`	`"squad"`	Name of the agent definition under `.github/agents/{name}.agent.md` loaded via `--agent`. Set to `null` to skip auto-injection.
`Instructions`	`string?`	—	Optional system instructions appended to the inner Copilot agent’s system message.
`EmitSubagentActivities`	`bool`	`true`	Opens one OTel `Activity` per subagent dispatch with lifecycle events. Set to `false` to handle telemetry from `OnSubagentTrace` only.
`OnSubagentTrace`	`Action<SquadAgentTraceEvent>?`	—	Callback invoked for every subagent lifecycle event. Independent of `EmitSubagentActivities`. `[JsonIgnore]`.

Connection strings

AddSquadAgent() reads the connection string ConnectionStrings:squad through IConfiguration. In environment variables use ConnectionStrings__squad. Supported connection-string formats:

C:\path\to\team-root
squad://localhost?teamRoot=C%3A%5Cteam&cliPath=C%3A%5Ctools%5Ccopilot.exe&cliArgs=--yolo&env=KEY=value

Parsed URI query keys: teamRoot, cliPath, cwd, cliArgs (semicolon-separated), and env (key=value;key2=value2). Named registrations support two conventions:

Style	Example	Looks up
Aspire-style direct (tried first)	`AddSquadAgent("research-squad")`	`ConnectionStrings:research-squad`
Legacy prefixed fallback	`AddSquadAgent("research")`	`ConnectionStrings:squad-research`

When a .NET Aspire AppHost registers a Squad resource and a downstream project calls .WithReference(researchSquad), the consumer can resolve the agent with a single builder.Services.AddKeyedSquadAgent("research-squad") — the Aspire-injected connection string is found automatically.

OpenTelemetry

Squad.Agents.AI emits one OpenTelemetry Activity per subagent dispatch with no additional configuration. Wire it up in two lines:

using OpenTelemetry.Trace;
using Squad.Agents.AI;

builder.Services.AddOpenTelemetry()
    .WithTracing(t => t.AddSource(SquadAgentDiagnostics.ActivitySourceName));

builder.Services.AddSquadAgent(o => o.SquadFolderPath = @"C:\team");

Each subagent dispatch appears as a squad.subagent {Name} span tagged with:

squad.subagent.name — the agent’s identifier
squad.subagent.display_name — the agent’s display name
squad.subagent.sdk_agent_id — the Copilot SDK agent ID
squad.subagent.reply_preview — first 120 characters of the reply

Timeline events annotate every lifecycle phase: squad.subagent.start, squad.subagent.message, squad.subagent.completed, squad.subagent.failed. To handle observability yourself and suppress the built-in spans:

builder.Services.AddSquadAgent(o =>
{
    o.SquadFolderPath          = @"C:\team";
    o.EmitSubagentActivities   = false;   // disable built-in OTel spans
    o.OnSubagentTrace = trace =>          // handle telemetry yourself
    {
        if (trace.Kind == SquadAgentTraceEventKind.SubagentStarted)
            MyMetrics.IncrementSpawn(trace.SubagentName!);
    };
});

The OnSubagentTrace callback fires regardless of EmitSubagentActivities. Both can be active simultaneously — Squad’s built-in spans and your custom callback are independent.

Security

Squad.Agents.AI applies several protections by default:

Credential redaction

GitHubToken is always shown as [REDACTED] in ToString() output. Environment variable values whose keys contain TOKEN, KEY, SECRET, HMAC, PASSWORD, or CREDENTIAL are also redacted.

JSON safety

GitHubToken, GitHubTokenProvider, Environment, and ConfigureCopilotClient are all marked [JsonIgnore] and will never appear in JSON serialization output.

Routing guard

The ConfigureCopilotClient delegate cannot change Cwd, CliPath, or CliArgs. Any changes are silently restored to prevent routing the agent to an unintended CLI process.

TraceEvents warning

Enabling TraceEvents emits a startup warning because verbose SDK traces may include sensitive operational details. Keep it disabled in production.

No hardcoded tokens

Never embed tokens in source code. Use GitHubTokenProvider with a secure store (Key Vault, managed identity, or a CI secret flow) for production token retrieval.

What’s next

SDK Overview

Explore all @bradygaster/squad-sdk exports — state backends, casting engine, and cross-squad coordination.

Observability Guide

Connect Squad’s OpenTelemetry spans to Aspire, Jaeger, Zipkin, or Application Insights.

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Squad.Agents.AI: .NET and Agent Framework Integration

Prerequisites

Installation

Five-line quickstart

Streaming

Keyed DI

BYOK / ConfigureCopilotClient

SquadAgentOptions reference

Connection strings

OpenTelemetry

Security

What’s next

SDK Overview

Observability Guide

Build docs developers (and LLMs) love

Get Started

CLI Reference

Guides

SDK

Samples & Examples

Documentation Index

​Prerequisites

​Installation

​Five-line quickstart

​Streaming

​Keyed DI

​BYOK / ConfigureCopilotClient

​SquadAgentOptions reference

​Connection strings

​OpenTelemetry

​Security

​What’s next

SDK Overview

Observability Guide

Build docs developers (and LLMs) love

Prerequisites

Installation

Five-line quickstart

Streaming

Keyed DI

BYOK / ConfigureCopilotClient

SquadAgentOptions reference

Connection strings

OpenTelemetry

Security

What’s next