# strands-agents/agent-builder architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Python-based command-line toolkit (“Strands Agent Builder”) for interactively creating, testing, and extending AI agents and tools from the terminal.
- It orchestrates multiple components: a CLI front end, a core agent-builder library, a pluggable model-provider layer (Bedrock, Ollama, custom), a set of built-in tools, and integration with external services (AWS Bedrock Knowledge Bases, Ollama, etc.).

##### File Structure Breakdown
- Top-level: configuration files (.gitignore, pyproject.toml, .prompt, README, license).
- src/strands_agents_builder:
- handlers/ — streaming callback and event handling (callback_handler.py)
- models/ — abstractions for model providers (bedrock.py, ollama.py)
- strands.py — core agent-builder logic and orchestration
- utils/ — utility modules (kb_utils for knowledge-base, model_utils for provider configuration, welcome_utils for onboarding)
- tools/ — standalone tool modules (rich_interface, store_in_kb, strand, welcome) that get dynamically loaded into agents
- tests/ — coverage for all components

##### README Insights
- CLI entrypoint “strands” with interactive and non-interactive modes
- Built-in tools (shell, editor, http_request, python_repl, calculator, retrieve, store_in_kb, load_tool, environment, strands, dialog, use_aws)
- Knowledge-base integration via AWS Bedrock KB and persistence
- Nested sub-agent creation via the strands tool
- Pluggable model providers with optimized defaults

##### Main Components
a. CLI Interface
- “strands” command (argument parser) / .prompt loader / environment-var config
b. Core Application Layer
- StrandsAgentBuilder (strands.py): receives user input, selects system prompt, orchestrates tools and providers
- CallbackHandler: streams model tokens back to UI
- Utility modules: kb_utils, model_utils, welcome_utils
c. Tooling Subsystem
- Dynamic registry of built-in tools under tools/ (rich_interface, strand, etc.)
- Plugin loading mechanism in core
d. Model Provider Layer
- BedrockProvider: boto3 client to AWS Bedrock & Knowledge Base
- OllamaProvider: local LLM interface
- Custom providers via .models directory extension
e. External Services
- AWS Bedrock Model API & Knowledge Base
- Ollama local or containerized LLM
f. Terminal I/O Layer
- Rich output interface (rich library)
- Standard input/output streams

##### Relationships and Data Flow
1. User ➔ CLI Parser (“strands” command)
2. CLI Parser ➔ Core (StrandsAgentBuilder)
3. Core ➔ Load system prompt (.prompt / env vars)
4. Core ➔ model_utils to configure selected provider
5. Core ➔ instantiate Provider (Bedrock or Ollama)
6. Core ➔ register Tools (dynamic plugin loader)
7. Core ➔ call Provider.generate() with callbacks
8. Provider ➔ External API (AWS or Ollama)
9. External API ➔ streaming tokens back ➔ CallbackHandler
10. CallbackHandler ➔ RichInterface ➔ User’s terminal

##### Architectural Patterns and Principles
- Plugin architecture: dynamic tool loading & pluggable model providers
- Separation of concerns: CLI parsing, core orchestration, model communication, tool execution
- Builder/orchestrator pattern for agent construction (nested agents supported)
- Streaming callbacks for low-latency user feedback

##### Must‐Include Elements
- Component labels and brief descriptions

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Layer
    User["User"]:::external

    %% Configuration Inputs
    SystemPrompt[".prompt"]:::config
    EnvConfig["pyproject.toml"]:::config

    %% CLI Layer
    CLI["CLI Parser\n(strands command)"]:::internal
    click CLI "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/strands.py"

    %% Core Layer
    StrandsCore["StrandsAgentBuilder\n(core orchestrator)"]:::internal
    click StrandsCore "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/strands.py"

    %% Utilities
    subgraph "Utility Modules"
        KBUtils["kb_utils\n(AWS KB integration)"]:::internal
        click KBUtils "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/utils/kb_utils.py"
        ModelUtils["model_utils\n(provider config)"]:::internal
        click ModelUtils "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/utils/model_utils.py"
        WelcomeUtils["welcome_utils\n(onboarding)"]:::internal
        click WelcomeUtils "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/utils/welcome_utils.py"
    end

    %% Handlers
    CallbackHandler["CallbackHandler\n(stream tokens)"]:::internal
    click CallbackHandler "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/handlers/callback_handler.py"

    %% Tooling Subsystem
    subgraph "Tooling Subsystem"
        RichInterface["RichInterface Tool\n(terminal rendering)"]:::io
        click RichInterface "https://github.com/strands-agents/agent-builder/blob/main/tools/rich_interface.py"
        StoreInKB["StoreInKB Tool\n(store to KB)"]:::internal
        click StoreInKB "https://github.com/strands-agents/agent-builder/blob/main/tools/store_in_kb.py"
        StrandTool["Strand Tool\n(nested-agent)"]:::internal
        click StrandTool "https://github.com/strands-agents/agent-builder/blob/main/tools/strand.py"
        WelcomeTool["Welcome Tool\n(interactive)"]:::internal
        click WelcomeTool "https://github.com/strands-agents/agent-builder/blob/main/tools/welcome.py"
    end

    %% Model Providers
    subgraph "Model Provider Layer"
        BedrockProvider["BedrockProvider\n(AWS Bedrock & KB client)"]:::internal
        click BedrockProvider "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/models/bedrock.py"
        OllamaProvider["OllamaProvider\n(local LLM)"]:::internal
        click OllamaProvider "https://github.com/strands-agents/agent-builder/blob/main/src/strands_agents_builder/models/ollama.py"
    end

    %% External Services
    AWSModel["AWS Bedrock API"]:::external
    AWSKB["AWS Bedrock Knowledge Base"]:::db
    OllamaAPI["Ollama LLM"]:::external

    %% Terminal I/O
    Terminal["Terminal I/O\n(stdin/stdout)"]:::io

    %% Flows
    User -->|"runs command"| CLI
    SystemPrompt -->|provides prompt| StrandsCore
    EnvConfig -->|env settings| StrandsCore
    CLI -->|"invoke"| StrandsCore

    StrandsCore -->|"load utils"| KBUtils
    StrandsCore -->|"load utils"| ModelUtils
    StrandsCore -->|"load utils"| WelcomeUtils

    StrandsCore -->|"register tools"| RichInterface
    StrandsCore -->|"register tools"| StoreInKB
    StrandsCore -->|"register tools"| StrandTool
    StrandsCore -->|"register tools"| WelcomeTool

    StrandsCore -->|"setup provider"| BedrockProvider
    StrandsCore -->|"setup provider"| OllamaProvider

    StrandsCore -->|"generate() call"| BedrockProvider
    StrandsCore -->|"generate() call"| OllamaProvider

    BedrockProvider -->|"API call"| AWSModel
    BedrockProvider -->|"persist/query"| AWSKB

    OllamaProvider -->|"local call"| OllamaAPI

    AWSModel -->|"stream tokens"| CallbackHandler
    OllamaAPI -->|"stream tokens"| CallbackHandler

    CallbackHandler -->|"render"| RichInterface
    CallbackHandler -->|"render"| Terminal

    Terminal -->|"display output"| User

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#1A5276,stroke-width:1px;
    classDef external fill:#D5F5E3,stroke:#196F3D,stroke-width:1px;
    classDef io fill:#FCF3CF,stroke:#B7950B,stroke-width:1px;
    classDef db fill:#FADBD8,stroke:#C0392B,stroke-width:1px;
    classDef config fill:#F2F3F4,stroke:#839192,stroke-width:1px;
```
