diff --git a/README.md b/README.md index b6614aa07..8f41f05f4 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,9 @@ **Human-led AI agent teams for any project.** One command. A team that helps you move faster with your code. -[![Status](https://img.shields.io/badge/status-alpha-blueviolet)](#status) [![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad) -> ⚠️ **Alpha Software** — Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in [CHANGELOG.md](CHANGELOG.md). +Breaking changes are documented in [CHANGELOG.md](CHANGELOG.md). --- @@ -96,9 +95,9 @@ Squad proposes a team — each member named from a persistent thematic cast. You --- -## .NET package preview +## .NET package -Building a .NET app that should call a Squad team as a Microsoft Agent Framework agent? `Squad.Agents.AI` is a preview NuGet package under [`src/Squad.Agents.AI`](src/Squad.Agents.AI/README.md). It registers a Squad-backed `AIAgent` in DI and targets early `0.1.0-preview` consumers. +Building a .NET app that should call a Squad team as a Microsoft Agent Framework agent? `Squad.Agents.AI` is a NuGet package under [`src/Squad.Agents.AI`](src/Squad.Agents.AI/README.md). Version **1.0.0** targets .NET 8, 9, and 10 and registers a Squad-backed `AIAgent` in DI. See the package README for installation and local validation before publication. ## Upgrading diff --git a/README.zh.md b/README.zh.md index e629eef2b..4020f2e78 100644 --- a/README.zh.md +++ b/README.zh.md @@ -4,10 +4,9 @@ **为任何项目打造的 AI 智能体团队。** 一行命令,拥有一个随代码同步成长的开发团队。 -[![状态](https://img.shields.io/badge/status-alpha-blueviolet)](#status) [![平台](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad) -> ⚠️ **Alpha 预览版** — Squad 仍处于实验阶段。API 和命令行工具可能在版本更迭中发生变化。我们会在 [CHANGELOG.md](CHANGELOG.md) 中记录重大变更。 +重大变更会记录在 [CHANGELOG.md](CHANGELOG.md) 中。 --- diff --git a/docs/src/content/docs/guide/agent-framework-integration.md b/docs/src/content/docs/guide/agent-framework-integration.md index c5d36ac7b..5782d2d29 100644 --- a/docs/src/content/docs/guide/agent-framework-integration.md +++ b/docs/src/content/docs/guide/agent-framework-integration.md @@ -3,7 +3,7 @@ title: "Microsoft Agent Framework integration" description: "Expose any Squad team as a MAF AIAgent for durable .NET workflows, Aspire dashboard observability, and multi-model composition." --- -> ⚠️ **Preview** — `Squad.Agents.AI` is a preview package. APIs may change before stable release. Use `--prerelease` when installing and pin to a specific version in production builds. +`Squad.Agents.AI` **1.0.0** is the stable package version for .NET 8, 9, and 10. Source versioning is separate from publication; until 1.0.0 is available on NuGet, follow the [local package instructions](https://github.com/bradygaster/squad/blob/dev/src/Squad.Agents.AI/README.md#install). `Squad.Agents.AI` exposes any Squad team as a Microsoft Agent Framework (MAF) `AIAgent`. Once registered, a `SquadAgent` participates in durable workflows alongside Azure OpenAI, Anthropic, and every other MAF provider — with DTS checkpointing, Aspire dashboard observability, and streaming out of the box. @@ -35,14 +35,14 @@ Authentication uses the signed-in GitHub Copilot CLI user by default. No separat ## Install ```bash -dotnet add package Squad.Agents.AI --prerelease +dotnet add package Squad.Agents.AI --version 1.0.0 ``` -Minimum version for Aspire dashboard observability: **0.5.1**. Current version: **0.5.6-rc1**. +Minimum version for Aspire dashboard observability: **0.5.1**. Stable package version: **1.0.0**. ### GitHub.Copilot.SDK direct reference — active workaround -`Squad.Agents.AI 0.5.6-rc1` ships a `buildTransitive/Squad.Agents.AI.props` that pins the correct `GitHub.Copilot.SDK` version for all consumers, so **most users do not need to add a direct reference**. If you are on an older version of `Squad.Agents.AI` and see: +`Squad.Agents.AI 1.0.0` ships a `buildTransitive/Squad.Agents.AI.props` that pins `GitHub.Copilot.SDK` 1.0.14 for all consumers, so **most users do not need to add a direct reference**. If you are on an older version of `Squad.Agents.AI` and see: ``` InvalidOperationException: Copilot runtime not found @@ -54,7 +54,7 @@ add the direct reference that was previously required: ``` -The root cause is that without a direct `PackageReference`, the SDK's MSBuild targets that copy `copilot.exe` into `bin/` do not fire for transitive consumers. The upstream fix is tracked in [microsoft/agent-framework#6457](https://github.com/microsoft/agent-framework/issues/6457). `Squad.Agents.AI 0.5.6-rc1` works around it independently via the generated `buildTransitive` bridge. +The root cause is that without a direct `PackageReference`, the SDK's MSBuild targets that copy `copilot.exe` into `bin/` do not fire for transitive consumers. The upstream fix is tracked in [microsoft/agent-framework#6457](https://github.com/microsoft/agent-framework/issues/6457). Since 0.5.6-rc1, `Squad.Agents.AI` works around it independently via the generated `buildTransitive` bridge. --- diff --git a/packages/squad-cli/README.md b/packages/squad-cli/README.md index 4bdf0187d..097387e0b 100644 --- a/packages/squad-cli/README.md +++ b/packages/squad-cli/README.md @@ -2,7 +2,7 @@ The programmable multi-agent CLI for GitHub Copilot. Build an AI team, assign roles, and let them work your repo—automating issue triage, code review, documentation, and more through orchestrated AI agents. -> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. +Breaking changes are documented in [CHANGELOG.md](https://github.com/bradygaster/squad/blob/main/CHANGELOG.md). ## Installation diff --git a/src/Squad.Agents.AI/README.md b/src/Squad.Agents.AI/README.md index 76ef2847e..737d72a37 100644 --- a/src/Squad.Agents.AI/README.md +++ b/src/Squad.Agents.AI/README.md @@ -1,12 +1,12 @@ # Squad.Agents.AI -> **Preview package.** `Squad.Agents.AI` is a preview NuGet package for early adopters. It multi-targets `net8.0`, `net9.0`, and `net10.0`, and depends on preview Microsoft Agent Framework / GitHub Copilot SDK packages, so APIs may change before a stable release. +`Squad.Agents.AI` **1.0.0** is the stable package version and multi-targets `net8.0`, `net9.0`, and `net10.0`. It uses Microsoft Agent Framework 1.23.0 and GitHub Copilot SDK 1.0.14. Source versioning does not confirm NuGet publication; use the local package instructions below until 1.0.0 is published. ## 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: +Public surface: - `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. @@ -18,23 +18,33 @@ Repository: ## Install ```bash -dotnet add package Squad.Agents.AI --prerelease +dotnet add package Squad.Agents.AI --version 1.0.0 ``` If you are consuming the PR before publish, pack it locally and add the generated package source: ```bash dotnet pack src/Squad.Agents.AI/Squad.Agents.AI.csproj -c Release -o nupkgs -dotnet add package Squad.Agents.AI --prerelease --source ./nupkgs +dotnet add package Squad.Agents.AI --version 1.0.0 --source ./nupkgs ``` ## Prerequisites -- .NET 10 SDK. +- .NET 8, 9, or 10 for consumers; .NET 10 SDK to build this repository and run the sample. - GitHub Copilot CLI available on `PATH` (`copilot --version`). - Squad CLI and an initialized Squad team root; see the [Squad CLI repo](https://github.com/bradygaster/squad). - GitHub Copilot authentication through the signed-in user. The quickstart below does not require an app key or environment variable. +For a bounded sample check without authentication, CLI startup, or model calls: + +```powershell +dotnet run --project src\Squad.Agents.AI\samples\Squad.Agents.AI.Sample -- --smoke +``` + +This checks default and keyed DI resolution and the client configuration callback. +The five live sample flows still require Copilot authentication and may consume credits; +the smoke check does not validate live responses or streaming. + ## Five-line quickstart ```csharp @@ -223,18 +233,18 @@ builder.Services.AddSquadAgent(o => - **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 +## Runtime notes - 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 targets .NET 8, 9, and 10 and includes OpenTelemetry activity support. - 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 +- `lib/net8.0/`, `lib/net9.0/`, and `lib/net10.0/`, each containing `Squad.Agents.AI.dll` and XML IntelliSense / API docs +- `buildTransitive/Squad.Agents.AI.props` for the pinned Copilot SDK native runtime bridge - `README.md` for NuGet.org rendering - `.nuspec` metadata with authors, tags, repository, and readme pointer - `LICENSE` copied from the repository root @@ -242,9 +252,9 @@ builder.Services.AddSquadAgent(o => ## Sample A runnable console application is included at -`src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/`. It demonstrates the four +`src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/`. It demonstrates the five core integration patterns in one place: basic DI, keyed DI with multiple agents, -the `ConfigureCopilotClient` BYOK delegate, and streaming via `RunStreamingAsync`. +the `ConfigureCopilotClient` delegate, streaming via `RunStreamingAsync`, and subagent OpenTelemetry observability. ### Prerequisites @@ -268,19 +278,20 @@ $env:SQUAD_TEAM_ROOT = "C:\path\to\your\team-root" ### Run -Run all four flows in sequence: +Run all five flows in sequence: ```bash dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ ``` -Run a single flow (1–4): +Run a single flow (1–5): ```bash 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 +dotnet run --project src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ -- --flow=5 ``` ### Flow walkthrough @@ -294,14 +305,19 @@ under keys `"alpha"` and `"beta"`. Resolution uses `GetRequiredKeyedService("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 +`CopilotClientOptions` after Squad has applied its defaults. The sample merges a custom +environment variable without overriding authentication, model, or session configuration. +Hosts can additionally inject a token from their credential store. The routing gate prevents accidental redirection of `Cwd`, `CliPath`, or `CliArgs` — configure those on `SquadAgentOptions` directly. **Flow 4 — Streaming** — `RunStreamingAsync` returns `IAsyncEnumerable`. Each `update.Text` fragment is written to `Console.Write` without a newline for live token-by-token output. +**Flow 5 — Subagent observability** — requests two specialist introductions and +prints dispatch callbacks and OpenTelemetry span counts. A response alone does +not prove that subagents were dispatched; inspect the captured events and spans. + ### Troubleshooting | Error | Cause | Fix | diff --git a/src/Squad.Agents.AI/Squad.Agents.AI.csproj b/src/Squad.Agents.AI/Squad.Agents.AI.csproj index 8d7293683..dec8fb6f4 100644 --- a/src/Squad.Agents.AI/Squad.Agents.AI.csproj +++ b/src/Squad.Agents.AI/Squad.Agents.AI.csproj @@ -18,24 +18,17 @@ README.md true - 0.5.6-rc1 + 1.0.0 - +