Agent Architecture Reference¶
Overview¶
This document describes the enhanced agent execution architecture supporting the dual-layer system (Internal AgentCore + AWS Bedrock AgentCore) with modular dry run testing capabilities.
Current Architecture (After Migration)¶
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ENHANCED AGENT EXECUTION FLOW │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌──────────────────┐ ┌────────────────────────────────┐ │
│ │ User │───▶│ AgentController │───▶│ AgentOrchestrator │ │
│ │ Request │ │ │ │ ┌──────────────────────────┐ │ │
│ └─────────────┘ └──────────────────┘ │ │ executeDryRun() │ │ │
│ │ │ │ (Test before publish) │ │ │
│ │ │ └──────────────────────────┘ │ │
│ ▼ └────────────┬───────────────────┘ │
│ ┌─────────────┐ │ │
│ │ Dry Run? │──── YES ────────────────────────────────▶│ │
│ └─────────────┘ │ │
│ │ NO ▼ │
│ │ ┌────────────────────────────────────────────────┐ │
│ │ │ AGENT TYPE ROUTER │ │
│ │ │ ┌──────────┬──────────────┬───────────────┐ │ │
│ │ │ │ INTERNAL │BEDROCK_MEMORY│ BEDROCK_FULL │ │ │
│ │ │ │ (Default)│ (Hybrid) │ (Future) │ │ │
│ │ │ └────┬─────┴──────┬───────┴───────────────┘ │ │
│ │ └───────┼────────────┼───────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ INTERNAL AGENTCORE │ │
│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ │ WorkflowPlanner │ │ │
│ │ │ (Uses Bedrock Claude Models) │ │ │
│ │ │ • Multi-step planning with dependency resolution │ │ │
│ │ │ • Guardrail enforcement │ │ │
│ │ │ • Retry logic with exponential backoff │ │ │
│ │ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ │ CapabilityRegistry │ │ │
│ │ │ (50+ Capabilities) │ │ │
│ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │
│ │ │ │ Generation │ │ Analysis │ │ Publishing │ │ Workflow │ │ │ │
│ │ │ │ • Text │ │ • SEO │ │ • Social │ │ • Co-Sell │ │ │ │
│ │ │ │ • Image │ │ • Compete │ │ • Mkplace │ │ • GTM │ │ │ │
│ │ │ │ • Meta │ │ • Content │ │ • CRM │ │ • Partner │ │ │ │
│ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │
│ │ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │ │
│ │ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ │ BrandVoiceContextBuilder │ │ │
│ │ │ • Company brand voice injection │ │ │
│ │ │ • Product context │ │ │
│ │ │ • Custom instructions │ │ │
│ │ └───────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────────────────┼──────────────────────────────────────┐ │
│ │ AWS BEDROCK SERVICES │ │ │
│ │ ┌─────────────────────────────────▼──────────────────────────────────┐ │ │
│ │ │ BedrockRuntime │ │ │
│ │ │ • Claude 3.5 Sonnet/Haiku/Opus │ │ │
│ │ │ • Stable Diffusion XL │ │ │
│ │ │ • Amazon Nova │ │ │
│ │ └────────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ BedrockAgent │ │ BedrockKnowledgeBase │ │ │
│ │ │ • Session memory (40-60% save) │ │ • RAG for documents │ │ │
│ │ │ • Cross-session context │ │ • Platform knowledge │ │ │
│ │ │ • Memory types: │ │ • Company data │ │ │
│ │ │ - SESSION_SUMMARY │ └─────────────────────────────┘ │ │
│ │ │ - SEMANTIC │ │ │
│ │ └──────────────────────────────────┘ │ │
│ │ │ │
│ │ ┌──────────────────────────────────┐ ┌─────────────────────────────┐ │ │
│ │ │ Guardrails │ │ CloudWatch │ │ │
│ │ │ • Content safety │ │ • Observability │ │ │
│ │ │ • PII filtering │ │ • Cost tracking │ │ │
│ │ │ • Custom policies │ │ • Audit logs │ │ │
│ │ └──────────────────────────────────┘ └─────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ DRY RUN & TESTING LAYER │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ AgentExecutionDryRunService │ │ │
│ │ │ • Complete workflow simulation without side effects │ │ │
│ │ │ • Stakeholder challenge mode (5 personas) │ │ │
│ │ │ • AWS Marketplace readiness testing │ │ │
│ │ │ • Cost estimation │ │ │
│ │ │ • Capability preview │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │
│ │ │ AgentMigrationService │ │ │
│ │ │ • Migrate between agent types (with dry run) │ │ │
│ │ │ • Batch migration support │ │ │
│ │ │ • Rollback capability │ │ │
│ │ │ • Migration recommendations │ │ │
│ │ └─────────────────────────────────────────────────────────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Agent Type Comparison¶
┌────────────────────────────────────────────────────────────────────────────────┐
│ AGENT TYPE ARCHITECTURE │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ INTERNAL (Default) BEDROCK_MEMORY BEDROCK_FULL │
│ ═══════════════════ ════════════════ ═══════════════ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ User Request │ │ User Request │ │ User Request │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ AgentOrchestrator│ │ AgentOrchestrator│ │ Bedrock Agent │ │
│ │ (Internal) │ │ (Internal) │ │ (AWS Native) │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ WorkflowPlanner │ │ WorkflowPlanner │ │ Bedrock Agent │ │
│ │ + Claude │ │ + Claude+Memory │ │ Runtime │ │
│ └────────┬────────┘ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Capabilities │ │ Capabilities │ │ AWS Actions │ │
│ │ Execution │ │ Execution │ │ & Tools │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ✓ Legacy agents │ │ ✓ Session memory│ │ ✓ Full AWS │ │
│ │ ✓ No AWS setup │ │ ✓ 40-60% tokens │ │ ✓ Marketplace │ │
│ │ ✓ Fast & simple │ │ ✓ Multi-session │ │ ✓ Managed │ │
│ │ ✗ No memory │ │ ✓ Hybrid control│ │ ✗ Less control │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ Best for: Best for: Best for: │
│ • Quick tasks • Research workflows • AWS Marketplace │
│ • One-off content • Co-sell matching • Enterprise deploy │
│ • Simple automation • Multi-turn analysis • Fully managed AI │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
Dry Run Testing Flow¶
┌────────────────────────────────────────────────────────────────────────────────┐
│ DRY RUN TESTING WORKFLOW │
├────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 1. INITIATE DRY RUN │ │
│ │ POST /api/agents/audit/{agent}/dry-run │ │
│ │ { "task": "Create promotional content", "quality": "standard" } │ │
│ └─────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 2. WORKFLOW SIMULATION │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐│ │
│ │ │ ✓ Plan workflow steps ││ │
│ │ │ ✓ Validate each capability ││ │
│ │ │ ✓ Estimate token usage ││ │
│ │ │ ✓ Calculate cost estimate ││ │
│ │ │ ✓ Generate simulated outputs (optional) ││ │
│ │ └─────────────────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 3. CHALLENGE MODE (Optional) │ │
│ │ POST /api/agents/audit/{agent}/challenge │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐│ │
│ │ │ Stakeholder Personas: ││ │
│ │ │ ┌───────────────┐ ┌───────────────┐ ┌───────────────────────┐ ││ │
│ │ │ │ Technical │ │ Business │ │ Compliance │ ││ │
│ │ │ │ Reviewer │ │ Stakeholder │ │ Officer │ ││ │
│ │ │ │ • Security │ │ • ROI │ │ • Privacy │ ││ │
│ │ │ │ • Scale │ │ • Cost │ │ • Audit │ ││ │
│ │ │ └───────────────┘ └───────────────┘ └───────────────────────┘ ││ │
│ │ │ ┌───────────────┐ ┌───────────────────────────────────────┐ ││ │
│ │ │ │ End User │ │ AWS Marketplace │ ││ │
│ │ │ │ Champion │ │ Reviewer │ ││ │
│ │ │ │ • UX │ │ • Bedrock best practices │ ││ │
│ │ │ │ • Reliability│ │ • Billing integration │ ││ │
│ │ │ └───────────────┘ └───────────────────────────────────────┘ ││ │
│ │ └─────────────────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────────────┐ │
│ │ 4. MARKETPLACE READINESS TEST │ │
│ │ GET /api/agents/audit/{agent}/marketplace-readiness │ │
│ │ ┌─────────────────────────────────────────────────────────────────┐│ │
│ │ │ Checks: ││ │
│ │ │ ☐ Bedrock Agent provisioned ││ │
│ │ │ ☐ Memory configuration enabled ││ │
│ │ │ ☐ Content guardrails active ││ │
│ │ │ ☐ Billing tracking configured ││ │
│ │ │ ☐ Error handling implemented ││ │
│ │ │ ☐ Security compliance verified ││ │
│ │ │ ☐ Documentation complete ││ │
│ │ └─────────────────────────────────────────────────────────────────┘│ │
│ └─────────────────────────────────┬────────────────────────────────────┘ │
│ │ │
│ ┌─────────────┴─────────────┐ │
│ │ Ready to Deploy? │ │
│ └─────────────┬─────────────┘ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Production │ │ AWS │ │ External │ │
│ │ Environment │ │ Marketplace │ │ Systems │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└────────────────────────────────────────────────────────────────────────────────┘
Legacy Agent Compatibility¶
All agents created before this migration continue to work without changes:
| Scenario | Behavior |
|---|---|
| Existing agent, no changes | Runs as INTERNAL type (default) |
Existing agent with bedrock_agent_id |
Can upgrade to BEDROCK_MEMORY |
| New agent | Choose type at creation |
| Migration rollback | Supports full rollback to previous state |
Migration Path for Legacy Agents¶
Legacy Agent (Pre-Migration)
│
▼
┌─────────────────────────────┐
│ Run Migration │
│ agent_type = 'internal' │ ◄── Automatic, no changes needed
│ (Works exactly as before) │
└─────────────────────────────┘
│
│ Optional upgrade
▼
┌─────────────────────────────┐
│ POST /api/agents/audit/ │
│ {agent}/migrate │
│ { "target_type": │
│ "bedrock_memory", │
│ "dry_run": true } │ ◄── Test first with dry_run
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ BEDROCK_MEMORY Type │
│ • Session memory enabled │
│ • 40-60% token savings │
│ • Full backwards compat │
└─────────────────────────────┘
Service Dependencies¶
AgentOrchestrator
├── WorkflowPlanner
├── BrandVoiceContextBuilder
├── CapabilityRegistry
├── AgentMemoryService (optional)
└── AgentExecutionDryRunService (optional)
├── BedrockRuntimeService
├── WorkflowPlanner
├── CapabilityRegistry
└── AgentConfigurationService
AgentAuditController
├── AgentAnalyticsService
├── AgentMigrationService
│ ├── BedrockAgentProvisioningService
│ ├── AgentConfigurationService
│ └── AgentAnalyticsService
├── AgentConfigurationService
└── AgentExecutionDryRunService
Document Version: 2.0 Last Updated: 2026-01-13