Development on AGW

Development setup

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisites: .NET 10 SDK, Node.js 24, pnpm 12.5.1 (pinned by packageManager in src/clients/package.json), and Git. Docker Buildx is needed only for container images. These application commands run in the AGW repository; the documentation site does not depend on this toolchain.

Backend

git clone https://github.com/zxyao145/agw.git
cd agw
git config core.hooksPath .githooks
dotnet restore Agw.slnx
dotnet tool restore
dotnet run --project src/server/Agw.Standalone.Host

Initialize at http://localhost:30816/setup. Replace dotnet run with dotnet watch for hot reload.

Architecture and module boundaries

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisite: a working source setup. Identify the business owner of a use case before tracing cross-module capabilities through Contracts.

Backend organization

AGW is a modular monolith. Agw.Host supplies shared hosting; Control Plane, Data Plane, and Standalone compose the modules they need. Business modules follow Api → Application → Domain ← Infrastructure, creating only necessary layers.

flowchart LR
 API[Api] --> APP[Application]
 APP --> DOMAIN[Domain]
 INFRA[Infrastructure] --> DOMAIN

Layer	Responsibility	What to inspect
Api	Receive requests and return responses	Routes, inputs, and outputs
Application	Complete a business operation	Authorization, queries, transactions, and call order
Domain	Hold business data and express rules	Entities, Behaviors, and DomainServices
Infrastructure	Connect databases and external systems	Persistence and concrete adapters

Domain entities hold state. A Behavior handles rules within one Aggregate, while a DomainService handles rules that need facts beyond it. Application loads data, coordinates these calls, and persists changes. Ordinary CRUD stays in Application without creating a Behavior for every entity.

APIs and execution protocols

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisites: access to a development Server and a valid authenticated identity, such as an API Key or a browser session. Use current OpenAPI and owning-module Contracts for exact fields; this site does not duplicate the complete schema.

Protocol boundaries

Interface	Purpose and contract
Management JSON APIs	Bens.Results `ApiResult` envelopes, unwrapped by typed client helpers
`/api/hubs/exec`	SignalR execution commands, state, and events; mapped by Data Plane and Standalone only and accepts only the WebSocket transport. The official client connects with `skipNegotiation: true`
`/api/agents/permission-capabilities`	Query supported permissions for a target
`/api/auth/oidc/providers`	Enabled sign-in providers, used to render the sign-in buttons
`/api/auth/oidc/login`	Redirects to the provider; `client` is `web` or `desktop`
`/api/auth/desktop/exchange`	Desktop exchanges a one-time code plus its verifier for an API Key
A2A	Protocol-specific responses, mapped by Data Plane and Standalone only
`/openapi/*`	Contract entry point; served, together with the Scalar API reference, only in the Development environment by Control Plane or Standalone

Sign-in routes are served by Control Plane and Standalone. An API Key obtained by Desktop behaves like a manually created one and accesses resources as its creator.

Extend tools and integrations

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisites: understand module boundaries and decide whether the capability is general-purpose or business-owned. Begin with one small, verifiable capability.

Tool extension path

Put hand-written IAgwTool, IContextualTool, and IToolBlock implementations in Agw.Tools; the global catalog scans only that assembly for hand-written tools. Business tools belong in their module’s Application/Tools, declared as attributed containers or supplied through a Skill, with DTOs in Contracts/Tools.
Reference Agw.Tools.Abstractions; add Agw.Tools.Generators as an Analyzer for attributed declarations.
Explicitly declare permissions, argument descriptions, and return types. Standalone tools and attributed containers stay stateless; session state belongs in a Provider, session, or owned storage.
Register services and generated declarations in the owning module. Choose Skill exposure or explicit global catalog inclusion.
Verify discovery, arguments, permissions, project binding, and error mapping.

The generator emits metadata, JSON Schema, and direct invocation delegates. Do not add runtime reflection scanning as a fallback. Skill tools come from two members: IAgentSkillRegistration.Tools supplies hand-written IProjectScopedAgwTool instances, and ToolTypes supplies attributed container types generated through IAgwToolSet<T>. They bind to a Project during execution. Registering a generated module does not automatically expose every tool globally.

Testing and contribution

Fri, 25 Sep 2026 00:00:00 +0000

Prerequisite: dependencies are installed. Read root AGENTS.md and the relevant rules under docs/human/ before changes, and preserve unrelated local work.

Backend checks

From the repository root:

dotnet build Agw.slnx
dotnet test Agw.slnx
dotnet csharpier check .

Test projects use xUnit v3 and run on Microsoft.Testing.Platform, selected by the root global.json. Start with relevant tests when investigating a failure, such as dotnet test tests/Agw.Files.Tests. Unit and composition tests use real implementations and pure option helpers, never mocks or fake implementations. Constructing CodexAIAgent or ClaudeCodeAIAgent probes the CLI, so those tests run as real CLI tests: they are opt-in, require the executable, and stay out of the default suite.