Strands Agent Builder Documentation

To exit the interactive development mode in the Agent Builder, you can use any of the following methods:

• Type exit
• Type quit
• Press Ctrl+C
• Press Ctrl+D

Strands uses Amazon Bedrock Knowledge Bases to persist tools, configurations, and history.

Console Setup

1. Create Knowledge Base: In the Amazon Bedrock console, select Create → Knowledge base with vector store.
2. Configure IAM: Use a new service role or an existing one with Bedrock permissions.
3. Data Source: Select Custom for Strands Agent.
4. Embeddings: Select a model (e.g., Amazon Titan Text Embeddings V2) and choose float32 or binary.
5. Vector Store: Use Quick create (recommended) or a custom OpenSearch Serverless/Aurora/S3 setup.
6. Sync: Once created, click Sync in the data source section.

Get Your Knowledge Base ID

• Console: Copy from the knowledge base details page.
• CLI: Use aws bedrock-agent list-knowledge-bases.
• Format: 10 characters (e.g., ABCDEFGHIJ).

Install the strands-agents-builder package using pipx to enable the strands CLI command.

# Install
pipx install strands-agents-builder

You can interact with your Knowledge Base using the --kb flag or by setting the STRANDS_KNOWLEDGE_BASE_ID environment variable.

Usage Examples:

# Load and extend tools from your knowledge base
strands --kb YOUR_KB_ID "Load my data_visualizer tool and add 3D plotting capabilities"

# Set a default knowledge base via environment variable
export STRANDS_KNOWLEDGE_BASE_ID="YOUR_KB_ID"
strands "Find my most recent agent configuration and make it more efficient"

# Load and extend tools from your knowledge base
strands --kb YOUR_KB_ID "Load my data_visualizer tool and add 3D plotting capabilities"

# Or set a default knowledge base via environment variable
export STRANDS_KNOWLEDGE_BASE_ID="YOUR_KB_ID"
strands "Find my most recent agent configuration and make it more efficient"

You can define the agent's persona and instructions using environment variables or a local file.

• Environment Variable: Use STRANDS_SYSTEM_PROMPT.
• Local File: Create a file named .prompt in your current directory.

# Via environment variable
export STRANDS_SYSTEM_PROMPT="You are a Python expert."

# Or local file
echo "You are a security expert." > .prompt

The CallbackHandler manages the visual state of the agent's execution through several phases:

1. Event Loop Initialization: When init_event_loop is true, a blue 'retrieving memories...' spinner is shown. When start_event_loop is true, it updates to 'thinking...'.
2. Tool Execution: When current_tool_use is detected, a ToolSpinner is created. It tracks the size of the input string to show progress (e.g., 🛠️ web_search: 45 chars).
3. Tool Completion: When a message with role: 'user' contains a toolResult, the handler calculates the duration of the tool execution and updates the spinner to a success (green) or failure (red) state.
4. Cleanup: Once a tool result is processed, the handler clears the tool_histories and resets the current_spinner.

You can connect an agent to a knowledge base to enable retrieval-augmented generation (RAG).

1. Identification: Provide the knowledge base ID via the --kb flag or set the STRANDS_KNOWLEDGE_BASE_ID environment variable.
2. Retrieval: When a knowledge base ID is present, the CLI automatically calls agent.tool.retrieve using the user's input before processing the query.
3. Persistence: If a knowledge base is active, the conversation (query and response) is automatically stored in the knowledge base using store_conversation_in_kb after each turn.

# Using environment variable
export STRANDS_KNOWLEDGE_BASE_ID="my-kb-123"
strands "Search the docs for installation"

Strands uses optimized defaults for Amazon Bedrock (Claude Sonnet 4). You can override these using environment variables.

• STRANDS_MAX_TOKENS: Sets the maximum token output for responses (Default: 32767).
• STRANDS_BUDGET_TOKENS: Sets the budget for agent thinking/reasoning (Default: 2048).

# Maximum tokens for responses
export STRANDS_MAX_TOKENS=32000

# Budget for agent thinking/reasoning
export STRANDS_BUDGET_TOKENS=1024

You can switch from the default bedrock provider to ollama or a custom provider using the --model-provider and --model-config flags.

Using Ollama

strands --model-provider ollama --model-config '{"model_id": "<ID>"}'

Using a Custom Python Provider

To use a custom provider, create a Python module in $CWD/.models/ that exposes an instance function:

1. Create .models/custom_model.py:

from mymodels import CustomModel

def instance(**config):
    return CustomModel(**config)

2. Run strands with the provider name:

strands --model-provider custom_model --model-config <JSON|FILE>

# Example using Ollama
strands --model-provider ollama --model-config '{"model_id": "<ID>"}'