# awslabs/amazon-bedrock-agent-samples architecture

> Architecture diagram of the GitHub repository awslabs/amazon-bedrock-agent-samples, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/amazon-bedrock-agent-samples
- Repository: https://github.com/awslabs/amazon-bedrock-agent-samples

## Overview

##### Project Type and Purpose
- This is an open-source sample repository showcasing Amazon Bedrock Agents in both single-agent and multi-agent collaboration scenarios.
- It provides:
- “examples/…”—dozens of ready-to-run demos (Python scripts, Jupyter notebooks, CDK/CloudFormation templates, React/Streamlit UIs)
- A core Python library “src/InlineAgent” for building inline and multi-agent workflows
- Reusable modules in “src/shared” (Action Groups, web-search, working memory, stock data)
- Utility wrappers in “src/utils” abstracting boto3 calls to Bedrock and other AWS services

##### Directory-Based Architectural Insights
- examples/agents & examples/multi_agent_collaboration: Presentation layer (scripts, notebooks) that drive various agent flows
- examples/agents_ux: UI demos (Streamlit, Flask, React via AWS Amplify)
- examples/sdk: Lambda-based SDK usage samples
- src/InlineAgent: Core library implementing agent orchestration (inline_agent, action_group, observability hooks, confirmation, ROC processing)
- src/shared: Packaged Action Groups deployed as AWS Lambda/Step Functions via CDK/CloudFormation
- src/utils: Higher-level Bedrock Agent helpers, knowledge base loaders, instrumentation wrappers

##### README Architecture Highlights
- Architecture.gif shows: Client apps → InlineAgent library → AWS Bedrock Agent API → Action Groups (Lambda) → Data stores/External APIs → Observability
- The README calls out: Boto3 SDK, AWS CDK (TypeScript & Python), multi-agent supervisor/routing modes, guardrails, traces

a. Main Components
- Developer Environment: IDE/CLI, Jupyter notebooks, Streamlit/Flask UIs, React front-end
- Example Drivers: Python scripts & notebooks under examples/agents & examples/multi_agent_collaboration
- Core Library: InlineAgent package (agent orchestration, confirmation, ROC processing, observability hooks)
- Shared Modules (Action Groups): Packaged Lambda functions & Step Functions in src/shared
- Utility Layer: src/utils for Bedrock Agent and knowledge base interactions
- AWS Cloud:
- Amazon Bedrock Agents API
- AWS Lambda & Step Functions (Action Groups)
- AWS CDK/CloudFormation stacks (in examples & src/shared/cfn_stacks)
- Data Stores: S3, Athena, DynamoDB, ClickHouse (in ECS Fargate example)
- Observability: OpenTelemetry agent, AWS X-Ray or custom trace provider
- Front-end Hosting: AWS Amplify, ECS Fargate, API Gateway
- External Services: Web search APIs, third-party services invoked via Action Groups

b. Component Interactions
1. Client/UI (notebook, Streamlit, React) invokes Example Driver
2. Example Driver imports & configures InlineAgent library
3. InlineAgent orchestrates calls to AWS Bedrock Agent via src/utils/bedrock_agent.py
4. InlineAgent routes to one or more Action Groups (Lambda or Step Functions) in src/shared
5. Action Groups perform tasks (web search, memory lookup, stock data) and return to agent
6. InlineAgent collects results, applies guardrails/confirmations, builds responses
7. Observability module instruments each call, emits spans/traces to OpenTelemetry collector
8. In multi-agent mode, a “supervisor agent” coordinates multiple agent roles via Bedrock routing API

c. Architectural Patterns and Principles
- Layered architecture: Presentation → Orchestration (InlineAgent) → Infrastructure as Code → Platform Services
- Modular “Action Group” pattern: discrete, deployable Lambda/Step Functions for extensibility
- Dependency inversion: high-level agent code depends on abstractions (src/utils, shared plugins)
- Infrastructure as code with CDK/CloudFormation templates next to examples for reproducibility
- Observability built-in: OpenTelemetry instrumentation within InlineAgent and Agent handlers

