Strands Agents Tools

https://github.com/strands-agents/tools
Admin
Strands Agents Tools provides a model-driven approach to building AI agents with a comprehensive set...
Tokens:212,446
Snippets:1,413
Trust Score:7.8
License:Apache-2.0
Update:1 day ago
Show doc for...
Tokens:
Raw
### Development installation setup

Source: https://github.com/strands-agents/tools/blob/main/README.md

Clone the repository, create a virtual environment, install in development mode, and set up pre-commit hooks. Includes Windows activation command as a comment.

```bash
# Clone the repository
git clone https://github.com/strands-agents/tools.git
cd tools

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install
```

--------------------------------

### Install pre-commit hooks with pre-commit install

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Install the pre-commit hook. The hook runs hatch run format, hatch run lint, hatch run test, and hatch run cz check on each commit.

```bash
pre-commit install
```

--------------------------------

### Namespace organization examples

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Shows various namespace patterns for user, session, hierarchical, and feature-based isolation. The namespace is bound per tool instance and is not agent-controllable.

```python
# User-based namespaces
user_namespace = f"user_{user_id}"

# Session-based namespaces
session_namespace = f"session_{session_id}"

# Hierarchical namespaces
org_user_namespace = f"org_{org_id}_user_{user_id}"

# Feature-based namespaces
chat_namespace = "feature_chat"
task_namespace = "feature_tasks"

# Bind the chosen namespace when constructing the tool
memory_tool = ElasticsearchMemoryTool(
    cloud_id="your-cloud-id",
    api_key="your-api-key",
    namespace=user_namespace,
)
```

--------------------------------

### Install strands-agents-tools via pip

Source: https://github.com/strands-agents/tools/blob/main/README.md

Install the core package with pip. Use this for the base installation without optional dependencies.

```bash
pip install strands-agents-tools
```

--------------------------------

### Set up pre-commit hooks with pre-commit install

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Install pre-commit hooks for pre-commit and commit-msg stages. This automatically runs formatters and conventional commit checks before each commit.

```bash
pre-commit install -t pre-commit -t commit-msg
```

--------------------------------

### Build per-principal tool with base configuration

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Creates a reusable base configuration and builds one tool per authenticated user, binding the namespace at construction. The example shows usage with an agent and recording a memory.

```python
# Create a base connection configuration
base_config = {
    "cloud_id": "your-cloud-id",
    "api_key": "your-api-key",
    "index_name": "user_memories",
    "region": "us-east-1",
}

# Build one tool per authenticated principal
def build_user_agent(user_id):
    memory_tool = ElasticsearchMemoryTool(namespace=f"user_{user_id}", **base_config)
    return Agent(tools=[memory_tool.elasticsearch_memory])

# Usage
alice_agent = build_user_agent("alice")
result = alice_agent.tool.elasticsearch_memory(action="record", content="Alice likes Italian food")
```

--------------------------------

### Install strands-agents-tools with optional dependencies

Source: https://github.com/strands-agents/tools/blob/main/README.md

Install the package along with optional dependencies for mem0 memory, browser use, RSS, and computer use tools. Enables additional tool functionality.

```bash
pip install "strands-agents-tools[mem0_memory, use_browser, rss, use_computer]"
```

--------------------------------

### Usage examples for media tools

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/media_tools.md

Shows how to instantiate an Agent with media tools and call each tool. Includes error handling for chat_video when status is 'error'.

```python
from strands import Agent
from strands_tools import generate_image, image_reader
from strands_tools.generate_image_stability import generate_image_stability
from strands_tools.nova_reels import nova_reels
from strands_tools.search_video import search_video
from strands_tools.chat_video import chat_video

agent = Agent(tools=[generate_image, generate_image_stability, image_reader, nova_reels, search_video, chat_video])

agent.tool.generate_image(prompt="A sunset over mountains")
agent.tool.image_reader(image_path="path/to/image.jpg")
agent.tool.generate_image_stability(prompt="A tranquil pool")

job = agent.tool.nova_reels(action="create", text="A cinematic shot of mountains", s3_bucket="my-bucket")
arn = job.get("invocation_arn")
status = agent.tool.nova_reels(action="status", invocation_arn=arn)

result = agent.tool.search_video(query="people discussing AI", threshold="high", group_by="video")
result = agent.tool.chat_video(prompt="Summarize this", video_id="existing-video-id")
if result["status"] == "error":
    print(result["content"][0]["text"])
```

--------------------------------

### Install development dependencies with pip

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Install the package in editable mode with development dependencies using pip.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Basic HTTP Request Tool Usage

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/http_request.md

Shows how to instantiate an Agent with the http_request tool and make GET and POST requests. The POST example includes headers, a JSON body, and Bearer token authentication.

```python
from strands import Agent
from strands_tools.http_request import http_request

agent = Agent(tools=[http_request])

result = agent.tool.http_request(method="GET", url="https://api.example.com/data")
result = agent.tool.http_request(
    method="POST",
    url="https://api.example.com/resource",
    headers={"Content-Type": "application/json"},
    body='{"key": "value"}',
    auth_type="Bearer",
    auth_token="your_token_here",
)
```

--------------------------------

### init_session

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/code_interpreter.md

Starts a sandbox client and returns an error if the session name already exists locally or in the module cache.

```APIDOC
## init_session

### Description
Starts a sandbox client and returns an error if the session name already exists locally or in the module cache.

### Method
`init_session(self, action: InitSessionAction) -> Dict[str, Any]`

### Parameters
- `action` (InitSessionAction) - Required - The action containing session initialization details.
```

