# thangchung/agent-engineering-experiment architecture

> Architecture diagram of the GitHub repository thangchung/agent-engineering-experiment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thangchung/agent-engineering-experiment
- Repository: https://github.com/thangchung/agent-engineering-experiment

## Overview

#### Repository Shape and Entry Points
This is a workspace of independent samples/prototypes, not one deployable application; the root README is empty and there is no root solution. Each top-level project owns its runtime and deployment model. Primary .NET entry points include `DotNetClaw/DotNetClaw/Program.cs`, `foundry-agentfx/apphost.cs`, `loop-runtime/src/LoopRuntime.AppHost/Program.cs`, `mcp-experiments/src/AppHost/Program.cs`, and `context-engineering-dotnet/src/ContextEngineering.Api/Program.cs`. A separate Next.js storefront starts from `myshop-claude-code/app/page.tsx`.

#### Agent Runtime and Channel Pattern
DotNetClaw is a compact agent host: a runtime loads agent “mind” instructions and exposes Slack and web channels. Its core control path is host startup → runtime → tools/memory/skills → channel response.
- Runtime and telemetry: `DotNetClaw/DotNetClaw/ClawRuntime.cs`, `DotNetClaw/DotNetClaw/ClawTelemetry.cs`
- Input/output boundaries: `DotNetClaw/DotNetClaw/SlackChannel.cs`, `DotNetClaw/DotNetClaw/WebChannel.cs`
- Agent state/prompt assets: `DotNetClaw/DotNetClaw/mind/SOUL.md`, `DotNetClaw/DotNetClaw/mind/.working-memory/memory.md`

#### Foundry Coffeeshop Distributed Agent
`foundry-agentfx` decomposes the same broad pattern into services: channels route requests to an agent; the agent invokes a coffeeshop workflow and discovers tools through a gateway; an MCP service implements coffeeshop operations.
- Agent execution: `foundry-agentfx/src/Claw.Agent/Program.cs`, `foundry-agentfx/src/Claw.Agent/Agents/CoffeeshopWorkflow.cs`
- Channel-to-agent client boundary, including local versus Foundry-backed clients: `foundry-agentfx/src/Claw.Channels/Program.cs`, `foundry-agentfx/src/Claw.Channels/FoundryAgentClient.cs`
- Tool search/registration: `foundry-agentfx/src/ToolSearch.Gateway/Program.cs`, `foundry-agentfx/src/ToolSearch.Gateway/Registry/ToolRegistry.cs`
- MCP business tools: `foundry-agentfx/src/Coffeeshop.Mcp/Program.cs`, `foundry-agentfx/src/Coffeeshop.Mcp/Tools/OrderTools.cs`

Azure Foundry, Azure AI Search, Storage, Application Insights, Log Analytics, Container Apps, and container registry are provisioned through `foundry-agentfx/infra/main.bicep`.

#### Agent Gateway with OBO Identity
`agentgateway-entraid-obo` is a Todo-oriented reference architecture for delegated identity across API, agent, MCP server, and gateway. The Todo API accepts client requests and delegates through an `IAgentGateway`; the agent uses an LLM description generator and an MCP todo sink; the MCP service persists todos via EF Core.
- Public API/gateway adapters: `agentgateway-entraid-obo/src/AgenticTodo.TodoApi/Program.cs`, `agentgateway-entraid-obo/src/AgenticTodo.TodoApi/Adapters/OboAgentGateway.cs`
- Agent domain and feature orchestration: `agentgateway-entraid-obo/src/AgenticTodo.TodoAgent/Features/CreateTodo/CreateTodoHandler.cs`, `agentgateway-entraid-obo/src/AgenticTodo.TodoAgent/Adapters/Mcp/McpTodoSink.cs`
- MCP persistence boundary: `agentgateway-entraid-obo/src/AgenticTodo.TodoMcpServer/Adapters/TodoDbContext.cs`, `agentgateway-entraid-obo/src/AgenticTodo.TodoMcpServer/Tools/TodoTools.cs`
- Gateway policy/configuration: `agentgateway-entraid-obo/gateway.yaml`

