How aws-samples/sample-agentic-delegation works
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: delegation-mesh-stack.ts Gateway · coordinator/main.py Coordinator · audit.py Audit Events · pricing/main.py Pricing Agent
Components 18
Agents
Heterogeneous agent runtimes that receive delegated tasks and invoke tools through the gateway.
- Coordinator · Orchestrates tasks and delegates to specialist agents with constrained scopes.
agents/coordinator/main.py - Pricing Agent · Read-only specialist for pricing and lookup tasks.
agents/pricing/main.py - Purchasing 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 · Defines delegation tokens, scopes, and chains.
lib/delegation/models.py - Attenuation · Reduces permissions before minting downstream delegation.
lib/delegation/attenuate.py - Token Minting · Issues child delegation tokens for downstream agents and calls.
lib/delegation/mint.py - Validation · Verifies integrity, expiry, and chain consistency on receipt.
lib/delegation/validate.py - Audit Events · 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 · Single enforcement point for tool access and policy evaluation.
infra/lib/delegation-mesh-stack.ts - Cedar Policies · Delegation-aware authorization rules for chain depth, read-only limits, and amount caps.
infra/policies/delegation-policies.cedar - Policy Schema · Extends the Cedar model with delegation-specific entities and context.
infra/policies/delegation-schema.cedarschema - Tool Lambdas · Lambda-backed business tools for pricing, inventory, and purchase order actions.
infra/lib/delegation-mesh-stack.ts - Audit Dashboard · CloudWatch dashboard and log views for delegation decisions.
infra/lib/delegation-audit-dashboard.ts - Audit 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 · Runs token minting, attenuation, tamper detection, and audit output without AWS.
scripts/demo.py - Docker Compose · Runs the three agents locally on separate ports for multi-agent testing.
docker-compose.yml - Tests · Covers delegation logic, audit behavior, and integration workflows.
tests/test_integration.py
Other components
- User Request · Starts the delegation flow with an initial task request.
Connections 25
- 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.