--------------------------------

### Use Computer - Python

Source: https://github.com/strands-agents/tools/blob/main/README.md

Control the computer with actions like mouse_position, type, analyze_screen, open_app, close_app, and hotkey. The hotkey action includes a macOS example.

```python
from strands import Agent
from strands_tools import use_computer

agent = Agent(tools=[use_computer])

# Find mouse position
result = agent.tool.use_computer(action="mouse_position")

# Automate adding text
result = agent.tool.use_computer(action="type", text="Hello, world!", app_name="Notepad")

# Analyze current computer screen
result = agent.tool.use_computer(action="analyze_screen")

result = agent.tool.use_computer(action="open_app", app_name="Calculator")
result = agent.tool.use_computer(action="close_app", app_name="Calendar")

result = agent.tool.use_computer(
    action="hotkey",
    hotkey_str="command+ctrl+f",  # For macOS
    app_name="Chrome"
)
```

--------------------------------

### Cloud diagram usage example

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/diagram.md

Example of creating a cloud architecture diagram with nodes and edges using the diagram tool.

```python
from strands import Agent
from strands_tools import diagram

agent = Agent(tools=[diagram])

result = agent.tool.diagram(
    diagram_type="cloud",
    nodes=[
        {"id": "users", "type": "Users", "label": "End Users"},
        {"id": "lambda", "type": "Lambda", "label": "Backend Service"},
    ],
    edges=[{"from": "users", "to": "lambda"}],
    title="Web Application Architecture",
)
```

--------------------------------

### Usage example for agent_graph tool

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/agent_graph.md

Shows how to create a star-topology graph, send a message, and check status using the agent_graph tool.

```python
from strands import Agent
from strands_tools.agent_graph import agent_graph

agent = Agent(tools=[agent_graph])

result = agent.tool.agent_graph(
    action="create",
    graph_id="analysis_graph",
    topology={
        "type": "star",
        "nodes": [
            {"id": "central", "role": "coordinator", "system_prompt": "You are the coordinator."},
            {"id": "agent1", "role": "analyzer", "system_prompt": "You are a data analyzer."},
        ],
        "edges": [{"from": "central", "to": "agent1"}],
    },
)
agent.tool.agent_graph(action="message", graph_id="analysis_graph",
                       message={"target": "agent1", "content": "Analyze this data pattern..."})
status = agent.tool.agent_graph(action="status", graph_id="analysis_graph")
```

--------------------------------

### Use standalone elasticsearch_memory tool with environment variables

Source: https://github.com/strands-agents/tools/blob/main/README.md

For single-tenant setups, use the standalone elasticsearch_memory tool configured via environment variables. Supports the same actions as the per-principal version.

```python
from strands import Agent
from strands_tools.elasticsearch_memory import ElasticsearchMemoryTool, elasticsearch_memory

# Single-tenant: use the standalone tool with configuration from environment variables
agent = Agent(tools=[elasticsearch_memory])
result = agent.tool.elasticsearch_memory(action="record", content="User prefers vegetarian pizza")
```

--------------------------------

### Usage example for generate_input_schema and check_boto3_validity

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/schema_utils.md

Shows how to import and use generate_input_schema and check_boto3_validity. Generates a schema for s3 list_buckets and checks an invalid service.

```python
from strands_tools.utils.generate_schema_util import generate_input_schema, check_boto3_validity

schema = generate_input_schema("s3", "list_buckets")
print(schema["result"])  # "success"

valid, msg = check_boto3_validity("invalid_service", "anything")
assert valid is False
print(msg)  # "Unknown service: 'invalid_service'"
```

--------------------------------

### AgentCore Memory Tool Usage

Source: https://github.com/strands-agents/tools/blob/main/README.md

Shows how to use the AgentCoreMemoryToolProvider to create an agent with memory tools. Supports actions: record, retrieve, list, and get. Requires memory_id, actor_id, session_id, and namespace; region is optional.

```python
from strands import Agent
from strands_tools.agent_core_memory import AgentCoreMemoryToolProvider


provider = AgentCoreMemoryToolProvider(
    memory_id="memory-123abc",  # Required
    actor_id="user-456",        # Required
    session_id="session-789",   # Required
    namespace="default",        # Required
    region="us-west-2"          # Optional, defaults to us-west-2
)

agent = Agent(tools=provider.tools)

# Create a new memory
result = agent.tool.agent_core_memory(
    action="record",
    content="I am allergic to shellfish"
)

# Search for relevant memories
result = agent.tool.agent_core_memory(
    action="retrieve",
    query="user preferences"
)

# List all memories
result = agent.tool.agent_core_memory(
    action="list"
)

# Get a specific memory by ID
result = agent.tool.agent_core_memory(
    action="get",
    memory_record_id="mr-12345"
)
```

--------------------------------

### Create model and get provider config

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/model_utils.md

Creates a model using the create_model function with a provider and configuration, and retrieves the default configuration for a provider.

```python
from strands_tools.utils.models.model import create_model, get_provider_config

model = create_model(provider="bedrock", config={"model_id": "us.anthropic.claude-sonnet-4-20250514-v1:0"})
cfg = get_provider_config("ollama")  # {"host": "http://localhost:11434", "model_id": "qwen3:4b"}
```

--------------------------------

### Get Specific Memory by ID

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Retrieves a specific memory using its memory_id.