#### Iterative Executor–Checker Runtime
`loop-runtime` implements an agent loop: an executor agent works with local/remote MCP tools and a code sandbox; a checker service evaluates output over A2A; shared contracts carry feedback, verdicts, and run results.
- Agent loop state and roles: `loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs`, `loop-runtime/src/LoopRuntime.Agents/CheckerAgent.cs`, `loop-runtime/src/LoopRuntime.Agents/SessionState.cs`
- Checker service/A2A boundary: `loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs`, `loop-runtime/src/LoopRuntime.Checker/CheckerAIAgent.cs`
- Tool and execution isolation: `loop-runtime/src/LoopRuntime.Mcp/Program.cs`, `loop-runtime/src/LoopRuntime.Sandbox/DockerSandbox.cs`
- Cross-service types: `loop-runtime/src/LoopRuntime.Contracts/ICodeSandbox.cs`, `loop-runtime/src/LoopRuntime.Contracts/Verdict.cs`

It uses Docker for sandboxing and includes Entra agent-identity/OBO setup scripts.

#### MCP and Context Infrastructure Experiments
Two projects supply reusable patterns around MCP.
- `mcp-experiments` turns OpenAPI operations into registered/searchable tools and can execute generated code through local, Hyperlight, or OpenSandbox runners: `mcp-experiments/src/McpServer/Program.cs`, `mcp-experiments/src/McpServer/OpenApi/OpenApiToolCatalogBuilder.cs`, `mcp-experiments/src/McpServer/CodeMode/SandboxRunnerFactory.cs`.
- `context-engineering-dotnet` provides conversation/scratchpad persistence, token counting, and context reduction behind API and MCP-server hosts: `context-engineering-dotnet/src/ContextEngineering.Infrastructure/Data/AppDbContext.cs`, `context-engineering-dotnet/src/ContextEngineering.Infrastructure/Services/SummarizingChatReducer.cs`, `context-engineering-dotnet/src/ContextEngineering.McpServer/Program.cs`.

Most .NET distributed projects use Aspire AppHosts and shared ServiceDefaults for local orchestration, service discovery, resilience, and telemetry.

