Squad.Agents.AI 0.5.1-preview.8

Squad.Agents.AI

Preview package. Squad.Agents.AI is a 0.1.0-preview NuGet package for early adopters. It targets net10.0 and depends on preview Microsoft Agent Framework / GitHub Copilot SDK packages, so APIs may change before a stable release.

What it does

Squad.Agents.AI exposes a Squad team as a Microsoft Agent Framework AIAgent. SquadAgent composes the Squad CLI through the GitHub Copilot SDK, delegates MAF sessions/runs/streaming to the inner Copilot agent, and gives .NET consumers a DI-friendly wrapper instead of hand-rolling CLI process setup.

Public surface in this preview:

• SquadAgent — sealed AIAgent wrapper over the Copilot-backed inner agent. Supports both non-streaming and streaming via RunStreamingAsync.
• SquadAgentOptions — team root, CLI path/args, environment, token, logging, instruction settings, and a ConfigureCopilotClient delegate for advanced SDK customization.
• SquadConnectionFactory — parses PATH or squad:// connection strings into options.
• SquadServiceCollectionExtensions — registers SquadAgent and base AIAgent in DI, with standard and keyed overloads.

Repository: https://github.com/bradygaster/squad

Install

dotnet add package Squad.Agents.AI --prerelease

If you are consuming the PR before publish, pack it locally and add the generated package source:

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

Prerequisites

• .NET 10 SDK.
• GitHub Copilot CLI available on PATH (copilot --version).
• Squad CLI and an initialized Squad team root; see the Squad CLI repo.
• GitHub Copilot authentication through the signed-in user. The quickstart below does not require an app key or environment variable.

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);

Streaming

SquadAgent supports streaming via the MAF RunStreamingAsync method. The inner Copilot-backed agent streams response updates as they arrive from the CLI process:

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);
}

Keyed DI

Register multiple Squad teams in the same DI container using .NET 8+ keyed services:

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

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

// Resolve 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;
});

Keyed registrations include AddKeyedSquadAgent overloads for service key, optional connection-string name, and lifetime. Keyed and non-keyed registrations can coexist.

Advanced: ConfigureCopilotClient (BYOK)

Use ConfigureCopilotClient to customize the underlying CopilotClientOptions after Squad applies its standard values. This is the extension point for injecting custom environment variables, providing a BYOK token, 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 — if the delegate changes Cwd, CliPath, or CliArgs, the original values are restored and a warning is logged. Configure these via SquadAgentOptions instead.

GitHub Copilot authentication

The default path mirrors the base GitHub Copilot SDK examples: leave GitHubToken and GitHubTokenProvider unset, then run with a locally signed-in GitHub Copilot user. For local development, sign in before running the app, for example with gh auth login, the Copilot CLI sign-in flow, or a Copilot-supported local sign-in that the SDK runtime can access.

The SDK documents the credential priority order in Authenticate Copilot SDK and the broader authentication overview. Explicit tokens and environment variables are supported by the SDK, but they are not required for the minimal happy path.

Use GitHubTokenProvider only when the host owns token retrieval, such as Key Vault, managed identity, or CI secret flow scenarios. Use GitHubToken only when you already have a Copilot-supported token in process and cannot use a provider callback. Use ConfigureCopilotClient when you need full control over the SDK's CopilotClientOptions, including BYOK token injection.

Aspire / configuration path

AddSquadAgent() reads ConnectionStrings:squad through IConfiguration.GetConnectionString("squad"). In environment variables, use ConnectionStrings__squad.

Named registrations support both connection-string conventions:

So when an Aspire AppHost registers a Squad resource via builder.AddSquad("research-squad", ...) and a downstream project does .WithReference(researchSquad), the consumer can resolve the agent with a single builder.Services.AddKeyedSquadAgent("research-squad") call — the SDK finds the Aspire-injected connection string automatically. Existing consumers using the prefixed form continue to work; the SDK tries the literal name first and falls back to squad-{name} if the direct lookup is empty.

Supported connection string forms:

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). Unknown URI host/protocol values are reserved for future use.

Coordinator agent selection

SquadAgent exists to wrap a Squad coordinator team, so it passes --agent squad to the underlying copilot.exe child process by default. That tells the CLI to load .github/agents/squad.agent.md as the agent definition — which is what teaches the coordinator to eager-execute, fan out, and dispatch through the task tool. Without it, the CLI uses its built-in generic agent and the coordinator role-plays responses inline instead of spawning real subagents — producing SDK behavior that does NOT match running copilot --agent squad interactively against the same team root.

SDK note: SessionConfigBase.Agent exists but looks up the name in the SDK's CustomAgents registry, NOT in .github/agents/*.agent.md files on disk. The CLI --agent flag is currently the only path that reads the on-disk agent definition.

