# strands-agents/samples architecture

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

- Interactive diagram: https://gitdiagram.com/strands-agents/samples
- Repository: https://github.com/strands-agents/samples

## Overview

##### Project Type & Purpose
- This is a “sample-code monorepo” showcasing how to build AI agents using the Strands Agents Python SDK.
- It contains:
– “01-getting-started/…”: notebook-driven tutorials (agent basics, AWS integration, guardrails, streaming, deployment).
– “02-samples/…”: standalone Python apps illustrating real-world use cases.
– Top-level infra: AWS CDK apps for Lambda and Fargate deployment.

##### File Structure
- Top-level:
– README, LICENSE, CONTRIBUTING, requirements.txt
- 01-getting-started: numbered tutorial folders, each with notebooks, helper scripts (cleanup, deploy_prereqs), and “prereqs” subfolders that contain Python scripts to seed DynamoDB, document files, and YAML configs.
- 02-samples: independent sample apps, each with a README, .env examples, Python source, utility modules, and requirements or pyproject files.
- Deployment patterns:
– 11-lambda-deployment & 12-fargate-deployment: AWS CDK in TypeScript, Dockerfiles, agent requirements, CloudFormation stacks.

##### README
- The project is a **demo repo** for the Strands Agents SDK.
- It links out to documentation, shows how to install the SDK, pick a model provider, build agents in four lines of code, and then explore tutorials or samples.

a. Main Components
1. Developer Workstation
- Jupyter Notebook Interface (for 01-getting-started)
- CLI / Python runtimes (for 02-samples apps)
2. Strands Agents Python SDK
- Core Agent engine
- Tool registry (calculator, current_time, python_repl, custom tools, knowledge_base scripts)
3. Model Provider Endpoint
- OpenAI API
- Ollama or other local LLM providers
4. External Services & Data Stores
- AWS DynamoDB (knowledge base)
- Optionally S3, other AWS services used in guardrails or observability
5. Deployment Infrastructure
- AWS CDK (TypeScript)
– Lambda stack (11-lambda-deployment)
– Fargate/ECS stack (12-fargate-deployment)
- Docker container for agent runtime (Fargate / Lambda)
6. Sample Application Layer
- Restaurant assistant, Scrum-master assistant, AWS-cost assistant, etc., each a standalone Python service

b. Relationships & Data Flows
1. Developer triggers Notebook or runs CLI script →
2. Notebook/Script calls the Agent API (Strands Agents SDK) →
3. Agent orchestrates:
– Sends prompt to Model Provider (HTTP request)
– Receives response (JSON containing next action or tool call)
– If tool call: invokes a local Python function or AWS service
- e.g., knowledge_base.py writes/reads DynamoDB
- calculator/current_time/python_repl run locally
– Loops until final answer, returns to user
4. For deployed scenarios:
– AWS CDK provisions DynamoDB, IAM roles, Lambda function or ECS service
– Docker image (with Strands Agents & prerequisites) is pushed to ECR
– Event/API Gateway triggers Lambda or directs traffic to Fargate
– The hosted agent runs the same call flow as above

c. Architectural Patterns & Principles
- Modular SDK + plugin tools (tool registry pattern)
- Notebook-driven learning path + standalone samples
- Infrastructure as Code (IaC) with AWS CDK
- Cloud-native deployments: serverless (Lambda) or container-based (Fargate)
- Separation of concerns:
– Agent orchestration vs. tool execution
– Core SDK vs. example code vs. deployment code

