# aws-samples/sample-agentic-delegation architecture

> Architecture diagram of the GitHub repository aws-samples/sample-agentic-delegation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-agentic-delegation
- Repository: https://github.com/aws-samples/sample-agentic-delegation

## Overview

1. This repository is organized around a **delegation-chain security pattern for multi-agent systems**. The core idea is that a user request enters a **coordinator agent**, which delegates to specialist agents with progressively narrower permissions, and every downstream tool call is authorized by a **Cedar policy engine** at the gateway.

2. The main architectural boundary is the split between **agent logic** and **delegation/security infrastructure**. Agent behavior lives under `agents/`, while the reusable delegation semantics live in `lib/delegation/`. That library is framework-agnostic and is the heart of the repo’s security model: it defines how scopes are represented, attenuated, minted, validated, and audited.

3. `lib/delegation/` contains the security primitives:
   - `models.py` for delegation tokens, scopes, and chains
   - `attenuate.py` for narrowing permissions
   - `mint.py` for issuing child tokens
   - `validate.py` for receiving-side integrity and expiry checks
   - `audit.py` for structured event logging  
   This layer is the canonical source of truth for the delegation chain rules used by both the demo and the agents.

4. The **agent tier** is deliberately heterogeneous to demonstrate cross-framework delegation:
   - `agents/coordinator` is the entry point and orchestration agent
   - `agents/pricing` is a read-only specialist
   - `agents/purchasing` is a write-capable specialist with amount caps  
   The README indicates these are implemented with different agent frameworks/runtime styles, which matters because the delegation protocol must work across agent boundaries, not just within one framework.

5. The primary runtime flow is:
   user request → coordinator → delegated specialist agent(s) → tool invocation through gateway → policy decision → tool backend.  
   The specialists receive delegation metadata with the A2A task, validate the chain locally, then attach delegation context to MCP tool calls so the gateway can enforce policy centrally.

6. The **AWS deployment layer** is in `infra/` and is built with **AWS CDK in TypeScript**. The key stack file, `delegation-mesh-stack.ts`, provisions the AgentCore runtime, gateway, and Lambda-backed tools. `delegation-audit-dashboard.ts` adds CloudWatch observability. This means the repo is not just a library; it is an end-to-end reference implementation with infrastructure as code.

7. Authorization is enforced with **Cedar policies** stored under `infra/policies/`. The schema (`delegation-schema.cedarschema`) extends the policy model with delegation-aware entities and contextual authorization. The policy file (`delegation-policies.cedar`) encodes the actual access rules, such as chain depth limits, read-only restrictions, and amount-cap enforcement for financial actions.

8. The **tooling/data plane** is centered on the AgentCore Gateway and Lambda functions. The gateway is the single enforcement point for tool access, while Lambda functions back the actual procurement tools, such as pricing lookup, inventory read, and purchase order creation. This separates policy enforcement from business logic and keeps the agent code from directly reaching tools without mediation.

9. **Auditability** is a first-class subsystem. Delegation decisions are emitted as structured logs and then visualized through CloudWatch dashboards and Logs Insights queries (`infra/queries/audit-queries.sql`). The audit layer is designed to retain the full delegation chain context for every ALLOW/DENY decision, making it possible to reconstruct why a tool call was allowed or rejected.

10. The repository supports two execution modes:
   - a **local demo** in `scripts/demo.py` that runs without AWS and demonstrates token minting, attenuation, tamper detection, and audit output
   - a **local multi-agent Docker setup** via `docker-compose.yml` for running the three agents together on local ports  
   This makes the security model testable before any cloud deployment.

11. The testing strategy is layered:
   - unit tests for the delegation library in `tests/test_delegation.py`
   - audit/logging tests in `tests/test_audit.py`
   - end-to-end workflow tests in `tests/test_integration.py`  
   That structure reflects the architecture: the reusable delegation logic is isolated from agent orchestration and from cloud integration concerns.

12. The repo also includes operational glue for deploying policy into the gateway (`scripts/load-cedar-policies.sh`) and a specification document (`agentic-delegation-spec.md`) that likely defines the protocol and security model in more detail. Together, these files show the project is meant as a **reference architecture** for secure multi-agent delegation, not just an application.

13. If you are drawing the architecture, the most important boxes and arrows are: **User → Coordinator Agent → Specialist Agent(s) → Gateway/Policy Engine → Lambda Tool Backends**, with a parallel **Delegation Library** used by coordinator and specialists, and a separate **Audit/CloudWatch** path capturing every decision. The key security property is that permissions only narrow as they move rightward through the chain.

