Introduction

AgentCircuits is primarily a deployable platform, not just a library.

For most teams, the default path is:

1. Run the published server image or the bundled compose file.
2. Configure providers, authentication, storage, and routing.
3. Add custom tools and integrations.
4. Only drop into the NuGet packages when you need your own host or deep runtime customisation.

Two layers

AgentCircuits.Server

AgentCircuits.Server is the product surface most users should start with. It gives you:

• the admin portal at /portal
• the chat UI at /chat
• REST APIs and SignalR hubs
• file or PostgreSQL-backed persistence
• built-in provider registration
• configuration-based tool and skill loading

The runtime is designed to be container-friendly and is published as ghcr.io/agent-circuits/agentcircuits-server.

NuGet packages

The package surface is still important, but it is secondary to the hosted platform story:

• AgentCircuits.Server lets you create your own host around the same runtime.
• AgentCircuits.Core gives you direct control over agents, sessions, tools, hooks, and events.
• provider, storage, A2A, and channel packages are there when you need to compose a more opinionated host.

If you already know you need a custom ASP.NET Core application, use the packages. Otherwise, start with the platform runtime.

Tool model

AgentCircuits supports several extension paths:

• CLI tool directories, configured through AgentCircuits:Portal:CliToolDirs
• MCP servers attached to agents
• custom C# tools and services when you host with the NuGet packages
• skill directories for packaged instructions and helper scripts

That means you can ship a useful platform quickly in Docker and still keep a path open for deeper integration later.

Execution model

The underlying runtime still exposes the same execution model whether you run it in the platform or embed it yourself:

• SendAsync() followed by ReceiveAsync() when you want a streaming loop that runs to completion.
• SendAsync() followed by StepAsync() when you need turn-by-turn control for approvals, retries, or long-lived workflows.

Both patterns operate on the same underlying session and event model.

Runtime shape

At runtime the stack looks like this:

Docker image or custom host
        |
        v
Portal + Chat + APIs + SignalR
        |
        v
Agent runtime
        |
        v
Providers + Tools + Storage

Continue to Installation when you are ready to add packages.