Agentic Lab

Agentic Lab was created to demystify agentic AI and show how it works. It brings together two complementary parts:

1. Learn how agentic AI works. Guided lessons and simple explanations introduce agents, models, tools and context.
2. See it happen in Live Flow. Run an agent and watch the steps between your question and its answer: what the model receives, which tools it asks to use, and what comes back.

Warning

This is an educational sample, not a production-ready agent platform. Use a trusted local development environment. Before shared or public deployment, add authentication, authorization, sandboxing, network/tool policy, resource limits, and a reviewed data-retention policy. Read SECURITY.md before using real credentials or workspace data.

Project Status

Agentic Lab is actively evolving. APIs, UI details, and configuration may change between versions. Security fixes target the latest main branch; older releases have no separate support commitment.

1. Learn How Agentic AI Works

The Learn experience explains the building blocks of an agent through guided lessons on models, tools and context. Start with the core idea:

Agent = Agent host + Model. The model chooses the next step. The agent host is the code around it that supplies context, manages tools and controls execution.

1. You ask a question.
2. The host sends the model your question, instructions, context and available tools.
3. The model returns an answer or asks to use a tool.
4. The host checks and runs allowed tool calls, then sends the results back to the model.

This loop continues until the model gives a final answer. A request to use a tool is not permission to run it: the host decides what is allowed.

Explore the guided lessons at /learn with the learning-only setup; no model credentials or live model calls are needed.

The agent loop in the guided Learn experience. Learning guide.

2. See It Happen in Live Flow

Live Flow is the hands-on workspace where you run an agent and see what is happening as it runs.

• Watch the flow between the agent host, model and tools as your question is processed.
• Inspect the actual model requests, responses, tool calls and results.
• Pause, step through execution and replay a captured run without running it again.

The captured activity shows what the application sends and receives, not the model's private reasoning. Illustrations of model internals are labelled simulations.

Built with .NET 10, Aspire and your choice of Azure OpenAI, OpenAI or Gemini. Read the vision for more on the project's purpose and direction.

Follow a conversation alongside its agent and tools. Workspace guide.

Screenshots captured locally on 2026-09-22 from a running Blazor build. The live run uses public Wikipedia data and real calculator calls. Gray masks cover deployment identifiers. The ChatGPT-labelled host is a representative demo backed by Azure OpenAI, not a connection to the ChatGPT product. Select an image to open it at full size.

Security, Data, and Costs

AiService, the React BFF, and the sample MCP/A2A services do not provide caller authentication or per-user authorization. Chat endpoints can invoke tools; control and workspace endpoints also need protection. The terminal allowlist and workspace working directory are not a sandbox: processes run with the service account's permissions and can access files and networks outside that directory. Use only trusted workspaces and integrations. See the security policy for the full trust boundaries and private vulnerability-reporting channel.

• Live runs send prompts, conversation history, enabled instructions, selected context, and tool results to the configured model service. Provider charges may apply; local startup does not mean data stays local. Wikipedia, web-fetch, MCP, and A2A integrations can contact other services.
• Flow captures include model/tool payloads and can contain private data. Backend conversation history and frontend captures have separate lifetimes. Reset does not erase external copies, exported logs, screenshots, browser workspace preferences, or tool side effects. See conversation memory, Blazor replay retention, and React state.
• OpenTelemetry collects logs, traces, and metrics for the configured collector. Review their contents, access, and retention before using sensitive data; aggregate metrics without content do not guarantee that every log or trace is free of sensitive information.

To explore without model or protocol calls, use the learning-only Web guide without starting AppHost or the model/protocol services. Disabling an example or individual tools does not turn live chat into an offline workflow or impose a cost limit.

Prerequisites

For the full local application:

• .NET 10 SDK.
• Aspire CLI matching the pinned 13.5.4 version. The AppHost restores its Aspire SDK automatically and uses the SDK-paired CLI through dnx as a fallback when a compatible CLI is not on PATH.
• One model provider with a chat model that supports tool calling: an Azure OpenAI deployment (including Foundry), an OpenAI API key, or a Gemini API key.
• Git to clone the repository, or download and extract its source archive.

Docker is not required for the default local setup. The learning-only option needs just the .NET SDK and the source code, without model credentials or Aspire orchestration.

Run Locally

Get the Source

git clone https://github.com/o-viken/agenticlab.git
cd agenticlab

Run the following commands from the repository root.

Configure a Model Provider

Choose one provider and store its settings in the AppHost's local user-secrets store. Both AiService and A2AServer use that provider; restart the application after changing it. Keys stay in server-side configuration, not browser settings. Never commit credentials.

Configure Azure OpenAI

Azure OpenAI remains the default when Models:Provider is absent. Existing Foundry configuration continues to work. To select it explicitly, including when switching back from another provider:

dotnet user-secrets set "Models:Provider" "AzureOpenAI" --project src/AgenticLab.AppHost
dotnet user-secrets set "AzureOpenAI:Endpoint" "<your-azure-openai-endpoint>" --project src/AgenticLab.AppHost
dotnet user-secrets set "AzureOpenAI:Deployment" "<your-deployment-name>" --project src/AgenticLab.AppHost
dotnet user-secrets set "AzureOpenAI:ApiKey" "<your-api-key>" --project src/AgenticLab.AppHost

Use the deployment name you created in Azure, not just the model's name.

OpenAI API

dotnet user-secrets set "Models:Provider" "OpenAI" --project src/AgenticLab.AppHost
dotnet user-secrets set "OpenAI:Model" "<your-openai-model-id>" --project src/AgenticLab.AppHost
dotnet user-secrets set "OpenAI:ApiKey" "<your-openai-api-key>" --project src/AgenticLab.AppHost

Use an OpenAI API key, not a ChatGPT login. API usage is billed separately from ChatGPT subscriptions.

Gemini API

dotnet user-secrets set "Models:Provider" "Gemini" --project src/AgenticLab.AppHost
dotnet user-secrets set "Gemini:Model" "<your-gemini-model-id>" --project src/AgenticLab.AppHost
dotnet user-secrets set "Gemini:ApiKey" "<your-gemini-api-key>" --project src/AgenticLab.AppHost

Get the key from Google AI Studio. Gemini uses Google's OpenAI-compatible chat API, including streaming and tool calls. This compatibility API is beta; provider-specific features outside chat are not exposed.

OpenAI and Gemini need no Azure credentials or deployment. Choose a model available to your API account that supports chat completions and function calling. Selecting a ChatGPT or Gemini host in the UI only changes the example prompt; it does not select this backend or require its matching example to be enabled.

Environment variables work too: use Models__Provider, OpenAI__ApiKey / OpenAI__Model, or Gemini__ApiKey / Gemini__Model. Aspire explicitly forwards only the selected connection settings to the inference services. Live requests send context to that provider and may incur its charges. See model configuration for model overrides and validation rules.

Build and Start

Using the .NET CLI:

dotnet build AgenticLab.slnx
dotnet run --project src/AgenticLab.AppHost

Alternatively, use the Aspire CLI from the repository root:

aspire run

Aspire finds the AppHost through aspire.config.json, restores and builds it and its dependencies, then starts the application. No separate build command is needed to run it.

Open the Aspire dashboard URL printed in the terminal, then open the web resource's endpoint. The dashboard also provides service logs and traces.

Development startup enables Default, ChatGPT, GitHub Copilot and Copilot 365. Start with a conversation in Default, or select ChatGPT / chat and try:

Find the height of the Eiffel Tower on Wikipedia, then calculate how much taller it is than a 250-metre building.

Watch the model and tool activity, inspect the captured data, or use Manual mode to advance one step at a time. The vendor-labelled experiences are representative demos backed by your configured model API, not connections to those vendors' consumer products.

For a coding example, use sample-workspace with the GitHub Copilot host and Coder. Its short guide shows how to select the folder in Settings and try its sample content.

Run With Docker

docker-compose.yml builds the four service targets in Dockerfile. Set the selected provider's environment variables in the same terminal as Compose; AppHost user-secrets are not loaded into containers. For example, in PowerShell:

$env:Models__Provider = "AzureOpenAI"
$env:AzureOpenAI__Endpoint = "https://<resource>.openai.azure.com/"
$env:AzureOpenAI__Deployment = "<deployment>"
$env:AzureOpenAI__ApiKey = Read-Host "Azure OpenAI API key" -MaskInput
docker compose up --build -d

For OpenAI or Gemini, use the matching provider and environment variables described above. Enter keys locally, never in chat or committed files. Inference services require valid provider configuration; this full-stack command is not a credential-free learning mode.

Open http://localhost:8080. Published ports are bound to localhost: Web 8080, MCP 8081, A2A 8082 and AiService 8083. Internal service discovery uses HTTP port 8080 through services__aiservice__http__0, services__mcpserver__http__0 and services__a2aserver__http__0; ASPNETCORE_HTTP_PORTS alone does not configure outgoing connections. Compose uses Production settings (Default host only), without the Aspire dashboard.

After changing only Compose settings, run docker compose up -d from the credential-configured terminal; rebuilding is unnecessary. Check docker compose ps -a and docker compose logs --tail 100. Startup ordering is not readiness: if protocol discovery runs before a server is listening, use Discovery to retry once the services are ready. Stop with docker compose down.

Web's data-protection keys are not persisted across container replacement. Clear this site's cookies or use a private window if an old antiforgery cookie cannot be decrypted. This warning is separate from service connection errors; the local sample does not disable antiforgery protection.

Deploy to Radix