Main entry points: [`infra/lib/delegation-mesh-stack.ts`](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-mesh-stack.ts) (Gateway), [`agents/coordinator/main.py`](https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/coordinator/main.py) (Coordinator), [`lib/delegation/audit.py`](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/audit.py) (Audit Events), [`agents/pricing/main.py`](https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/pricing/main.py) (Pricing Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_agents["Agents"]
  node_node_coordinator["Coordinator<br/>agent<br/>[main.py]"]
  node_node_pricing["Pricing Agent<br/>[main.py]"]
  node_node_purchasing["Purchasing Agent<br/>[main.py]"]
end

subgraph group_grp_delegation["Delegation Core"]
  node_node_models["Delegation Models<br/>core model<br/>[models.py]"]
  node_node_attenuate{{"Attenuation<br/>scope narrowing<br/>[attenuate.py]"}}
  node_node_mint["Token Minting<br/>token issuer<br/>[mint.py]"]
  node_node_validate["Validation<br/>chain check<br/>[validate.py]"]
  node_node_auditlib["Audit Events<br/>logging<br/>[audit.py]"]
end

subgraph group_grp_infra["Cloud Infra"]
  node_node_gateway[("Gateway")]
  node_node_cedar["Cedar Policies<br/>policy rules"]
  node_node_schema["Policy Schema<br/>authorization schema"]
  node_node_tools["Tool Lambdas<br/>tool backend"]
  node_node_dashboard["Audit Dashboard<br/>observability"]
  node_node_queries["Audit Queries<br/>log queries<br/>[audit-queries.sql]"]
end

subgraph group_grp_ops["Ops & Demo"]
  node_node_demo["Local Demo<br/>demo runner<br/>[demo.py]"]
  node_node_compose["Docker Compose<br/>local runtime<br/>[docker-compose.yml]"]
  node_node_tests["Tests<br/>test suite"]
end

node_node_user(("User Request<br/>entrypoint"))

node_node_user -->|"request"| node_node_coordinator
node_node_coordinator -->|"build chain"| node_node_models
node_node_coordinator -->|"narrow scope"| node_node_attenuate
node_node_attenuate -->|"issue child"| node_node_mint
node_node_mint -->|"delegate"| node_node_pricing
node_node_mint -->|"delegate"| node_node_purchasing
node_node_pricing -->|"verify chain"| node_node_validate
node_node_purchasing -->|"verify chain"| node_node_validate
node_node_validate -->|"attach context"| node_node_gateway
node_node_pricing -->|"tool call"| node_node_gateway
node_node_purchasing -->|"tool call"| node_node_gateway
node_node_gateway -->|"authorize"| node_node_cedar
node_node_cedar -->|"interpret"| node_node_schema
node_node_gateway -->|"dispatch"| node_node_tools
node_node_gateway -->|"emit event"| node_node_auditlib
node_node_auditlib -->|"visualize"| node_node_dashboard
node_node_auditlib -->|"query"| node_node_queries
node_node_demo -->|"exercise"| node_node_models
node_node_demo -->|"show logs"| node_node_auditlib
node_node_compose -->|"run"| node_node_coordinator
node_node_compose -->|"run"| node_node_pricing
node_node_compose -->|"run"| node_node_purchasing
node_node_tests -->|"cover"| node_node_models
node_node_tests -->|"cover"| node_node_auditlib
node_node_tests -->|"exercise"| node_node_coordinator

click node_node_coordinator "https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/coordinator/main.py"
click node_node_pricing "https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/pricing/main.py"
click node_node_purchasing "https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/purchasing/main.py"
click node_node_models "https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/models.py"
click node_node_attenuate "https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/attenuate.py"
click node_node_mint "https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/mint.py"
click node_node_validate "https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/validate.py"
click node_node_auditlib "https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/audit.py"
click node_node_gateway "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-mesh-stack.ts"
click node_node_cedar "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/policies/delegation-policies.cedar"
click node_node_schema "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/policies/delegation-schema.cedarschema"
click node_node_tools "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-mesh-stack.ts"
click node_node_dashboard "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-audit-dashboard.ts"
click node_node_queries "https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/queries/audit-queries.sql"
click node_node_demo "https://github.com/aws-samples/sample-agentic-delegation/blob/main/scripts/demo.py"
click node_node_compose "https://github.com/aws-samples/sample-agentic-delegation/blob/main/docker-compose.yml"
click node_node_tests "https://github.com/aws-samples/sample-agentic-delegation/blob/main/tests/test_integration.py"

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_node_coordinator,node_node_pricing,node_node_purchasing toneBlue
class node_node_models,node_node_attenuate,node_node_mint,node_node_validate,node_node_auditlib toneAmber
class node_node_gateway,node_node_cedar,node_node_schema,node_node_tools,node_node_dashboard,node_node_queries toneMint
class node_node_demo,node_node_compose,node_node_tests toneRose
class node_node_user toneNeutral
```

## Components

### Agents

Heterogeneous agent runtimes that receive delegated tasks and invoke tools through the gateway.

- [Coordinator](https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/coordinator/main.py): agent · Orchestrates tasks and delegates to specialist agents with constrained scopes. · `agents/coordinator/main.py`
- [Pricing Agent](https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/pricing/main.py): agent · Read-only specialist for pricing and lookup tasks. · `agents/pricing/main.py`
- [Purchasing Agent](https://github.com/aws-samples/sample-agentic-delegation/blob/main/agents/purchasing/main.py): agent · Write-capable specialist that operates under amount caps and narrower permissions. · `agents/purchasing/main.py`

### Delegation Core

Framework-agnostic security primitives for minting, narrowing, validating, and auditing delegation chains.

- [Delegation Models](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/models.py): core model · Defines delegation tokens, scopes, and chains. · `lib/delegation/models.py`
- [Attenuation](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/attenuate.py): scope narrowing · Reduces permissions before minting downstream delegation. · `lib/delegation/attenuate.py`
- [Token Minting](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/mint.py): token issuer · Issues child delegation tokens for downstream agents and calls. · `lib/delegation/mint.py`
- [Validation](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/validate.py): chain check · Verifies integrity, expiry, and chain consistency on receipt. · `lib/delegation/validate.py`
- [Audit Events](https://github.com/aws-samples/sample-agentic-delegation/blob/main/lib/delegation/audit.py): logging · Produces structured delegation decision and chain audit events. · `lib/delegation/audit.py`

### Cloud Infra

AWS CDK stacks, Cedar policy artifacts, and observability for the secured tool plane.

- [Gateway](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-mesh-stack.ts): policy gateway · Single enforcement point for tool access and policy evaluation. · `infra/lib/delegation-mesh-stack.ts`
- [Cedar Policies](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/policies/delegation-policies.cedar): policy rules · Delegation-aware authorization rules for chain depth, read-only limits, and amount caps. · `infra/policies/delegation-policies.cedar`
- [Policy Schema](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/policies/delegation-schema.cedarschema): authorization schema · Extends the Cedar model with delegation-specific entities and context. · `infra/policies/delegation-schema.cedarschema`
- [Tool Lambdas](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-mesh-stack.ts): tool backend · Lambda-backed business tools for pricing, inventory, and purchase order actions. · `infra/lib/delegation-mesh-stack.ts`
- [Audit Dashboard](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/lib/delegation-audit-dashboard.ts): observability · CloudWatch dashboard and log views for delegation decisions. · `infra/lib/delegation-audit-dashboard.ts`
- [Audit Queries](https://github.com/aws-samples/sample-agentic-delegation/blob/main/infra/queries/audit-queries.sql): log queries · Logs Insights queries for reconstructing ALLOW and DENY decisions. · `infra/queries/audit-queries.sql`

### Ops & Demo

Local demo, compose-based execution, and test coverage for the delegation model.

- [Local Demo](https://github.com/aws-samples/sample-agentic-delegation/blob/main/scripts/demo.py): demo runner · Runs token minting, attenuation, tamper detection, and audit output without AWS. · `scripts/demo.py`
- [Docker Compose](https://github.com/aws-samples/sample-agentic-delegation/blob/main/docker-compose.yml): local runtime · Runs the three agents locally on separate ports for multi-agent testing. · `docker-compose.yml`
- [Tests](https://github.com/aws-samples/sample-agentic-delegation/blob/main/tests/test_integration.py): test suite · Covers delegation logic, audit behavior, and integration workflows. · `tests/test_integration.py`

### Other components

- **User Request**: entrypoint · Starts the delegation flow with an initial task request.

## Connections

- User Request → Coordinator: request · A user request enters the coordinator agent.
- Coordinator → Delegation Models: build chain · The coordinator creates or extends delegation state using the shared model.
- Coordinator → Attenuation: narrow scope · Before delegation, permissions are reduced for the downstream specialist.
- Attenuation → Token Minting: issue child · Attenuated permissions are packaged into a child delegation token.
- Token Minting → Pricing Agent: delegate · The coordinator hands off read-only work to the pricing specialist.
- Token Minting → Purchasing Agent: delegate · The coordinator hands off constrained write work to the purchasing specialist.
- Pricing Agent → Validation: verify chain · The specialist validates delegation metadata before using tools.
- Purchasing Agent → Validation: verify chain · The specialist validates delegation metadata before using tools.
- Validation → Gateway: attach context · Validated delegation context is attached to downstream tool calls.
- Pricing Agent → Gateway: tool call · Pricing requests flow through the gateway for authorization.
- Purchasing Agent → Gateway: tool call · Purchasing requests flow through the gateway for authorization.
- Gateway → Cedar Policies: authorize · The gateway evaluates the call against Cedar policy rules.
- Cedar Policies → Policy Schema: interpret · Policy decisions rely on the delegation-aware authorization schema.
- Gateway → Tool Lambdas: dispatch · Allowed calls are forwarded to the Lambda tool backends.
- Gateway → Audit Events: emit event · Each decision produces structured delegation audit output.
- Audit Events → Audit Dashboard: visualize · Audit events surface in CloudWatch dashboards and log views.
- Audit Events → Audit Queries: query · Logs Insights queries reconstruct decision history and chain context.
- Local Demo → Delegation Models: exercise · The local demo demonstrates token and chain behavior.
- Local Demo → Audit Events: show logs · The demo emits and displays audit output locally.
- Docker Compose → Coordinator: run · Compose starts the coordinator container.
- Docker Compose → Pricing Agent: run · Compose starts the pricing container.
- Docker Compose → Purchasing Agent: run · Compose starts the purchasing container.
- Tests → Delegation Models: cover · Unit tests validate the delegation primitives.
- Tests → Audit Events: cover · Tests verify audit event generation and formatting.
- Tests → Coordinator: exercise · Integration tests drive the end-to-end agent flow.