```python
# Retrieve a specific memory by ID
result = agent.tool.elasticsearch_memory(
    action="get",
    memory_id="mem_1704567890123_abc12345",
)
```

--------------------------------

### Usage example with Agent and shell/python_repl

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/shell_python.md

Shows how to create an Agent with shell and python_repl tools, execute single and sequential shell commands, handle errors, and run persistent-state Python code.

```python
from strands import Agent
from strands_tools import shell, python_repl

agent = Agent(tools=[shell, python_repl])

# Single command, then a sequence
agent.tool.shell(command="ls -la")
agent.tool.shell(command=["mkdir -p tmp", "cd tmp", "touch f.txt"])
result = agent.tool.shell(command="risky-command", ignore_errors=True)
if result["status"] == "error":
    print(result["content"][0]["text"])

# Persistent-state Python execution
agent.tool.python_repl(code="x = 10")
result = agent.tool.python_repl(code="print(x * 2)")  # 20
```

--------------------------------

### List All Memories with ElasticsearchMemoryTool

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Lists memories with optional pagination. The first call lists recent memories; the second uses a next_token to start from the 11th result.

```python
# List recent memories
result = agent.tool.elasticsearch_memory(
    action="list",
    max_results=20,
)

# List with pagination
result = agent.tool.elasticsearch_memory(
    action="list",
    max_results=10,
    next_token="10",  # Start from the 11th result
)
```

--------------------------------

### MongoDBMemoryTool setup and usage with Agent

Source: https://github.com/strands-agents/tools/blob/main/README.md

Bind MongoDB connection, collection, and namespace per principal using MongoDBMemoryTool, then use the agent-facing mongodb_memory tool to record, retrieve, list, get, and delete memories. Requires AWS credentials for Amazon Bedrock Titan embeddings.

```python
from strands import Agent
from strands_tools.mongodb_memory import MongoDBMemoryTool, mongodb_memory

# Bind connection, collection, and namespace per principal (kept out of the agent-facing tool)
memory_tool = MongoDBMemoryTool(
    cluster_uri="mongodb+srv://username:password@cluster0.mongodb.net/?retryWrites=true&w=majority",
    database_name="memories",
    collection_name="user_memories",
    namespace="user_123",
)
agent = Agent(tools=[memory_tool.mongodb_memory])

# Store a memory with semantic embeddings
result = agent.tool.mongodb_memory(
    action="record",
    content="User prefers vegetarian pizza with extra cheese",
    metadata={"category": "food_preferences", "type": "dietary"},
)

# Search memories using semantic similarity (vector search)
result = agent.tool.mongodb_memory(
    action="retrieve",
    query="food preferences and dietary restrictions",
    max_results=5,
)

# List all memories with pagination
result = agent.tool.mongodb_memory(action="list", max_results=10)

# Get specific memory by ID
result = agent.tool.mongodb_memory(action="get", memory_id="mem_1234567890_abcd1234")

# Delete a memory
result = agent.tool.mongodb_memory(action="delete", memory_id="mem_1234567890_abcd1234")

# Single-tenant: use the standalone tool with configuration from environment variables
agent = Agent(tools=[mongodb_memory])
result = agent.tool.mongodb_memory(action="record", content="User prefers vegetarian pizza")
```

--------------------------------

### use_llm

Source: https://github.com/strands-agents/tools/blob/main/README.md

Create nested AI loops with customized system prompts for specialized tasks.

```APIDOC
## use_llm

### Description
Create nested AI loops with customized system prompts for specialized tasks.

### Method
agent.tool.use_llm

### Parameters
- **prompt** (string) - Required - The prompt for the LLM.
- **system_prompt** (string) - Optional - The system prompt.

### Request Example
```
agent.tool.use_llm(prompt="Analyze this data", system_prompt="You are a data analyst")
```

```

--------------------------------

### Run linters with hatch fmt --linter

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Run the linters manually using hatch.

```bash
hatch fmt --linter
```

--------------------------------

### Install MongoDB Memory Tool Dependencies

Source: https://github.com/strands-agents/tools/blob/main/docs/mongodb_memory_tool.md

Install the required dependencies for the MongoDB Atlas Memory Tool. This installs pymongo>=4.0.0,<5.0.0.

```bash
pip install strands-agents-tools[mongodb_memory]
```

--------------------------------

### Install strands-agents-tools with Elasticsearch memory extra

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Installs the package with the elasticsearch_memory extra, which includes the Elasticsearch Python client (elasticsearch>=8.0.0,<9.0.0).

```bash
pip install strands-agents-tools[elasticsearch_memory]
```

--------------------------------

### Run unit tests with hatch test

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Run the unit tests using hatch.

```bash
hatch test
```

--------------------------------

### Basic setup and discovery with A2AClientToolProvider

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/a2a_client.md

Initializes the A2AClientToolProvider with known agent URLs and HTTP client arguments, then creates an Agent with the provider's tools. Agent-facing calls include a2a_discover_agent and a2a_list_discovered_agents. Discovery is lazy and occurs on the first tool call.

```python
from strands import Agent
from strands_tools.a2a_client import A2AClientToolProvider

provider = A2AClientToolProvider(
    known_agent_urls=["http://localhost:9000"],
    httpx_client_args={"headers": {"Authorization": "Bearer token"}, "timeout": 300},
)
agent = Agent(tools=provider.tools)

# Agent-facing calls
card = await agent.tool.a2a_discover_agent(url="http://localhost:9000")
agents = await agent.tool.a2a_list_discovered_agents()
```

