# strands-agents/sdk-typescript architecture

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

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

## Overview

Strands Agents is a TypeScript SDK for building and running model-driven agents. Its principal workflow accepts a user request, manages conversation context, invokes a configured model, executes requested tools, and returns a result; streaming exposes intermediate events. The SDK also provides structured output, MCP tools, conversation strategies, multi-agent orchestration, persistence, lifecycle extensions, and A2A serving. The graph combines README-documented capabilities with sampled source; unsampled modules are included only where the tree and README establish their role, so uncertain internal call wiring is omitted.

Main entry points: [`strands-ts/src/agent/agent.ts`](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/agent/agent.ts) (Agent Loop), [`strands-ts/src/tools/tool.ts`](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/tools/tool.ts) (Tool Runtime), [`strands-ts/src/session/storage.ts`](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/storage.ts) (Snapshot Storage), [`strands-ts/src/models/model.ts`](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/model.ts) (Model Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent Runtime"]
  node_agent["Agent Loop<br/>[agent.ts]"]
  node_conversation["Conversation History"]
  node_model["Model Providers<br/>[model.ts]"]
  node_bedrock["Bedrock Provider<br/>[bedrock.ts]"]
  node_openai["OpenAI Provider<br/>[model.ts]"]
  node_streaming["Streaming Events<br/>[streaming.ts]"]
  node_tools["Tool Runtime<br/>[tool.ts]"]
  node_structured["Structured Output"]
end

subgraph group_extensions["Agent Extensions"]
  node_mcp["MCP Client<br/>[mcp.ts]"]
  node_vendedtools["Vended Tools<br/>[index.ts]"]
  node_hooks["Lifecycle Hooks<br/>[registry.ts]"]
  node_plugins["Plugins<br/>[registry.ts]"]
  node_telemetry["Telemetry<br/>[index.ts]"]
  node_sandbox["Sandbox<br/>[base.ts]"]
end

subgraph group_coordination["Agent Coordination"]
  node_multiagent["Multi-Agent<br/>[multiagent.ts]"]
  node_graphswarm["Graph and Swarm<br/>[index.ts]"]
end

subgraph group_state["State and Context"]
  node_session["Session Manager<br/>[session-manager.ts]"]
  node_snapshot["Snapshot Storage<br/>[storage.ts]"]
  node_filestorage["File Storage<br/>[file-storage.ts]"]
  node_s3storage["S3 Storage<br/>[s3-storage.ts]"]
end

subgraph group_interfaces["External Interfaces"]
  node_a2a["A2A Server<br/>[server.ts]"]
end

node_user(("User"))
node_modelservice(("Model Service"))
node_externaltools(("External Tools"))
node_s3[("Amazon S3")]

node_user -->|"submits request"| node_agent
node_agent -->|"manages context"| node_conversation
node_agent -->|"requests response"| node_model
node_model -.->|"calls provider"| node_modelservice
node_bedrock -.->|"calls Bedrock"| node_modelservice
node_openai -.->|"calls OpenAI"| node_modelservice
node_agent -->|"executes requested tools"| node_tools
node_tools -.->|"performs actions"| node_externaltools
node_agent -->|"emits events"| node_streaming
node_agent -->|"validates output"| node_structured
node_agent -->|"dispatches lifecycle"| node_hooks
node_agent -->|"uses extensions"| node_plugins
node_agent -->|"coordinates agents"| node_multiagent
node_multiagent -->|"uses patterns"| node_graphswarm
node_a2a -->|"dispatches requests"| node_agent
node_agent -->|"persists session state"| node_session
node_session -->|"uses snapshot backend"| node_snapshot
node_snapshot -->|"implemented by"| node_filestorage
node_snapshot -->|"implemented by"| node_s3storage
node_s3storage -.->|"reads and writes"| node_s3
node_agent -->|"reports activity"| node_telemetry
node_tools -->|"supports MCP tools"| node_mcp
node_tools -->|"supports built-ins"| node_vendedtools
node_vendedtools -.->|"executes in"| node_sandbox

click node_agent "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/agent/agent.ts"
click node_conversation "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/conversation-manager/conversation-manager.ts"
click node_model "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/model.ts"
click node_bedrock "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/bedrock.ts"
click node_openai "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/openai/model.ts"
click node_streaming "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/streaming.ts"
click node_tools "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/tools/tool.ts"
click node_structured "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/tools/structured-output-tool.ts"
click node_mcp "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/mcp.ts"
click node_vendedtools "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/vended-tools/index.ts"
click node_hooks "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/hooks/registry.ts"
click node_plugins "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/plugins/registry.ts"
click node_multiagent "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/multiagent/multiagent.ts"
click node_graphswarm "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/multiagent/index.ts"
click node_a2a "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/a2a/server.ts"
click node_session "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/session-manager.ts"
click node_snapshot "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/storage.ts"
click node_filestorage "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/file-storage.ts"
click node_s3storage "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/s3-storage.ts"
click node_telemetry "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/telemetry/index.ts"
click node_sandbox "https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/sandbox/base.ts"

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_agent,node_conversation,node_model,node_bedrock,node_openai,node_streaming,node_tools,node_structured,node_user toneBlue
class node_mcp,node_vendedtools,node_hooks,node_plugins,node_telemetry,node_sandbox,node_s3 toneAmber
class node_multiagent,node_graphswarm toneMint
class node_session,node_snapshot,node_filestorage,node_s3storage toneRose
class node_a2a,node_modelservice,node_externaltools toneIndigo
```

## Components

### Agent Runtime

- [Agent Loop](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/agent/agent.ts): `strands-ts/src/agent/agent.ts`
- [Conversation History](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/conversation-manager/conversation-manager.ts): `strands-ts/src/conversation-manager/conversation-manager.ts`
- [Model Providers](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/model.ts): `strands-ts/src/models/model.ts`
- [Bedrock Provider](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/bedrock.ts): `strands-ts/src/models/bedrock.ts`
- [OpenAI Provider](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/openai/model.ts): `strands-ts/src/models/openai/model.ts`
- [Streaming Events](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/models/streaming.ts): `strands-ts/src/models/streaming.ts`
- [Tool Runtime](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/tools/tool.ts): `strands-ts/src/tools/tool.ts`
- [Structured Output](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/tools/structured-output-tool.ts): `strands-ts/src/tools/structured-output-tool.ts`

### Agent Extensions

- [MCP Client](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/mcp.ts): `strands-ts/src/mcp.ts`
- [Vended Tools](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/vended-tools/index.ts): `strands-ts/src/vended-tools/index.ts`
- [Lifecycle Hooks](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/hooks/registry.ts): `strands-ts/src/hooks/registry.ts`
- [Plugins](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/plugins/registry.ts): `strands-ts/src/plugins/registry.ts`
- [Telemetry](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/telemetry/index.ts): `strands-ts/src/telemetry/index.ts`
- [Sandbox](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/sandbox/base.ts): `strands-ts/src/sandbox/base.ts`

### Agent Coordination

- [Multi-Agent](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/multiagent/multiagent.ts): `strands-ts/src/multiagent/multiagent.ts`
- [Graph and Swarm](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/multiagent/index.ts): `strands-ts/src/multiagent/index.ts`

### State and Context

- [Session Manager](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/session-manager.ts): `strands-ts/src/session/session-manager.ts`
- [Snapshot Storage](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/storage.ts): `strands-ts/src/session/storage.ts`
- [File Storage](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/file-storage.ts): `strands-ts/src/session/file-storage.ts`
- [S3 Storage](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/session/s3-storage.ts): `strands-ts/src/session/s3-storage.ts`

### External Interfaces

- [A2A Server](https://github.com/strands-agents/sdk-typescript/blob/main/strands-ts/src/a2a/server.ts): `strands-ts/src/a2a/server.ts`

### Other components

- **User**
- **Model Service**
- **External Tools**
- **Amazon S3**

## Connections

- User → Agent Loop: submits request
- Agent Loop → Conversation History: manages context
- Agent Loop → Model Providers: requests response
- Model Providers → Model Service: calls provider
- Bedrock Provider → Model Service: calls Bedrock
- OpenAI Provider → Model Service: calls OpenAI
- Agent Loop → Tool Runtime: executes requested tools
- Tool Runtime → External Tools: performs actions
- Agent Loop → Streaming Events: emits events
- Agent Loop → Structured Output: validates output
- Agent Loop → Lifecycle Hooks: dispatches lifecycle
- Agent Loop → Plugins: uses extensions
- Agent Loop → Multi-Agent: coordinates agents
- Multi-Agent → Graph and Swarm: uses patterns
- A2A Server → Agent Loop: dispatches requests
- Agent Loop → Session Manager: persists session state
- Session Manager → Snapshot Storage: uses snapshot backend
- Snapshot Storage → File Storage: implemented by
- Snapshot Storage → S3 Storage: implemented by
- S3 Storage → Amazon S3: reads and writes
- Agent Loop → Telemetry: reports activity
- Tool Runtime → MCP Client: supports MCP tools
- Tool Runtime → Vended Tools: supports built-ins
- Vended Tools → Sandbox: executes in