How ukhan262/claude-managed-agents-aca works
1. What this repo implements
- This is a three-part reference architecture for running Claude “managed agents” with Anthropic handling the agent loop and Azure Container Apps dynamic sessions handling tool execution. The repository is organized around one user-facing app, one session allocator, and one ephemeral sandbox worker.
2. Main subsystems
- frontend/: the chat/UI entrypoint that talks to Anthropic with an org API key.
- dispatcher/: the always-on or webhook-triggered allocator that decides when a session needs a sandbox.
- sandbox/: the per-run container image that executes tools locally inside a dynamic session.
- environment-queue-cleanup/: a supporting utility for clearing stale queue/session state.
3. Frontend boundary
- The frontend is the only component meant to interact with end users. It creates Anthropic sessions, sends user.message events, and streams back agent/tool events for rendering.
- Architecturally, it sits outside the dynamic-session pool and never runs tools itself. Its main dependency is the Anthropic API, with the secret boundary being the org API key stored server-side.
4. Dispatcher boundary
- The dispatcher is the control plane bridge between Anthropic and Azure session allocation.
- In poll mode, it uses the Anthropic API to check for queued work and needs the API key.
- In webhook mode, it reacts to Anthropic session events instead, so it can avoid holding the Anthropic API key and only needs a webhook secret plus access to the session pool management endpoint.
5. Sandbox boundary
- The sandbox is the execution plane. It is an ephemeral container started per run in a dynamic session.
- It holds only the environment key and environment ID, not the Anthropic API key. That is the key security boundary: the sandbox can execute tools locally, reach private VNet resources, and report results back through the Anthropic-managed agent loop without owning the user-facing secret.
6. End-to-end request flow
- User input starts in the frontend, which creates a session and sends a message to Anthropic.
- Anthropic enqueues work for the managed agent.
- The dispatcher notices pending work or receives a webhook, then calls /start on the session pool with an identifier.
- Azure allocates one fresh sandbox container, forwards the start request, and the sandbox claims the pending item, runs bash/file tools, posts results, and exits.
- Exiting the container ends the dynamic session, which is why the pool lifecycle must be aligned to container exit.
7. Queueing and idempotency model
- The README makes an important architectural point: handle_item() claims one pending session item and each run maps to one sandbox instance.
- In webhook mode, the Azure Container Apps identifier is the session id, which makes allocation effectively 1:1 and retry-safe. This is the key diagram element for avoiding duplicated work.
8. Infrastructure dependencies that matter
- The sandbox runs inside an Azure Container Apps dynamic sessions pool with OnContainerExit lifecycle, target port 8080, and secrets injected via environment variables.
- The pool is expected to be VNet-integrated so the sandbox can directly reach internal APIs/databases.
- The dispatcher needs permission to invoke the session pool, and the pool may need AcrPull if it pulls sandbox images from Azure Container Registry.
9. Data and secret flow
- Secrets are intentionally split by responsibility: frontend gets ANTHROPIC_API_KEY; dispatcher gets either the API key or webhook secret depending on mode; sandbox gets only ANTHROPIC_ENVIRONMENT_KEY and ANTHROPIC_ENVIRONMENT_ID.
- This separation is central to the design: the browser never sees secrets, the dispatcher never runs tools, and the sandbox never gets the org API key.
10. Operational/supporting component
- environment-queue-cleanup/ appears to be a maintenance worker for queue/session hygiene, likely used to clean stale environments or pending items. It is not part of the main request path, but it supports reliable operation of the managed-agent queue.
11. What a diagram should emphasize
- Draw three trust zones: user-facing frontend, control-plane dispatcher, and ephemeral sandbox pool.
- Show Anthropic as the system that owns the agent loop and event stream.
- Show Azure Container Apps dynamic sessions as the execution substrate that spawns one isolated container per run.
- Highlight the one-way secret boundary: API key stays outside the sandbox; environment key stays inside it.
12. Repo shape and runtime
- Each major component is a separate Python container image (Dockerfile + requirements.txt), which suggests independently deployable services rather than a single monolith.
- The presence of frontend/static/index.html indicates a small server-rendered or API-backed UI, while the other two services are backend workers/operators.
Main entry points: main.py Dispatcher · server.py Sandbox · app.py Frontend · index.html Web UI
Components 16
User-facing
Interactive entrypoint for the managed-agent workflow.
Control plane
Allocates and coordinates sandbox sessions.
- Anthropic · Owns the managed-agent loop, session events, and queued work.
- Dispatcher · Always-on or webhook-triggered session allocator that bridges Anthropic work to Azure sessions.
dispatcher/main.py - Poll mode · Checks Anthropic for queued work using the API key.
- Webhook mode · Receives Anthropic session events and avoids storing the Anthropic API key.
- Session pool · Azure Container Apps dynamic sessions pool that starts one sandbox container per run.
- ACA control · Azure Container Apps control surface used to start sessions and manage lifecycle.
- Org API key · Anthropic API credential kept outside the sandbox.
- ACR · Container registry used to pull sandbox images when needed.
Execution plane
Ephemeral per-run sandbox containers.
- Sandbox · Ephemeral container that runs bash and file tools inside the dynamic session.
sandbox/server.py - Local tools · Tool execution layer inside the sandbox.
- Private resources · Internal APIs and databases reachable from the VNet-integrated sandbox.
- Env secrets · Sandbox-only environment key and environment ID injected as runtime secrets.
Support
Operational maintenance for queue and session hygiene.
- Cleanup · Background maintenance for clearing stale queue or session state.
environment-queue-cleanup/main.py
Connections 17
- User → Web UI: uses · User interacts with the chat interface.
- Web UI → Frontend: serves · Static UI is served by the frontend application.
- Frontend → Anthropic: creates session · Frontend sends user messages and streams events through Anthropic.
- Frontend → Org API key: reads secret · Frontend uses the organization API key server-side.
- Anthropic → Dispatcher: event / queue · Anthropic exposes queued work or webhook events to the dispatcher.
- Dispatcher → Poll mode: supports · Dispatcher can operate by polling Anthropic for pending work.
- Dispatcher → Webhook mode: supports · Dispatcher can also operate as a webhook receiver.
- Poll mode → Org API key: uses key · Polling mode needs the Anthropic API key.
- Webhook mode → Dispatcher: triggers · Webhook events wake the dispatcher without requiring the API key.
- Dispatcher → ACA control: starts sessions · Dispatcher calls the session pool start endpoint with an identifier.
- ACA control → Session pool: allocates · Azure Container Apps creates a fresh sandbox container per run.
- Session pool → Sandbox: launches · Dynamic session starts the sandbox container.
- Sandbox → Local tools: executes · Sandbox runs local tool actions such as bash and file operations.
- Sandbox → Private resources: reaches · Sandbox can access private network resources.
- Sandbox → Env secrets: reads secret · Sandbox receives only environment-specific secrets.
- Session pool → ACR: pulls image · Pool may pull the sandbox image from Azure Container Registry.
- Cleanup → Session pool: cleans state · Maintenance worker clears stale queue or session state.