--------------------------------

### Video Tools Usage (search_video and chat_video)

Source: https://github.com/strands-agents/tools/blob/main/README.md

Shows how to use search_video to find video content and chat_video to interact with videos. For chat_video with a new video file, index_id is required or TWELVELABS_PEGASUS_INDEX_ID env var must be set.

```python
from strands import Agent
from strands_tools import search_video, chat_video

agent = Agent(tools=[search_video, chat_video])

# Search for video content using natural language
result = agent.tool.search_video(
    query="people discussing AI technology",
    threshold="high",
    group_by="video",
    page_limit=5
)

# Chat with existing video (no index_id needed)
result = agent.tool.chat_video(
    prompt="What are the main topics discussed in this video?",
    video_id="existing-video-id"
)

# Chat with new video file (index_id required for upload)
result = agent.tool.chat_video(
    prompt="Describe what happens in this video",
    video_path="/path/to/video.mp4",
    index_id="your-index-id"  # or set TWELVELABS_PEGASUS_INDEX_ID env var
)
```

--------------------------------

### Retrieve Tool Usage

Source: https://github.com/strands-agents/tools/blob/main/README.md

Shows how to use the retrieve tool with an Agent, including basic retrieval, enabling metadata, and using the RETRIEVE_ENABLE_METADATA_DEFAULT environment variable to set default metadata behavior.

```python
from strands import Agent
from strands_tools import retrieve

agent = Agent(tools=[retrieve])

# Basic retrieval without metadata
result = agent.tool.retrieve(
    text="What is artificial intelligence?"
)

# Retrieval with metadata enabled
result = agent.tool.retrieve(
    text="What are the latest developments in machine learning?",
    enableMetadata=True
)

# Using environment variable to set default metadata behavior
# Set RETRIEVE_ENABLE_METADATA_DEFAULT=true in your environment
result = agent.tool.retrieve(
    text="Tell me about cloud computing"
    # enableMetadata will default to the environment variable value
)
```

--------------------------------

### UML class diagram usage example

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/diagram.md

Example of creating a UML class diagram with elements and relationships using the diagram tool.

```python
result = agent.tool.diagram(
    diagram_type="class",
    elements=[
        {"name": "User", "attributes": ["+id: int"], "methods": ["+login(): bool"]},
        {"name": "Order", "attributes": ["+total: float"], "methods": ["+calculateTotal(): float"]},
    ],
    relationships=[{"from": "User", "to": "Order", "type": "association", "multiplicity": "1..*"}],
)
```

--------------------------------

### Usage examples for calculator tool

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/calculator.md

Shows how to instantiate an Agent with the calculator tool and call it for evaluation, solving, and differentiation. The first call evaluates a numeric expression, the second solves an equation, and the third computes a second-order derivative.

```python
from strands import Agent
from strands_tools import calculator

agent = Agent(tools=[calculator])

result = agent.tool.calculator(expression="2 * sin(pi/4) + log(e**2)")
result = agent.tool.calculator(expression="x**2 - 4", mode="solve", wrt="x")
result = agent.tool.calculator(expression="x**3", mode="derive", wrt="x", order=2)
```

--------------------------------

### Create, start, and check status of a workflow

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/workflow.md

Use the workflow tool to create a workflow with tasks, start it, and check its status. Workflows persist across calls via the WorkflowManager singleton and are saved to WORKFLOW_DIR as JSON.

```python
from strands import Agent
from strands_tools.workflow import workflow

agent = Agent(tools=[workflow])

result = agent.tool.workflow(
    action="create",
    workflow_id="research_pipeline",
    tasks=[
        {"task_id": "collect", "description": "Gather data", "tools": ["retrieve"],
         "model_provider": "bedrock", "priority": 5, "timeout": 300},
        {"task_id": "analyze", "description": "Analyze data", "dependencies": ["collect"],
         "tools": ["calculator"], "priority": 4},
    ],
)
agent.tool.workflow(action="start", workflow_id="research_pipeline")
status = agent.tool.workflow(action="status", workflow_id="research_pipeline")
```

--------------------------------

### Run all checks with hatch fmt

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Run all code quality checks (formatter and linter) using hatch.

```bash
# Run all checks
hatch fmt --formatter
hatch fmt --linter
```

--------------------------------

### Memory Not Found Error Handling for get Action

Source: https://github.com/strands-agents/tools/blob/main/docs/mongodb_memory_tool.md

Attempt to retrieve a non-existent memory ID using the get action. The tool returns an error status with an API error message indicating the memory was not found.

```python
# Non-existent memory ID
result = agent.tool.mongodb_memory(action="get", memory_id="nonexistent")
# Returns: {"status": "error", "content": [{"text": "API error: Memory nonexistent not found ..."}]}
```

--------------------------------

### Catching ElasticsearchValidationError

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/errors.md

Example of catching ElasticsearchValidationError when constructing ElasticsearchMemoryTool with an invalid namespace.

```python
from strands_tools.elasticsearch_memory import ElasticsearchMemoryTool, ElasticsearchValidationError
try:
    tool = ElasticsearchMemoryTool(namespace="bad namespace!")  # invalid namespace
except ElasticsearchValidationError as e:
    print(e)
```

--------------------------------

### Use Agent (Agent as Tool) - Python

Source: https://github.com/strands-agents/tools/blob/main/README.md