Subagent observability — first-class OpenTelemetry

Squad.Agents.AI emits one OpenTelemetry Activity per subagent dispatch out of the box. Hosts that subscribe to the activity source see one squad.subagent {Name} span per spawn, with the subagent name as a tag and timeline annotations (squad.subagent.start, squad.subagent.message, squad.subagent.completed, squad.subagent.failed) marking every state transition.

Two-line wiring is all that is required — no manual callback plumbing:

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

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

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

When the coordinator's task tool spawns specialists, the host's tracer (Jaeger, Zipkin, Application Insights, or the Aspire dashboard's Traces view) shows one squad.subagent span per spawn, each tagged with squad.subagent.name, squad.subagent.display_name, squad.subagent.sdk_agent_id, and squad.subagent.reply_preview — plus timeline events for every lifecycle transition.

Turning telemetry off. Set EmitSubagentActivities = false to suppress Squad's built-in spans (for example, when you want to drive observability entirely from your own callback or avoid double-counting). The OnSubagentTrace callback continues to fire either way — it is the customization seam, independent of telemetry.

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

Key options

Security

• Credential redaction: GitHubToken and Environment values whose keys match *TOKEN*, *KEY*, *SECRET*, *HMAC*, *PASSWORD*, or *CREDENTIAL* are always redacted in ToString() output.
• JSON safety: GitHubToken, GitHubTokenProvider, Environment, and ConfigureCopilotClient are marked [JsonIgnore] and will not appear in JSON serialization output.
• Routing guard: The ConfigureCopilotClient delegate cannot change Cwd, CliPath, or CliArgs — changes are silently restored to prevent routing the agent to an unintended CLI process.
• TraceEvents warning: Enabling TraceEvents logs a startup warning because verbose SDK traces may include sensitive operational details.
• Avoid hardcoded tokens: Never embed tokens in source code. Use GitHubTokenProvider for production token retrieval from Key Vault, managed identity, or similar secure stores.

Notes for v0.1-preview

• Default DI lifetime is scoped. An overload accepts any ServiceLifetime.
• DI registers both SquadAgent and base AIAgent (non-keyed). Keyed DI registers both SquadAgent and AIAgent under the same key.
• Multi-targeting and Aspire telemetry remain candidates for a later preview.
• The package does not validate that SquadFolderPath exists; consumers should validate their deployment paths.
• TraceEvents can log sensitive operational details. Keep it off unless debugging.

Package contents

• lib/net10.0/Squad.Agents.AI.dll
• lib/net10.0/Squad.Agents.AI.xml for IntelliSense / API docs
• README.md for NuGet.org rendering
• .nuspec metadata with authors, tags, repository, and readme pointer
• LICENSE copied from the repository root

Sample

A runnable console application is included at src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/. It demonstrates the four core integration patterns in one place: basic DI, keyed DI with multiple agents, the ConfigureCopilotClient BYOK delegate, and streaming via RunStreamingAsync.

Prerequisites

Set the team root path before running:

# Linux / macOS
export SQUAD_TEAM_ROOT=/path/to/your/team-root

# Windows PowerShell
$env:SQUAD_TEAM_ROOT = "C:\path\to\your\team-root"

Run

Run all four flows in sequence:

dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/

Run a single flow (1–4):

dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=1
dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=2
dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=3
dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=4

Flow walkthrough

Flow 1 — Basic DI registration — AddSquadAgent registers SquadAgent and the base AIAgent interface. Resolves the agent from DI, creates a session, calls RunAsync, and prints AgentResponse.Text.

Flow 2 — Keyed DI (multiple agents) — AddKeyedSquadAgent registers two agents under keys "alpha" and "beta". Resolution uses GetRequiredKeyedService<SquadAgent>("alpha").

Flow 3 — BYOK / ConfigureCopilotClient delegate — the delegate receives CopilotClientOptions after Squad has applied its defaults. Inject a custom token or environment variable. The routing gate prevents accidental redirection of Cwd, CliPath, or CliArgs — configure those on SquadAgentOptions directly.

Flow 4 — Streaming — RunStreamingAsync returns IAsyncEnumerable<AgentResponseUpdate>. Each update.Text fragment is written to Console.Write without a newline for live token-by-token output.

Troubleshooting

See also

• Root repo: https://github.com/bradygaster/squad
• Microsoft Agent Framework: https://github.com/microsoft/agents
• GitHub Copilot SDK authentication: https://github.com/github/copilot-sdk/blob/main/docs/auth/authenticate.md
• GitHub Copilot CLI: https://github.com/github/copilot-cli
• Changelog: https://github.com/bradygaster/squad/blob/main/CHANGELOG.md

License: MIT.