Main entry points: [`loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs`](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs) (Executor Agent), [`foundry-agentfx/infra/main.bicep`](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/infra/main.bicep) (Azure Deployment), [`DotNetClaw/DotNetClaw/ClawRuntime.cs`](https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/ClawRuntime.cs) (Claw Runtime), [`loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs`](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs) (Checker Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dotnetclaw["DotNetClaw"]
  node_dotnetclaw_host["Agent Host<br/>console host<br/>[Program.cs]"]
  node_dotnetclaw_runtime["Claw Runtime<br/>agent runtime<br/>[ClawRuntime.cs]"]
  node_dotnetclaw_channels["Slack &amp; Web Channels<br/>channel adapters"]
  node_dotnetclaw_mind["Agent Mind<br/>prompt asset<br/>[SOUL.md]"]
end

subgraph group_foundry["Foundry Coffeeshop"]
  node_foundry_channels["Channels Service<br/>channel service<br/>[Program.cs]"]
  node_foundry_agent["Coffeeshop Agent<br/>agent workflow"]
  node_foundry_gateway["Tool Search Gateway<br/>tool gateway<br/>[ToolRegistry.cs]"]
  node_foundry_mcp["Coffeeshop MCP<br/>MCP service<br/>[OrderTools.cs]"]
  node_foundry_infra["Azure Deployment<br/>Bicep infrastructure<br/>[main.bicep]"]
end

subgraph group_obo["OBO Todo Gateway"]
  node_obo_api["Todo API<br/>public API<br/>[OboAgentGateway.cs]"]
  node_obo_agent["Todo Agent<br/>feature handler"]
  node_obo_mcp[("Todo MCP Persistence<br/>MCP data service<br/>[TodoDbContext.cs]")]
  node_obo_policy["Gateway Policy<br/>gateway config<br/>[gateway.yaml]"]
end

subgraph group_loop["Loop Runtime"]
  node_loop_executor["Executor Agent<br/>agent loop<br/>[ExecutorAgent.cs]"]
  node_loop_checker["Checker Service<br/>A2A evaluator"]
  node_loop_contracts["Run Contracts<br/>shared contracts<br/>[Verdict.cs]"]
  node_loop_mcp["MCP Tools<br/>MCP service<br/>[Program.cs]"]
  node_loop_sandbox["Docker Sandbox<br/>isolated executor<br/>[DockerSandbox.cs]"]
end

subgraph group_mcp["MCP &amp; Context Experiments"]
  node_mcp_catalog["OpenAPI Tool Catalog<br/>tool generator"]
  node_mcp_sandbox["Sandbox Runner Factory<br/>execution adapter"]
  node_context_reducer["Context Reducer<br/>context service"]
end

node_storefront["Next.js Storefront<br/>web application<br/>[page.tsx]"]

node_dotnetclaw_host -->|"starts"| node_dotnetclaw_runtime
node_dotnetclaw_channels -->|"sends requests"| node_dotnetclaw_runtime
node_dotnetclaw_runtime -->|"returns responses"| node_dotnetclaw_channels
node_dotnetclaw_runtime -->|"loads instructions"| node_dotnetclaw_mind
node_foundry_channels -->|"routes requests"| node_foundry_agent
node_foundry_agent -->|"discovers tools"| node_foundry_gateway
node_foundry_gateway -->|"registers tools"| node_foundry_mcp
node_foundry_infra -.->|"deploys"| node_foundry_channels
node_foundry_infra -.->|"deploys"| node_foundry_agent
node_foundry_infra -.->|"deploys"| node_foundry_gateway
node_foundry_infra -.->|"deploys"| node_foundry_mcp
node_obo_api -->|"uses gateway policy"| node_obo_policy
node_obo_policy -->|"forwards OBO request"| node_obo_agent
node_obo_agent -->|"creates todos"| node_obo_mcp
node_loop_executor -->|"invokes tools"| node_loop_mcp
node_loop_executor -->|"executes code"| node_loop_sandbox
node_loop_executor -->|"submits output over A2A"| node_loop_checker
node_loop_checker -->|"returns feedback"| node_loop_executor
node_loop_executor -.->|"uses"| node_loop_contracts
node_loop_checker -.->|"uses verdicts"| node_loop_contracts
node_mcp_catalog -->|"executes generated code"| node_mcp_sandbox
node_context_reducer -.->|"complementary MCP pattern"| node_mcp_catalog

click node_dotnetclaw_host "https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/Program.cs"
click node_dotnetclaw_runtime "https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/ClawRuntime.cs"
click node_dotnetclaw_mind "https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/mind/SOUL.md"
click node_foundry_channels "https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Claw.Channels/Program.cs"
click node_foundry_agent "https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Claw.Agent/Agents/CoffeeshopWorkflow.cs"
click node_foundry_gateway "https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/ToolSearch.Gateway/Registry/ToolRegistry.cs"
click node_foundry_mcp "https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Coffeeshop.Mcp/Tools/OrderTools.cs"
click node_foundry_infra "https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/infra/main.bicep"
click node_obo_api "https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoApi/Adapters/OboAgentGateway.cs"
click node_obo_agent "https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoAgent/Features/CreateTodo/CreateTodoHandler.cs"
click node_obo_mcp "https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoMcpServer/Adapters/TodoDbContext.cs"
click node_obo_policy "https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/gateway.yaml"
click node_loop_executor "https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs"
click node_loop_checker "https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs"
click node_loop_contracts "https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Contracts/Verdict.cs"
click node_loop_mcp "https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Mcp/Program.cs"
click node_loop_sandbox "https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Sandbox/DockerSandbox.cs"
click node_mcp_catalog "https://github.com/thangchung/agent-engineering-experiment/blob/main/mcp-experiments/src/McpServer/OpenApi/OpenApiToolCatalogBuilder.cs"
click node_mcp_sandbox "https://github.com/thangchung/agent-engineering-experiment/blob/main/mcp-experiments/src/McpServer/CodeMode/SandboxRunnerFactory.cs"
click node_context_reducer "https://github.com/thangchung/agent-engineering-experiment/blob/main/context-engineering-dotnet/src/ContextEngineering.Infrastructure/Services/SummarizingChatReducer.cs"
click node_storefront "https://github.com/thangchung/agent-engineering-experiment/blob/main/myshop-claude-code/app/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dotnetclaw_host,node_dotnetclaw_runtime,node_dotnetclaw_channels,node_dotnetclaw_mind toneBlue
class node_foundry_channels,node_foundry_agent,node_foundry_gateway,node_foundry_mcp,node_foundry_infra toneAmber
class node_obo_api,node_obo_agent,node_obo_mcp,node_obo_policy toneMint
class node_loop_executor,node_loop_checker,node_loop_contracts,node_loop_mcp,node_loop_sandbox toneRose
class node_mcp_catalog,node_mcp_sandbox,node_context_reducer toneIndigo
class node_storefront toneNeutral
```

## Components

### DotNetClaw

Compact agent host with Slack and web channels.

- [Agent Host](https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/Program.cs): console host · `DotNetClaw/DotNetClaw/Program.cs`
- [Claw Runtime](https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/ClawRuntime.cs): agent runtime · Loads instructions and coordinates tools, memory, and skills. · `DotNetClaw/DotNetClaw/ClawRuntime.cs`
- **Slack & Web Channels**: channel adapters
- [Agent Mind](https://github.com/thangchung/agent-engineering-experiment/blob/main/DotNetClaw/DotNetClaw/mind/SOUL.md): prompt asset · `DotNetClaw/DotNetClaw/mind/SOUL.md`

### Foundry Coffeeshop

Distributed agent and MCP coffeeshop sample.

- [Channels Service](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Claw.Channels/Program.cs): channel service · Routes requests through local or Foundry-backed agent clients. · `foundry-agentfx/src/Claw.Channels/Program.cs`
- [Coffeeshop Agent](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Claw.Agent/Agents/CoffeeshopWorkflow.cs): agent workflow · `foundry-agentfx/src/Claw.Agent/Agents/CoffeeshopWorkflow.cs`
- [Tool Search Gateway](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/ToolSearch.Gateway/Registry/ToolRegistry.cs): tool gateway · Registers and discovers available tools. · `foundry-agentfx/src/ToolSearch.Gateway/Registry/ToolRegistry.cs`
- [Coffeeshop MCP](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/src/Coffeeshop.Mcp/Tools/OrderTools.cs): MCP service · Exposes coffeeshop ordering operations. · `foundry-agentfx/src/Coffeeshop.Mcp/Tools/OrderTools.cs`
- [Azure Deployment](https://github.com/thangchung/agent-engineering-experiment/blob/main/foundry-agentfx/infra/main.bicep): Bicep infrastructure · Provisions Foundry, search, storage, observability, and Container Apps. · `foundry-agentfx/infra/main.bicep`

### OBO Todo Gateway

Delegated-identity Todo reference architecture.

- [Todo API](https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoApi/Adapters/OboAgentGateway.cs): public API · Delegates requests through the agent gateway. · `agentgateway-entraid-obo/src/AgenticTodo.TodoApi/Adapters/OboAgentGateway.cs`
- [Todo Agent](https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoAgent/Features/CreateTodo/CreateTodoHandler.cs): feature handler · Generates descriptions and orchestrates Todo creation. · `agentgateway-entraid-obo/src/AgenticTodo.TodoAgent/Features/CreateTodo/CreateTodoHandler.cs`
- [Todo MCP Persistence](https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/src/AgenticTodo.TodoMcpServer/Adapters/TodoDbContext.cs): MCP data service · Persists todos through EF Core. · `agentgateway-entraid-obo/src/AgenticTodo.TodoMcpServer/Adapters/TodoDbContext.cs`
- [Gateway Policy](https://github.com/thangchung/agent-engineering-experiment/blob/main/agentgateway-entraid-obo/gateway.yaml): gateway config · Defines delegated OBO identity and routing policy. · `agentgateway-entraid-obo/gateway.yaml`

### Loop Runtime

Executor-checker agent loop.

- [Executor Agent](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs): agent loop · Iterates on tasks with tools and sandbox execution. · `loop-runtime/src/LoopRuntime.Agents/ExecutorAgent.cs`
- [Checker Service](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs): A2A evaluator · Evaluates executor output and returns feedback. · `loop-runtime/src/LoopRuntime.Checker/CheckerA2AEndpoint.cs`
- [Run Contracts](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Contracts/Verdict.cs): shared contracts · Carries sandbox, feedback, verdict, and result types. · `loop-runtime/src/LoopRuntime.Contracts/Verdict.cs`
- [MCP Tools](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Mcp/Program.cs): MCP service · `loop-runtime/src/LoopRuntime.Mcp/Program.cs`
- [Docker Sandbox](https://github.com/thangchung/agent-engineering-experiment/blob/main/loop-runtime/src/LoopRuntime.Sandbox/DockerSandbox.cs): isolated executor · `loop-runtime/src/LoopRuntime.Sandbox/DockerSandbox.cs`

### MCP & Context Experiments

Reusable tool and context-management patterns.

- [OpenAPI Tool Catalog](https://github.com/thangchung/agent-engineering-experiment/blob/main/mcp-experiments/src/McpServer/OpenApi/OpenApiToolCatalogBuilder.cs): tool generator · Converts OpenAPI operations into searchable MCP tools. · `mcp-experiments/src/McpServer/OpenApi/OpenApiToolCatalogBuilder.cs`
- [Sandbox Runner Factory](https://github.com/thangchung/agent-engineering-experiment/blob/main/mcp-experiments/src/McpServer/CodeMode/SandboxRunnerFactory.cs): execution adapter · Selects local, Hyperlight, or OpenSandbox execution. · `mcp-experiments/src/McpServer/CodeMode/SandboxRunnerFactory.cs`
- [Context Reducer](https://github.com/thangchung/agent-engineering-experiment/blob/main/context-engineering-dotnet/src/ContextEngineering.Infrastructure/Services/SummarizingChatReducer.cs): context service · Reduces persisted conversation and scratchpad context. · `context-engineering-dotnet/src/ContextEngineering.Infrastructure/Services/SummarizingChatReducer.cs`

### Other components

- [Next.js Storefront](https://github.com/thangchung/agent-engineering-experiment/blob/main/myshop-claude-code/app/page.tsx): web application · Independent storefront prototype. · `myshop-claude-code/app/page.tsx`

## Connections

- Agent Host → Claw Runtime: starts
- Slack & Web Channels → Claw Runtime: sends requests
- Claw Runtime → Slack & Web Channels: returns responses
- Claw Runtime → Agent Mind: loads instructions
- Channels Service → Coffeeshop Agent: routes requests
- Coffeeshop Agent → Tool Search Gateway: discovers tools
- Tool Search Gateway → Coffeeshop MCP: registers tools
- Azure Deployment → Channels Service: deploys
- Azure Deployment → Coffeeshop Agent: deploys
- Azure Deployment → Tool Search Gateway: deploys
- Azure Deployment → Coffeeshop MCP: deploys
- Todo API → Gateway Policy: uses gateway policy
- Gateway Policy → Todo Agent: forwards OBO request
- Todo Agent → Todo MCP Persistence: creates todos
- Executor Agent → MCP Tools: invokes tools
- Executor Agent → Docker Sandbox: executes code
- Executor Agent → Checker Service: submits output over A2A
- Checker Service → Executor Agent: returns feedback
- Executor Agent → Run Contracts: uses
- Checker Service → Run Contracts: uses verdicts
- OpenAPI Tool Catalog → Sandbox Runner Factory: executes generated code
- Context Reducer → OpenAPI Tool Catalog: complementary MCP pattern