Configure an Agent with the use_agent tool. Supports inheriting the parent agent's model, specifying a different provider (e.g., bedrock, github), using environment variables for provider/model, and custom model settings with parameters.

```python
from strands import Agent
from strands_tools import use_agent

agent = Agent(tools=[use_agent])

# Basic usage - inherits parent agent's model
result = agent.tool.use_agent(
    prompt="Tell me about the advantages of tool-building in AI agents",
    system_prompt="You are a helpful AI assistant specializing in AI development concepts."
)

# Use a different model provider for specialized tasks
result = agent.tool.use_agent(
    prompt="Calculate 2 + 2 and explain the result",
    system_prompt="You are a helpful math assistant.",
    model_provider="bedrock",
    model_settings={
        "model_id": "us.anthropic.claude-sonnet-4-20250514-v1:0"
    },
    tools=["calculator"]
)

# Use environment variables to determine model
import os
os.environ["STRANDS_PROVIDER"] = "ollama"
os.environ["STRANDS_MODEL_ID"] = "qwen3:4b"
result = agent.tool.use_agent(
    prompt="Analyze this code",
    system_prompt="You are a code review assistant.",
    model_provider="env"
)

# Custom model configuration with specific parameters
result = agent.tool.use_agent(
    prompt="Write a creative story",
    system_prompt="You are a creative writing assistant.",
    model_provider="github",
    model_settings={
        "model_id": "openai/o4-mini",
        "params": {"temperature": 1, "max_tokens": 4000}
    }
)
```

--------------------------------

### File Operations with file_read, file_write, editor

Source: https://github.com/strands-agents/tools/blob/main/README.md

Initialize an Agent with file operation tools and use them to read, write, and edit files. The editor tool uses a command-based interface with a 'view' action.

```python
from strands import Agent
from strands_tools import file_read, file_write, editor

agent = Agent(tools=[file_read, file_write, editor])

agent.tool.file_read(path="config.json")
agent.tool.file_write(path="output.txt", content="Hello, world!")
agent.tool.editor(command="view", path="script.py")
```

--------------------------------

### agent_core_memory

Source: https://github.com/strands-agents/tools/blob/main/README.md

Manages memories in AgentCore. Supports recording, retrieving, listing, and getting specific memories.

```APIDOC
## agent_core_memory

### Description
Manages memories in AgentCore. Supports recording, retrieving, listing, and getting specific memories.

### Method
Function call

### Endpoint
`agent.tool.agent_core_memory`

### Parameters
- **action** (string) - Required - The action to perform: `record`, `retrieve`, `list`, or `get`.
- **content** (string) - Optional - The content to record (required for `record`).
- **query** (string) - Optional - The search query (required for `retrieve`).
- **memory_record_id** (string) - Optional - The ID of a specific memory record (required for `get`).

### Request Example
```python
# Create a new memory
result = agent.tool.agent_core_memory(
    action="record",
    content="I am allergic to shellfish"
)

# Search for relevant memories
result = agent.tool.agent_core_memory(
    action="retrieve",
    query="user preferences"
)

# List all memories
result = agent.tool.agent_core_memory(
    action="list"
)

# Get a specific memory by ID
result = agent.tool.agent_core_memory(
    action="get",
    memory_record_id="mr-12345"
)
```

### Response
Returns the result of the memory operation.
```

--------------------------------

### Delete Memory by ID

Source: https://github.com/strands-agents/tools/blob/main/docs/elasticsearch_memory_tool.md

Deletes a specific memory using its memory_id.

```python
# Delete a specific memory
result = agent.tool.elasticsearch_memory(
    action="delete",
    memory_id="mem_1704567890123_abc12345",
)
```

--------------------------------

### MemoryServiceClient.store_document

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/memory.md

Ingests a document into the Knowledge Base by starting an ingestion job.

```APIDOC
## MemoryServiceClient.store_document

### Description
Ingests a document into the Knowledge Base by starting an ingestion job.

### Method
Method

### Signature
`store_document(self, kb_id: str, data_source_id: str = None, content: str = None, title: str = None)`

### Parameters
- **kb_id** (str) - Required - The Knowledge Base ID.
- **data_source_id** (Optional[str]) - Optional - The data source ID.
- **content** (Optional[str]) - Optional - The document content.
- **title** (Optional[str]) - Optional - The document title.
```

--------------------------------

### Initialize and use LocalChromiumBrowser with Agent

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/browser.md

Shows how to create a LocalChromiumBrowser instance, attach it to an Agent, and call the browser tool to initialize a session and navigate to a URL. The launch_options and context_options configure headless mode and viewport size.

```python
from strands import Agent
from strands_tools.browser import LocalChromiumBrowser

browser = LocalChromiumBrowser(
    launch_options={"headless": True},
    context_options={"viewport": {"width": 1280, "height": 720}},
)
agent = Agent(tools=[browser.browser])

result = agent.tool.browser({
    "action": {"type": "init_session", "session_name": "main-session", "description": "Web automation"},
    "wait_time": 2,
})
result = agent.tool.browser({
    "action": {"type": "navigate", "url": "https://example.com", "session_name": "main-session"}
})
```

--------------------------------

### current_time

Source: https://github.com/strands-agents/tools/blob/main/README.md

Get the current time in ISO 8601 format for a specified timezone. Deprecated — see Deprecations.