d. Key Technologies and Frameworks
- Python ecosystem: boto3, lambda, streamlit, flask, unittest/pytest
- AWS CDK (TypeScript & Python) & CloudFormation
- AWS Services: Bedrock Agent, Lambda, Step Functions, S3, Athena, DynamoDB, ECS Fargate, API Gateway, Amplify, X-Ray
- OpenTelemetry for agent instrumentation
- React + AWS Amplify for UX demos

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Examples Layer
    subgraph "Examples (Green)" 
        direction TB
        EX1["Single-Agent Drivers\n(examples/agents)"]:::green
        EX2["Multi-Agent Drivers\n(examples/multi_agent_collaboration)"]:::green
        EX3["UI Demos\n(examples/agents_ux)"]:::green
        EX4["SDK Samples\n(examples/sdk)"]:::green
    end

    %% Core Library
    subgraph "Core InlineAgent Library (Blue)"
        direction TB
        CORE["src/InlineAgent"]:::blue
        subgraph Modules
            direction TB
            AG["Action Group Module"]:::blue
            OL["Orchestration & Agent Logic"]:::blue
            ROC["ROC Processing"]:::blue
            CONF["Confirmation Hooks"]:::blue
            OBS["Observability Instrumentation"]:::blue
            UTIL_CORE["Core Utils"]:::blue
        end
    end

    %% Utility Layer
    UTIL["Utility Wrappers\n(src/utils)"]:::blue

    %% Shared Action Groups
    subgraph "Shared Action Groups (Orange)"
        direction TB
        WS["Web Search"]:::orange
        WM["Working Memory"]:::orange
        SD["Stock Data"]:::orange
        ED["Economic Data"]:::orange
        PD["Property Data"]:::orange
    end

    %% AWS Backend
    subgraph "AWS Services (Purple)"
        direction TB
        BEDROCK["Amazon Bedrock Agent API"]:::purple
        LAMBDA["AWS Lambda & Step Functions"]:::purple
        subgraph "Data Stores"
            direction TB
            S3["S3"]:::purple
            ATH["Athena"]:::purple
            DDB["DynamoDB"]:::purple
            CH["ClickHouse"]:::purple
        end
        APIGW["API Gateway / Amplify"]:::purple
        OTEL["OpenTelemetry Collector"]:::purple
        XRAY["X-Ray / CloudWatch"]:::purple
    end

    %% External Services
    EXT["External Web Search API"]:::gray

    %% Flows
    EX1 -->|drives| CORE
    EX2 -->|drives| CORE
    EX3 -->|drives| CORE
    EX4 -->|drives| CORE

    CORE -->|calls| UTIL
    CORE -->|invokes| BEDROCK
    UTIL -->|boto3 calls| BEDROCK

    CORE -->|routes to| WS
    CORE -->|routes to| WM
    CORE -->|routes to| SD
    CORE -->|routes to| ED
    CORE -->|routes to| PD

    WS -->|performs| LAMBDA
    WM -->|performs| LAMBDA
    SD -->|performs| LAMBDA
    ED -->|performs| LAMBDA
    PD -->|performs| LAMBDA

    LAMBDA --> S3
    LAMBDA --> ATH
    LAMBDA --> DDB
    LAMBDA --> CH

    CORE -->|emits traces| OTEL
    OTEL --> XRAY

    WS --> EXT

    %% Return flow
    CORE -->|responds| EX1
    CORE -->|responds| EX2
    CORE -->|responds| EX3
    CORE -->|responds| EX4

    %% Click Events
    click EX1 "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/examples/agents"
    click EX2 "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/examples/multi_agent_collaboration"
    click EX3 "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/examples/agents_ux"
    click EX4 "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/examples/sdk"
    click CORE "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/InlineAgent/src/InlineAgent"
    click AG "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/InlineAgent/src/InlineAgent/action_group/action_group.py"
    click OL "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/InlineAgent/src/InlineAgent/agent/inline_agent.py"
    click ROC "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/InlineAgent/src/InlineAgent/agent/process_roc.py"
    click CONF "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/InlineAgent/src/InlineAgent/agent/confirmation.py"
    click OBS "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/InlineAgent/src/InlineAgent/observability"
    click UTIL_CORE "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/InlineAgent/src/InlineAgent/utils.py"
    click UTIL "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/utils/bedrock_agent.py"
    click UTIL "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/utils/bedrock_agent_helper.py"
    click UTIL "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/utils/knowledge_base_helper.py"
    click WS "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/shared/web_search"
    click WM "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/shared/working_memory"
    click SD "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/shared/stock_data"
    click ED "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/shared/economic_data"
    click PD "https://github.com/awslabs/amazon-bedrock-agent-samples/tree/main/src/shared/property_data"
    click WS "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/shared/web_search/cfn_stacks/web_search_stack.yaml"
    click WM "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/shared/working_memory/cfn_stacks/working_memory_stack.yaml"
    click SD "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/shared/stock_data/cfn_stacks/stock_data_stack.yaml"
    click ED "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/shared/economic_data/cfn_stacks/economic_data_stack.yaml"
    click PD "https://github.com/awslabs/amazon-bedrock-agent-samples/blob/main/src/shared/property_data/cfn_stacks/property_data_stack.yaml"

    %% Styles
    classDef green fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32,stroke-width:1px;
    classDef blue fill:#e3f2fd,stroke:#1565c0,color:#1565c0,stroke-width:1px;
    classDef orange fill:#fff3e0,stroke:#ef6c00,color:#ef6c00,stroke-width:1px;
    classDef purple fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a,stroke-width:1px;
    classDef gray fill:#eceff1,stroke:#607d8b,color:#607d8b,stroke-width:1px;
```
