# aws-samples/sample-logistics-agent-agentcore-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/aws-samples/sample-logistics-agent-agentcore-runtime
- Repository: https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime

## Overview

This sample deploys a logistics-tracking agent on Amazon Bedrock AgentCore Runtime, connected privately to PostgreSQL in RDS. The principal workflow is a query sent to the runtime, handled by the agent and its shipment tools, then answered using database results and an OpenAI model. The README also documents the VPC/RDS foundation and a helper-instance workflow for loading schema and seed data. Source excerpts show the agent and CDK wiring; CloudFormation relationships below rely on README descriptions, not inspection of template contents.

Main entry points: [`infrastructure/rds-vpc-setup.yaml`](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/rds-vpc-setup.yaml) (Shipment database), [`cdk/app.py`](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/app.py) (CDK app), [`agent/agent.py`](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py) (Strands agent), [`cdk/logistics_agent_runtime_stack.py`](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/logistics_agent_runtime_stack.py) (AgentCore Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_query["Agent query runtime"]
  node_invoker["Invocation client<br/>[invoke_agent.py]"]
  node_runtime["AgentCore Runtime"]
  node_entrypoint["Query entrypoint<br/>[agent.py]"]
  node_agent["Strands agent<br/>[agent.py]"]
  node_tools["Shipment tools<br/>[agent.py]"]
  node_model["OpenAI model<br/>[agent.py]"]
end

subgraph group_data["Shipment data"]
  node_dbconfig["DB configuration<br/>[agent.py]"]
  node_rds[("Shipment database<br/>[rds-vpc-setup.yaml]")]
  node_schema["Database schema<br/>[schema.sql]"]
  node_seed["Shipment seed data<br/>[seed_data.sql]"]
end

subgraph group_deployment["AWS infrastructure"]
  node_ssm[("Parameter Store")]
  node_secrets[("Secrets Manager")]
  node_helper["DB setup helper"]
  node_vpc["Private network<br/>[rds-vpc-setup.yaml]"]
  node_cdkapp["CDK app<br/>[app.py]"]
end

node_user(("User"))
node_openai["OpenAI API"]

node_user -->|"submits query"| node_invoker
node_invoker -->|"invokes"| node_runtime
node_runtime -->|"runs agent code"| node_entrypoint
node_entrypoint -->|"executes query"| node_agent
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"uses model"| node_model
node_model -->|"loads API key"| node_secrets
node_model -->|"sends model requests"| node_openai
node_tools -->|"opens connection"| node_dbconfig
node_dbconfig -->|"reads parameters"| node_ssm
node_dbconfig -->|"loads credentials"| node_secrets
node_tools -->|"queries shipments"| node_rds
node_vpc -->|"hosts privately"| node_rds
node_helper -->|"loads schema"| node_schema
node_helper -->|"loads seed data"| node_seed
node_schema -->|"defines tables"| node_rds
node_seed -->|"populates data"| node_rds
node_cdkapp -->|"creates stack"| node_runtime
node_cdkapp -->|"receives network IDs"| node_vpc
node_cdkapp -->|"receives DB secret ARN"| node_rds

click node_invoker "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/invoke_agent.py"
click node_runtime "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/logistics_agent_runtime_stack.py"
click node_entrypoint "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py"
click node_agent "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py"
click node_tools "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py"
click node_model "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py"
click node_dbconfig "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py"
click node_rds "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/rds-vpc-setup.yaml"
click node_schema "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/schema.sql"
click node_seed "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/seed_data.sql"
click node_helper "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/db-setup-helper.yaml"
click node_vpc "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/rds-vpc-setup.yaml"
click node_cdkapp "https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/app.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_invoker,node_runtime,node_entrypoint,node_agent,node_tools,node_model,node_user toneBlue
class node_dbconfig,node_rds,node_schema,node_seed toneAmber
class node_ssm,node_secrets,node_helper,node_vpc,node_cdkapp,node_openai toneMint
```

## Components

### Agent query runtime

- [Invocation client](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/invoke_agent.py): `cdk/invoke_agent.py`
- [AgentCore Runtime](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/logistics_agent_runtime_stack.py): `cdk/logistics_agent_runtime_stack.py`
- [Query entrypoint](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py): `agent/agent.py`
- [Strands agent](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py): `agent/agent.py`
- [Shipment tools](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py): `agent/agent.py`
- [OpenAI model](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py): `agent/agent.py`

### Shipment data

- [DB configuration](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/agent/agent.py): `agent/agent.py`
- [Shipment database](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/rds-vpc-setup.yaml): `infrastructure/rds-vpc-setup.yaml`
- [Database schema](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/schema.sql): `infrastructure/schema.sql`
- [Shipment seed data](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/seed_data.sql): `infrastructure/seed_data.sql`

### AWS infrastructure

- **Parameter Store**
- **Secrets Manager**
- [DB setup helper](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/db-setup-helper.yaml): `infrastructure/db-setup-helper.yaml`
- [Private network](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/infrastructure/rds-vpc-setup.yaml): `infrastructure/rds-vpc-setup.yaml`
- [CDK app](https://github.com/aws-samples/sample-logistics-agent-agentcore-runtime/blob/main/cdk/app.py): `cdk/app.py`

### Other components

- **User**
- **OpenAI API**

## Connections

- User → Invocation client: submits query (evidence: `cdk/invoke_agent.py`)
- Invocation client → AgentCore Runtime: invokes (evidence: `cdk/invoke_agent.py`)
- AgentCore Runtime → Query entrypoint: runs agent code (evidence: `cdk/logistics_agent_runtime_stack.py`)
- Query entrypoint → Strands agent: executes query (evidence: `agent/agent.py`)
- Strands agent → Shipment tools: dispatches tools (evidence: `agent/agent.py`)
- Strands agent → OpenAI model: uses model (evidence: `agent/agent.py`)
- OpenAI model → Secrets Manager: loads API key (evidence: `agent/agent.py`)
- OpenAI model → OpenAI API: sends model requests (evidence: `agent/agent.py`)
- Shipment tools → DB configuration: opens connection (evidence: `agent/agent.py`)
- DB configuration → Parameter Store: reads parameters (evidence: `agent/agent.py`)
- DB configuration → Secrets Manager: loads credentials (evidence: `agent/agent.py`)
- Shipment tools → Shipment database: queries shipments (evidence: `agent/agent.py`)
- Private network → Shipment database: hosts privately (evidence: `README.md`)
- DB setup helper → Database schema: loads schema (evidence: `README.md`)
- DB setup helper → Shipment seed data: loads seed data (evidence: `README.md`)
- Database schema → Shipment database: defines tables (evidence: `README.md`)
- Shipment seed data → Shipment database: populates data (evidence: `README.md`)
- CDK app → AgentCore Runtime: creates stack (evidence: `cdk/app.py`)
- CDK app → Private network: receives network IDs (evidence: `cdk/app.py`)
- CDK app → Shipment database: receives DB secret ARN (evidence: `cdk/app.py`)