```APIDOC
## current_time

### Description
Get the current time in ISO 8601 format for a specified timezone. Deprecated — see Deprecations.

### Method
agent.tool.current_time

### Parameters
- **timezone** (string) - Optional - The timezone (e.g., "US/Pacific").

### Request Example
```
agent.tool.current_time(timezone="US/Pacific")
```

```

--------------------------------

### Run pre-commit hooks manually on all files

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Run the pre-commit hooks manually on all files.

```bash
pre-commit run --all-files
```

--------------------------------

### Get Specific Memory by ID

Source: https://github.com/strands-agents/tools/blob/main/docs/mongodb_memory_tool.md

Retrieves a single memory using its unique memory_id.

```python
# Retrieve a specific memory by ID
result = agent.tool.mongodb_memory(
    action="get",
    memory_id="mem_1704567890123_abc12345",
)
```

--------------------------------

### Exa Search and Contents

Source: https://github.com/strands-agents/tools/blob/main/README.md

Use Exa search and content retrieval tools with an Agent. Demonstrates basic search, company-specific search, news search with date filtering, content retrieval with summaries and subpages, and structured summary with JSON schema.

```python
from strands import Agent
from strands_tools.exa import exa_search, exa_get_contents

agent = Agent(tools=[exa_search, exa_get_contents])

# Basic search (auto mode is default and recommended)
result = agent.tool.exa_search(
    query="Best project management software",
    text=True
)

# Company-specific search when needed
result = agent.tool.exa_search(
    query="Anthropic AI safety research",
    category="company",
    include_domains=["anthropic.com"],
    num_results=5,
    summary={"query": "key research areas and findings"}
)

# News search with date filtering
result = agent.tool.exa_search(
    query="AI regulation policy updates",
    category="news",
    start_published_date="2024-01-01T00:00:00.000Z",
    text=True
)

# Get detailed content from specific URLs
result = agent.tool.exa_get_contents(
    urls=[
        "https://example.com/blog-post",
        "https://github.com/microsoft/semantic-kernel"
    ],
    text={"maxCharacters": 5000, "includeHtmlTags": False},
    summary={
        "query": "main points and practical applications"
    },
    subpages=2,
    extras={"links": 5, "imageLinks": 2}
)

# Structured summary with JSON schema
result = agent.tool.exa_get_contents(
    urls=["https://example.com/article"],
    summary={
        "query": "main findings and recommendations",
        "schema": {
            "type": "object",
            "properties": {
                "main_points": {"type": "string", "description": "Key points from the article"},
                "recommendations": {"type": "string", "description": "Suggested actions or advice"},
                "conclusion": {"type": "string", "description": "Overall conclusion"},
                "relevance": {"type": "string", "description": "Why this matters"}
            },
            "required": ["main_points", "conclusion"]
        }
    }
)

```

--------------------------------

### elasticsearch_memory

Source: https://github.com/strands-agents/tools/blob/main/README.md

Store and retrieve memories with semantic embeddings using Elasticsearch. Supports actions: record, retrieve, list, get, and delete.

```APIDOC
## elasticsearch_memory

### Description
Store and retrieve memories with semantic embeddings using Elasticsearch. Supports actions: record, retrieve, list, get, and delete.

### Actions

#### record

##### Description
Stores a memory with semantic embeddings.

##### Parameters
- **content** (string) - Required - The memory content to store.
- **metadata** (object) - Optional - Additional metadata associated with the memory.

##### Request Example
```json
{
  "action": "record",
  "content": "User prefers vegetarian pizza with extra cheese",
  "metadata": {"category": "food_preferences", "type": "dietary"}
}
```

#### retrieve

##### Description
Searches memories using semantic similarity (vector search).

##### Parameters
- **query** (string) - Required - The search query.
- **max_results** (integer) - Optional - Maximum number of results to return.

##### Request Example
```json
{
  "action": "retrieve",
  "query": "food preferences and dietary restrictions",
  "max_results": 5
}
```

#### list

##### Description
Lists all memories with pagination.

##### Parameters
- **max_results** (integer) - Optional - Maximum number of results to return.

##### Request Example
```json
{
  "action": "list",
  "max_results": 10
}
```

#### get

##### Description
Retrieves a specific memory by ID.

##### Parameters
- **memory_id** (string) - Required - Identifier of the memory to retrieve.

##### Request Example
```json
{
  "action": "get",
  "memory_id": "mem_1234567890_abcd1234"
}
```

#### delete

##### Description
Deletes a memory.

##### Parameters
- **memory_id** (string) - Required - Identifier of the memory to delete.

##### Request Example
```json
{
  "action": "delete",
  "memory_id": "mem_1234567890_abcd1234"
}
```

```

--------------------------------

### Dynamic MCP Client Integration with mcp_client

Source: https://github.com/strands-agents/tools/blob/main/README.md

Connect to external MCP servers at runtime using the mcp_client tool. Supports stdio, SSE, and streamable HTTP transports. Includes actions for connect, list_tools, call_tool, and load_tools. Security warning: loading external tools poses significant risks.