d. Key Technologies & Frameworks
- Python, Jupyter notebooks
- strands-agents (Python SDK)
- strands-agents-tools (prebuilt tools)
- AWS CDK (TypeScript)
- Docker, ECS Fargate, AWS Lambda, DynamoDB
- Model providers: OpenAI, Ollama, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        Notebook["Notebook Tutorials\n(01-01…01-15)"]:::compute
        CLI["Standalone Sample Apps"]:::compute
    end

    %% Sample Applications
    subgraph "Sample Apps"
        RestApp["Restaurant Assistant"]:::compute
        ScrumApp["Scrum-Master Assistant"]:::compute
        CostApp["AWS-Cost Assistant"]:::compute
        StartApp["Startup Advisor"]:::compute
    end

    %% SDK & Runtime
    subgraph "Strands Agents SDK & Runtime"
        SDK["Strands Agents SDK"]:::compute
        ToolRegistry["Tool Registry"]:::compute
    end

    %% Prereqs Scripts
    subgraph "Prereqs Scripts"
        DynSeed["DynamoDB Seeding Script"]:::compute
        KBTool["Knowledge-Base Tool"]:::compute
    end

    %% Model Providers
    subgraph "Model Provider"
        OpenAI["OpenAI API"]:::service
        Ollama["Ollama / Local LLM"]:::service
    end

    %% External Services & Data Stores
    subgraph "External Services & Data Stores"
        DynamoDB["DynamoDB Table"]:::storage
        S3["S3 Bucket"]:::storage
    end

    %% Deployment Infrastructure
    subgraph "Deployment Infrastructure"
        CDK["AWS CDK IaC"]:::infra
        LambdaStack["Lambda Stack"]:::infra
        FargateStack["Fargate Stack"]:::infra
        DockerLambda["Lambda Docker Image"]:::infra
        DockerFargate["Fargate Docker Image"]:::infra
        ECR["ECR"]:::storage
        API["API Gateway / Load Balancer"]:::infra
    end

    %% Relationships
    Notebook -->|runs| SDK
    CLI -->|executes| SDK
    CLI --> RestApp
    CLI --> ScrumApp
    CLI --> CostApp
    CLI --> StartApp

    SDK -->|calls| OpenAI
    SDK -->|calls| Ollama
    SDK -->|uses| ToolRegistry

    ToolRegistry -->|invokes| DynSeed
    ToolRegistry -->|invokes| KBTool
    ToolRegistry -->|queries| DynamoDB
    ToolRegistry -->|stores| DynamoDB
    ToolRegistry -->|uses| S3

    CDK -->|provisions| DynamoDB
    CDK -->|provisions| LambdaStack
    CDK -->|provisions| FargateStack

    DockerLambda -->|pushes| ECR
    DockerFargate -->|pushes| ECR

    ECR -->|triggers| LambdaStack
    ECR -->|triggers| FargateStack

    API -->|routes| LambdaStack
    API -->|routes| FargateStack

    LambdaStack -->|runs| SDK
    FargateStack -->|runs| SDK

    %% Click Events
    click Notebook "https://github.com/strands-agents/samples/tree/main/01-getting-started/"
    click CLI "https://github.com/strands-agents/samples/tree/main/02-samples/"
    click DynSeed "https://github.com/strands-agents/samples/blob/main/01-getting-started/01-connecting-with-aws-services/prereqs/dynamodb.py"
    click KBTool "https://github.com/strands-agents/samples/blob/main/01-getting-started/01-connecting-with-aws-services/prereqs/knowledge_base.py"
    click CDK "https://github.com/strands-agents/samples/tree/main/01-getting-started/11-lambda-deployment/cdk/"
    click LambdaStack "https://github.com/strands-agents/samples/blob/main/01-getting-started/11-lambda-deployment/cdk/stacks/strands-lambda-stack.ts"
    click DockerLambda "https://github.com/strands-agents/samples/tree/main/01-getting-started/11-lambda-deployment/cdk/lambda/Dockerfile"
    click FargateStack "https://github.com/strands-agents/samples/tree/main/01-getting-started/12-fargate-deployment/cdk/"
    click DockerFargate "https://github.com/strands-agents/samples/tree/main/01-getting-started/12-fargate-deployment/docker/Dockerfile"
    click RestApp "https://github.com/strands-agents/samples/blob/main/02-samples/01-restaurant-assistant/restaurant-assistant.ipynb"
    click ScrumApp "https://github.com/strands-agents/samples/blob/main/02-samples/02-scrum-master-assistant/jira_assistant.py"
    click CostApp "https://github.com/strands-agents/samples/blob/main/02-samples/03-aws-assistant-mcp/aws_cost_assistant.py"
    click StartApp "https://github.com/strands-agents/samples/blob/main/02-samples/04-startup-advisor-mcp/main.py"

    %% Styles
    classDef compute fill:#e0f7fa,stroke:#006064,color:#006064
    classDef service fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef storage fill:#f1f8e9,stroke:#558b2f,color:#558b2f
    classDef infra fill:#fff3e0,stroke:#ef6c00,color:#e65100
```