radixconfig.yaml deploys the four services to Equinor's Radix platform as the agenticlab application. Radix cannot select a stage of the multi-target root Dockerfile, so each component builds its own single-service file under docker/; keep them in sync with the root Dockerfile's stages.

• dev builds and deploys on every push to main. prod is never built; promote a dev deployment to it from the Radix web console.
• Only web is public, behind the Radix OAuth2 proxy restricted to the Equinor Entra ID tenant. aiservice, mcpserver and a2aserver are internal and reach each other at http://<component>:8080.
• Prod's official address is the app alias https://agenticlab.app.radix.equinor.com; dev is https://web-agenticlab-dev.radix.equinor.com. Every address users sign in through needs its /oauth2/callback URL registered as a Web redirect URI on the Entra ID app registration.
• aiservice runs with Workspace__Mode=ReadOnlySample: Ask, Plan and the Guide agent work on the bundled sample-workspace with read-only tools. Users can't choose server folders, write files, run commands or fetch web pages. See read-only sample mode.
• In the web console, set web's OAuth2 client secret and the AzureOpenAI__Endpoint and AzureOpenAI__ApiKey secrets of aiservice and a2aserver, in each environment.

Learning Only

To explore the guided lessons without configuring a model provider, run only the Web project:

dotnet run --project src/AgenticLab.Web

Open the listening URL printed in the terminal and visit /learn. The guide works without the AI service; live chat requires the full setup above.

Self-Contained Examples

Optional examples are registered as independent projects, keeping their domain code, UI, assets, tests and documentation together. See the example catalogue and contributor guide and the Windfarm project for an end-to-end process demo, or Copilot 365 for workplace chat, research and analysis over synthetic Microsoft 365 data. Every non-default host is an opt-in example, including ChatGPT, Gemini, GitHub Copilot, Claude Code, Claude, Copilot 365 and Windfarm. Each owns its host-specific prompts, branding and tests. The shared learning guide remains available independently of enabled examples. Use Examples:<id>:Enabled=true with IDs chatgpt, gemini, copilot, claude-code, claude, copilot365 or windfarm; flags can be combined. AppHost's Development settings enable chatgpt, copilot and copilot365; use --Examples:<id>:Enabled=false to disable one. Other environments start with only Default unless examples are explicitly enabled.

For example, enable the workplace Copilot host and its three agents:

dotnet run --project src/AgenticLab.AppHost -- --Examples:copilot365:Enabled=true

Documentation

Guide	What You Will Find
Agents and API	Agent personas, chat API, conversation memory, prompts, and model configuration.
Web Flow Workspace	Live visualization, panels, captured context, and execution controls.
Blazor Design System	Shared tokens, components, local fonts, accessibility, and the development catalogue.
Execution Explorer	Replay, breakpoints, streaming/control API, and retention limits.
Learning	Guided lessons and the contextual Learn panel.
Workspace Features	Workspace agents, skills, custom instructions, and file/terminal tools.
Protocols	MCP tools, A2A agents, discovery, and protocol integration tests.
React Frontend Example	Adding an alternative frontend on top of the existing AI service.
Example Modules	Self-contained community examples, extension contracts and registration.
Architecture and Conventions	Project structure and implementation guidance for contributors.
Browser Checks	Responsive UI smoke checks and separate browser load-test setup.
Security Policy	Private vulnerability reporting, tool risks, credentials, and data boundaries.
Contributing	Development workflow, checks, pull requests, and maintainer publication gates.

Alternative Frontend Example (React)

Blazor is the main frontend. The optional React example shows how to add an alternative frontend on top of the existing AI service, reusing its APIs through a backend-for-frontend. It runs alongside Blazor and is not required for the main application.

To try it, install Node.js 24 LTS and configure a model provider as described above, then run:

npm --prefix src/AgenticLab.React ci
aspire run -- --ReactFrontend:Enabled=true

Or use the .NET CLI after installing the same frontend dependencies:

dotnet run --project src/AgenticLab.AppHost -- --ReactFrontend:Enabled=true

Open the react resource's endpoint in the Aspire dashboard. The web resource still opens Blazor. See the React setup guide for customization and builds.

Contributing

Contributions can improve code, tests, documentation, lessons, or examples. Read CONTRIBUTING.md for setup, credential-free .NET tests, React/browser checks, and pull-request expectations. Discuss substantial changes in an issue first and keep changes focused.

Never include credentials, private workspace content, or sensitive captures in issues or pull requests. Report suspected vulnerabilities privately through the security policy.

License

Originally conceived and created by o-viken. Code and documentation are licensed under the Apache License 2.0, except where otherwise noted. See NOTICE for project attribution. Third-party assets retain their own licenses, including the Web icons and React assets. Published container images include the project license and attribution at /app/LICENSE and /app/NOTICE.