```python
from strands import Agent
from strands_tools import mcp_client

agent = Agent(tools=[mcp_client])

# Connect to a custom MCP server via stdio
agent.tool.mcp_client(
    action="connect",
    connection_id="my_tools",
    transport="stdio",
    command="python",
    args=["my_mcp_server.py"]
)

# List available tools on the server
tools = agent.tool.mcp_client(
    action="list_tools",
    connection_id="my_tools"
)

# Call a tool from the MCP server
result = agent.tool.mcp_client(
    action="call_tool",
    connection_id="my_tools",
    tool_name="calculate",
    tool_args={"x": 10, "y": 20}
)

# Connect to a SSE-based server
agent.tool.mcp_client(
    action="connect",
    connection_id="web_server",
    transport="sse",
    server_url="http://localhost:8080/sse"
)

# Connect to a streamable HTTP server
agent.tool.mcp_client(
    action="connect",
    connection_id="http_server",
    transport="streamable_http",
    server_url="https://api.example.com/mcp",
    headers={"Authorization": "Bearer token"},
    timeout=60
)

# Load MCP tools into agent's registry for direct access
# ⚠️ WARNING: This loads external tools directly into the agent
agent.tool.mcp_client(
    action="load_tools",
    connection_id="my_tools"
)
# Now you can call MCP tools directly as: agent.tool.calculate(x=10, y=20)
```

--------------------------------

### use_computer

Source: https://github.com/strands-agents/tools/blob/main/README.md

Desktop automation, GUI interaction, and screen capture.

```APIDOC
## use_computer

### Description
Desktop automation, GUI interaction, and screen capture.

### Usage
`agent.tool.use_computer(action="click", x=100, y=200, app_name="Chrome")`

### Parameters
- **action** (string) - Required - Action to perform (e.g., "click").
- **x** (integer) - Optional - X coordinate.
- **y** (integer) - Optional - Y coordinate.
- **app_name** (string) - Optional - Name of the application.
```

--------------------------------

### environment

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/core_tools.md

Manage environment variables: list, get, set, delete, or validate. Sensitive values are masked by default.

```APIDOC
## environment

### Description
Manage environment variables: list, get, set, delete, or validate. Sensitive values are masked by default.

### Parameters
- `action` (enum) - Required - `list`, `get`, `set`, `delete`, `validate`
- `name` (str) - Optional - Variable name
- `value` (str) - Optional - Value to set
- `prefix` (str) - Optional - Filter for listing

### Notes
- `set`/`delete` require confirmation unless `BYPASS_TOOL_CONSENT=true`.
- Protected variables cannot be modified: `PATH`, `PYTHONPATH`, `STRANDS_HOME`, `SHELL`, `USER`, `HOME`, `BYPASS_TOOL_CONSENT`, `STRANDS_NON_INTERACTIVE`, `STRANDS_DISABLE_LOAD_TOOL`, `ENV_VARS_MASKED_DEFAULT`, `STRANDS_HTTP_ALLOW_INSECURE_SSL`, `EDITOR_DISABLE_BACKUP`.
- Sensitive values (names containing TOKEN/SECRET/PASSWORD/KEY/AUTH) are masked unless `ENV_VARS_MASKED_DEFAULT=false`.
```

--------------------------------

### Catch construction error from Mem0MemoryTool

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/errors.md

Class-based tools raise at construction. This example catches the ValueError when Mem0MemoryTool is instantiated without user_id or agent_id.

```python
from strands_tools.mem0_memory import Mem0MemoryTool
try:
    Mem0MemoryTool()  # neither user_id nor agent_id
except ValueError as e:
    print(e)
```

--------------------------------

### Use AWS

Source: https://github.com/strands-agents/tools/blob/main/README.md

Use the use_aws tool to interact with AWS services like S3 and EC2. Demonstrates listing S3 buckets, listing objects in a bucket, and describing EC2 subnets.

```python
from strands import Agent
from strands_tools import use_aws

agent = Agent(tools=[use_aws])

# List S3 buckets
result = agent.tool.use_aws(
    service_name="s3",
    operation_name="list_buckets",
    parameters={},
    region="us-east-1",
    label="List all S3 buckets"
)

# Get the contents of a specific S3 bucket
result = agent.tool.use_aws(
    service_name="s3",
    operation_name="list_objects_v2",
    parameters={"Bucket": "example-bucket"},  # Replace with your actual bucket name
    region="us-east-1",
    label="List objects in a specific S3 bucket"
)

# Get the list of EC2 subnets
result = agent.tool.use_aws(
    service_name="ec2",
    operation_name="describe_subnets",
    parameters={},
    region="us-east-1",
    label="List all subnets"
)
```

--------------------------------

### MCPTool.__init__

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/mcp_client.md

Initializes an MCPTool instance wrapping a dynamically loaded MCP tool. The tool runs under the `with config.mcp_client:` context pattern.

```APIDOC
## MCPTool.__init__

### Description
Initializes an MCPTool instance wrapping a dynamically loaded MCP tool. The tool runs under the `with config.mcp_client:` context pattern.

### Signature
```python
MCPTool(mcp_tool, connection_id: str)
```

### Parameters
- **mcp_tool** - The MCP tool object to wrap.
- **connection_id** (str) - The connection ID associated with the MCP server.

```

--------------------------------

### MemoryAction Enum (agent_core_memory)

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/types.md

Enum of memory actions accepted by the `action` parameter of `AgentCoreMemoryToolProvider.agent_core_memory`. Values: record, retrieve, list, get, delete.

```APIDOC
## MemoryAction Enum (agent_core_memory)

### Description
Enum of memory actions accepted by the `action` parameter of `AgentCoreMemoryToolProvider.agent_core_memory`.

### Values
- `RECORD` = "record"
- `RETRIEVE` = "retrieve"
- `LIST` = "list"
- `GET` = "get"
- `DELETE` = "delete"

```

