# aws/bedrock-agentcore-sdk-python architecture

> Architecture diagram of the GitHub repository aws/bedrock-agentcore-sdk-python, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/bedrock-agentcore-sdk-python
- Repository: https://github.com/aws/bedrock-agentcore-sdk-python

## Overview

Bedrock AgentCore SDK is a Python client and serving layer for deploying agents and composing AgentCore services. Its primary workflow is to register an agent handler with the runtime app, receive an invocation, dispatch it to that handler, and stream the response. Separate SDK modules manage memory, gateway tools, knowledge retrieval, identity, policy, payments, and evaluation. The README documents protocol adapters and platform capabilities, while sampled source confirms selected runtime, client, memory, and evaluation behavior; links among unsampled modules are omitted where their wiring is uncertain.

Main entry points: [`src/bedrock_agentcore/runtime/app.py`](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/app.py) (Runtime app), [`src/bedrock_agentcore/evaluation/client.py`](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/client.py) (Evaluation client), [`src/bedrock_agentcore/runtime/ag_ui.py`](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/ag_ui.py) (AG-UI adapter), [`src/bedrock_agentcore/runtime/a2a.py`](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/a2a.py) (A2A adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_runtime_app["Runtime app<br/>[app.py]"]
  node_agui["AG-UI adapter<br/>[ag_ui.py]"]
  node_a2a["A2A adapter<br/>[a2a.py]"]
  node_runtime_client["Runtime client"]
end

subgraph group_agent_services["Agent Services"]
  node_memory_client["Memory client<br/>[client.py]"]
  node_memory_sessions["Memory sessions<br/>[session_manager.py]"]
  node_gateway_client["Gateway client<br/>[client.py]"]
  node_tool_search["Gateway tool search<br/>[plugin.py]"]
  node_knowledge_client["Knowledge base<br/>[client.py]"]
  node_web_search["Web search tool"]
  node_browser_tool["Browser tool<br/>[browser_client.py]"]
  node_code_tool["Code interpreter"]
end

subgraph group_controls["Controls and Payments"]
  node_identity["Identity auth<br/>[auth.py]"]
  node_policy["Policy client<br/>[client.py]"]
  node_payments["Payment manager<br/>[manager.py]"]
  node_payment_integrations["Payment integrations<br/>[handlers.py]"]
  node_config_bundle["Config bundles<br/>[client.py]"]
end

subgraph group_observability["Evaluation and Tracing"]
  node_evaluation["Evaluation client<br/>[client.py]"]
  node_span_collector["Span collector"]
  node_span_serializer["Span serializer"]
end

node_developer(("Agent developer"))
node_caller(("Agent caller"))
node_framework_agent["Agent handler"]
node_cloudwatch[("CloudWatch")]
node_agentcore_apis["AgentCore APIs"]
node_gateway_endpoint["Gateway MCP endpoint"]

node_developer -->|"registers handler"| node_runtime_app
node_caller -->|"invokes agent"| node_runtime_app
node_runtime_app -->|"dispatches handler"| node_framework_agent
node_framework_agent -->|"streams events"| node_runtime_app
node_runtime_app -->|"returns response"| node_caller
node_developer -.->|"serves AG-UI"| node_agui
node_agui -.->|"adapts protocol"| node_runtime_app
node_developer -.->|"serves A2A"| node_a2a
node_a2a -.->|"adapts protocol"| node_runtime_app
node_runtime_client -->|"invokes runtime"| node_agentcore_apis
node_memory_client -->|"manages memory"| node_agentcore_apis
node_memory_sessions -->|"persists sessions"| node_memory_client
node_gateway_client -->|"manages gateway"| node_agentcore_apis
node_tool_search -->|"discovers tools"| node_gateway_endpoint
node_knowledge_client -->|"manages and retrieves"| node_agentcore_apis
node_web_search -->|"sends MCP requests"| node_gateway_endpoint
node_browser_tool -->|"calls browser service"| node_agentcore_apis
node_code_tool -->|"calls execution service"| node_agentcore_apis
node_identity -->|"handles identity"| node_agentcore_apis
node_policy -->|"manages policies"| node_agentcore_apis
node_payments -->|"processes payments"| node_agentcore_apis
node_payment_integrations -->|"extracts payment data"| node_payments
node_config_bundle -->|"fetches bundles"| node_agentcore_apis
node_evaluation -->|"collects session spans"| node_span_collector
node_span_collector -->|"reads traces"| node_cloudwatch
node_evaluation -->|"runs evaluations"| node_agentcore_apis
node_span_serializer -.->|"formats trace data"| node_cloudwatch

click node_runtime_app "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/app.py"
click node_agui "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/ag_ui.py"
click node_a2a "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/a2a.py"
click node_runtime_client "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/agent_core_runtime_client.py"
click node_memory_client "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/memory/client.py"
click node_memory_sessions "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/memory/integrations/strands/session_manager.py"
click node_gateway_client "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/gateway/client.py"
click node_tool_search "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/gateway/integrations/strands/plugins/agentcore_tool_search/plugin.py"
click node_knowledge_client "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/knowledge_base/client.py"
click node_web_search "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/web_search_client.py"
click node_browser_tool "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/browser_client.py"
click node_code_tool "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/code_interpreter_client.py"
click node_identity "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/identity/auth.py"
click node_policy "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/policy/client.py"
click node_payments "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/payments/manager.py"
click node_payment_integrations "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/payments/integrations/handlers.py"
click node_config_bundle "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/config_bundle/client.py"
click node_evaluation "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/client.py"
click node_span_collector "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/agent_span_collector/agent_span_collector.py"
click node_span_serializer "https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/span_to_adot_serializer/strands_converter.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_runtime_app,node_agui,node_a2a,node_runtime_client toneBlue
class node_memory_client,node_memory_sessions,node_gateway_client,node_tool_search,node_knowledge_client,node_web_search,node_browser_tool,node_code_tool,node_cloudwatch toneAmber
class node_identity,node_policy,node_payments,node_payment_integrations,node_config_bundle,node_framework_agent,node_agentcore_apis toneMint
class node_evaluation,node_span_collector,node_span_serializer toneRose
class node_developer,node_caller,node_gateway_endpoint toneIndigo
```

## Components

### Agent Runtime

- [Runtime app](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/app.py): `src/bedrock_agentcore/runtime/app.py`
- [AG-UI adapter](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/ag_ui.py): `src/bedrock_agentcore/runtime/ag_ui.py`
- [A2A adapter](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/a2a.py): `src/bedrock_agentcore/runtime/a2a.py`
- [Runtime client](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/runtime/agent_core_runtime_client.py): `src/bedrock_agentcore/runtime/agent_core_runtime_client.py`

### Agent Services

- [Memory client](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/memory/client.py): `src/bedrock_agentcore/memory/client.py`
- [Memory sessions](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/memory/integrations/strands/session_manager.py): `src/bedrock_agentcore/memory/integrations/strands/session_manager.py`
- [Gateway client](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/gateway/client.py): `src/bedrock_agentcore/gateway/client.py`
- [Gateway tool search](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/gateway/integrations/strands/plugins/agentcore_tool_search/plugin.py): `src/bedrock_agentcore/gateway/integrations/strands/plugins/agentcore_tool_search/plugin.py`
- [Knowledge base](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/knowledge_base/client.py): `src/bedrock_agentcore/knowledge_base/client.py`
- [Web search tool](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/web_search_client.py): `src/bedrock_agentcore/tools/web_search_client.py`
- [Browser tool](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/browser_client.py): `src/bedrock_agentcore/tools/browser_client.py`
- [Code interpreter](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/tools/code_interpreter_client.py): `src/bedrock_agentcore/tools/code_interpreter_client.py`

### Controls and Payments

- [Identity auth](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/identity/auth.py): `src/bedrock_agentcore/identity/auth.py`
- [Policy client](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/policy/client.py): `src/bedrock_agentcore/policy/client.py`
- [Payment manager](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/payments/manager.py): `src/bedrock_agentcore/payments/manager.py`
- [Payment integrations](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/payments/integrations/handlers.py): `src/bedrock_agentcore/payments/integrations/handlers.py`
- [Config bundles](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/config_bundle/client.py): `src/bedrock_agentcore/config_bundle/client.py`

### Evaluation and Tracing

- [Evaluation client](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/client.py): `src/bedrock_agentcore/evaluation/client.py`
- [Span collector](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/agent_span_collector/agent_span_collector.py): `src/bedrock_agentcore/evaluation/agent_span_collector/agent_span_collector.py`
- [Span serializer](https://github.com/aws/bedrock-agentcore-sdk-python/blob/main/src/bedrock_agentcore/evaluation/span_to_adot_serializer/strands_converter.py): `src/bedrock_agentcore/evaluation/span_to_adot_serializer/strands_converter.py`

### Other components

- **Agent developer**
- **Agent caller**
- **Agent handler**
- **CloudWatch**
- **AgentCore APIs**
- **Gateway MCP endpoint**

## Connections

- Agent developer → Runtime app: registers handler
- Agent caller → Runtime app: invokes agent
- Runtime app → Agent handler: dispatches handler
- Agent handler → Runtime app: streams events
- Runtime app → Agent caller: returns response
- Agent developer → AG-UI adapter: serves AG-UI
- AG-UI adapter → Runtime app: adapts protocol
- Agent developer → A2A adapter: serves A2A
- A2A adapter → Runtime app: adapts protocol
- Runtime client → AgentCore APIs: invokes runtime
- Memory client → AgentCore APIs: manages memory
- Memory sessions → Memory client: persists sessions
- Gateway client → AgentCore APIs: manages gateway
- Gateway tool search → Gateway MCP endpoint: discovers tools
- Knowledge base → AgentCore APIs: manages and retrieves
- Web search tool → Gateway MCP endpoint: sends MCP requests
- Browser tool → AgentCore APIs: calls browser service
- Code interpreter → AgentCore APIs: calls execution service
- Identity auth → AgentCore APIs: handles identity
- Policy client → AgentCore APIs: manages policies
- Payment manager → AgentCore APIs: processes payments
- Payment integrations → Payment manager: extracts payment data
- Config bundles → AgentCore APIs: fetches bundles
- Evaluation client → Span collector: collects session spans
- Span collector → CloudWatch: reads traces
- Evaluation client → AgentCore APIs: runs evaluations
- Span serializer → CloudWatch: formats trace data