--------------------------------

### Run code formatters with hatch fmt --formatter

Source: https://github.com/strands-agents/tools/blob/main/CONTRIBUTING.md

Run the code formatters manually using hatch.

```bash
hatch fmt --formatter
```

--------------------------------

### HTTP Requests with http_request

Source: https://github.com/strands-agents/tools/blob/main/README.md

Make HTTP requests with support for GET, POST, authentication, and markdown conversion. Use convert_to_markdown for better readability of HTML pages.

```python
from strands import Agent
from strands_tools import http_request

agent = Agent(tools=[http_request])

# Make a simple GET request
response = agent.tool.http_request(
    method="GET",
    url="https://api.example.com/data"
)

# POST request with authentication
response = agent.tool.http_request(
    method="POST",
    url="https://api.example.com/resource",
    headers={"Content-Type": "application/json"},
    body=json.dumps({"key": "value"}),
    auth_type="Bearer",
    auth_token="your_token_here"
)

# Convert HTML webpages to markdown for better readability
response = agent.tool.http_request(
    method="GET",
    url="https://example.com/article",
    convert_to_markdown=True
)
```

--------------------------------

### start_platform

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/code_interpreter.md

No-op method that does nothing. It is part of the platform lifecycle but has no implementation.

```APIDOC
## start_platform

### Description
No-op method that does nothing. It is part of the platform lifecycle but has no implementation.

### Method
`start_platform(self) -> None`
```

--------------------------------

### MemoryAction enum definition

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/agent_core_memory.md

Defines the valid action values for the agent_core_memory tool: record, retrieve, list, get, delete.

```python
class MemoryAction(str, Enum):
    RECORD = "record"
    RETRIEVE = "retrieve"
    LIST = "list"
    GET = "get"
    DELETE = "delete"
```

--------------------------------

### LocalChromiumBrowser.__init__

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/browser.md

Initializes a LocalChromiumBrowser instance with optional Chromium launch and context options. These options are merged over environment defaults.

```APIDOC
## LocalChromiumBrowser.__init__

### Description
Initializes a LocalChromiumBrowser instance with optional Chromium launch and context options. These options are merged over environment defaults.

### Method
Constructor

### Signature
```python
LocalChromiumBrowser(launch_options: Optional[Dict[str, Any]] = None, context_options: Optional[Dict[str, Any]] = None)
```

### Parameters
- **launch_options** (Optional[Dict[str, Any]]) - Optional - Chromium launch options (headless, args). Merged over env defaults.
- **context_options** (Optional[Dict[str, Any]]) - Optional - Browser context options (viewport, user_agent, storage_state, locale...). Merged over env defaults.

### Environment Variables
- `STRANDS_BROWSER_USER_DATA_DIR` (default `~/.browser_automation`)
- `STRANDS_BROWSER_HEADLESS` (`"true"` → headless, default `false`)
- `STRANDS_BROWSER_WIDTH` (default `1280`)
- `STRANDS_BROWSER_HEIGHT` (default `800`)

### Notes
- `start_platform` reads env vars to build defaults.
- `create_browser_session` launches via `self._playwright.chromium.launch(**self._default_launch_options)`, or `launch_persistent_context(user_data_dir, ...)` when `persistent_context` is set in launch options.
- `close_platform` is a no-op.
```

--------------------------------

### Batch Tool Usage with http_request and use_aws

Source: https://github.com/strands-agents/tools/blob/main/README.md

Demonstrates using the batch tool to invoke multiple tools (http_request and use_aws) in a single call. Requires importing os and sys.

```python
import os
import sys

from strands import Agent
from strands_tools import batch, http_request, use_aws

# Example usage of the batch with http_request and use_aws tools
agent = Agent(tools=[batch, http_request, use_aws])

result = agent.tool.batch(
    invocations=[
        {"name": "http_request", "arguments": {"method": "GET", "url": "https://api.ipify.org?format=json"}},
        {
            "name": "use_aws",
            "arguments": {
                "service_name": "s3",
                "operation_name": "list_buckets",
                "parameters": {},
                "region": "us-east-1",
                "label": "List S3 Buckets"
            }
        },
    ]
)
```

--------------------------------

### Multi-tenant Mem0MemoryTool usage

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/mem0_memory.md

Recommended for multi-tenant setups. Creates a Mem0MemoryTool with a user_id and uses it via an Agent to store and retrieve memory.

```python
from strands import Agent
from strands_tools.mem0_memory import Mem0MemoryTool

tool = Mem0MemoryTool(user_id="user_12345")
agent = Agent(tools=[tool.mem0_memory])

agent.tool.mem0_memory(action="store", content="User prefers vegetarian pizza")
result = agent.tool.mem0_memory(action="retrieve", query="food preferences")
```

--------------------------------

### init_session

Source: https://github.com/strands-agents/tools/blob/main/_autodocs/api-reference/browser.md

Initializes a new browser session. Validates the session exists first and returns a result dict.

```APIDOC
## [METHOD] init_session

### Description
Initializes a new browser session. Validates the session exists first and returns a result dict.

### Method
METHOD

### Endpoint
init_session

### Parameters
#### Request Body
- **action** (InitSessionAction) - Required - The action containing session initialization parameters.

### Response
#### Success Response
- **status** (string) - "success" or "error"
- **content** (array) - Result content.

#### Response Example
{
  "status": "success",
  "content": [{"text": "..."}]
}
```
Tokens:
Raw