Skip to content

strands-py

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

strands-py

README.md

Strands Agents - Python SDK

A model-driven approach to building AI agents in just a few lines of code.

GitHub commit activity GitHub open issues GitHub open pull requests License PyPI version Python versions Strands Discord

Documentation ◆ Samples ◆ CLI ◆ MCP Server
Harness (Python, TypeScript) ◆ SDK (Python, TypeScript) ◆ Box ◆ Shell ◆ Evals ◆ Labs

Strands Agents is a simple yet powerful SDK that takes a model-driven approach to building and running AI agents. From simple conversational assistants to complex autonomous workflows, from local development to production deployment, Strands Agents scales with your needs.

Feature Overview

  • Lightweight & Flexible: Simple agent loop that just works and is fully customizable
  • Model Agnostic: Support for Amazon Bedrock, Anthropic, Gemini, LiteLLM, Llama, Ollama, OpenAI, Writer, and custom providers
  • Advanced Capabilities: Multi-agent systems, autonomous agents, and streaming support
  • Built-in MCP: Native support for Model Context Protocol (MCP) servers, enabling access to thousands of pre-built tools

Quick Start

# Install Strands Agents
pip install strands-agents
from strands import Agent
from strands.vended_tools import http_request

agent = Agent(tools=[http_request])
agent("Tell me about the Strands harness features: https://strandsagents.com/docs/user-guide/harness/index.md")

Note: For the default Amazon Bedrock model provider, you'll need AWS credentials configured and model access enabled for Claude 4 Sonnet in the us-west-2 region. See the Quickstart Guide for details on configuring other model providers.

Installation

Ensure you have Python 3.10+ installed, then:

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

# Install Strands
pip install strands-agents

Features at a Glance

Python-Based Tools

Easily build tools using Python decorators:

from strands import Agent, tool

@tool
def word_count(text: str) -> int:
    """Count words in text.

    This docstring is used by the LLM to understand the tool's purpose.
    """
    return len(text.split())

agent = Agent(tools=[word_count])
response = agent("How many words are in this sentence?")

Hot Reloading from Directory: Enable automatic tool loading and reloading from the ./tools/ directory:

from strands import Agent

# Agent will watch ./tools/ directory for changes
agent = Agent(load_tools_from_directory=True)
response = agent("Use any tools you find in the tools directory")

MCP Support

Connect to Model Context Protocol (MCP) servers:

from strands import Agent
from strands.tools.mcp import MCPClient
from mcp import stdio_client, StdioServerParameters

aws_docs_client = MCPClient(
    lambda: stdio_client(StdioServerParameters(command="uvx", args=["awslabs.aws-documentation-mcp-server@latest"]))
)

with aws_docs_client:
   agent = Agent(tools=aws_docs_client.list_tools_sync())
   response = agent("Tell me about Amazon Bedrock and how to use it with Python")

The SDK works with both major versions of the mcp package through a built-in compatibility layer, so most code that uses MCPClient runs unchanged on either version. A fresh install resolves to mcp 2.x, and pinning mcp<2 keeps you on 1.x. See docs/MCP_VERSIONS.md for support status, the behavior differences on 2.x, and migration notes.

Multiple Model Providers

Support for various model providers:

from strands import Agent
from strands.models import BedrockModel
from strands.models.ollama import OllamaModel
from strands.models.llamaapi import LlamaAPIModel
from strands.models.gemini import GeminiModel
from strands.models.llamacpp import LlamaCppModel

# Bedrock
bedrock_model = BedrockModel(
  model_id="us.amazon.nova-pro-v1:0",
  temperature=0.3,
  streaming=True, # Enable/disable streaming
)
agent = Agent(model=bedrock_model)
agent("Tell me about Agentic AI")

# Google Gemini
gemini_model = GeminiModel(
  client_args={
    "api_key": "your_gemini_api_key",
  },
  model_id="gemini-2.5-flash",
  params={"temperature": 0.7}
)
agent = Agent(model=gemini_model)
agent("Tell me about Agentic AI")

# Ollama
ollama_model = OllamaModel(
  host="http://localhost:11434",
  model_id="llama3"
)
agent = Agent(model=ollama_model)
agent("Tell me about Agentic AI")

# Llama API
llama_model = LlamaAPIModel(
    model_id="Llama-4-Maverick-17B-128E-Instruct-FP8",
)
agent = Agent(model=llama_model)
response = agent("Tell me about Agentic AI")

Built-in providers:

Custom providers can be implemented using Custom Providers

Vended tools

The SDK ships pre-built tools for common agent tasks. Import them from strands.vended_tools:

from strands import Agent
from strands.vended_tools import file_editor, http_request, shell

agent = Agent(tools=[file_editor, http_request, shell])
agent("Fetch https://strandsagents.com and save a one-paragraph summary to /tmp/summary.md")
Tool Exports Description
Shell shell, make_shell Run shell commands
File editor file_editor, make_file_editor View, create, and edit files
HTTP request http_request, make_http_request Make HTTP requests to external APIs
Web fetch web_fetch, make_web_fetch Fetch a web page for the model to read. Requires the web-fetch extra
Notebook notebook, make_notebook Keep persistent text notes
Python REPL python_repl, make_python_repl Run Python code
Sleep sleep, make_sleep Pause for a bounded, cancellable duration
Handoff to user handoff_to_user, make_handoff_to_user Pause the agent loop and ask the user for input
Stop stop, make_stop End the agent loop when the task is done
Subagent subagent, make_subagent Delegate a self-contained task to a child agent
Swarm swarm, make_swarm Run a team of agents that hand off work to each other
MCP router make_mcp_router Connect to MCP servers on an allowlist you set
A2A client make_a2a_client Discover and message remote A2A agents. Requires the a2a extra

Use the make_* factories to customize a tool, for example to bind a sandbox or change its name. shell, file_editor, and python_repl run on the host unless you pass a sandbox to Agent. See Vended tools for details on each tool.

Bidirectional Streaming

Build voice agents that talk with users in real time. A BidiAgent holds a persistent connection to a speech model, streams audio both ways, runs tools mid-conversation, and stops speaking when the user interrupts.

Install the extra for your provider. Local audio also needs the PortAudio system library:

# Amazon Bedrock Nova Sonic (Python 3.12+)
pip install "strands-agents[bidi,bidi-io,bidi-pyaudio]"

# Google Gemini Live
pip install "strands-agents[bidi-google,bidi-io,bidi-pyaudio]"

# OpenAI Realtime API
pip install "strands-agents[bidi-openai,bidi-io,bidi-pyaudio]"

This agent listens on your microphone, answers through your speakers, and prints transcripts to the terminal:

import asyncio

from strands.bidi.agent import BidiAgent
from strands.bidi.io import AudioIO
from strands.bidi.models import BedrockNovaSonicModel


async def main():
    model = BedrockNovaSonicModel(model_id="amazon.nova-2-5-sonic")
    agent = BidiAgent(model=model)
    audio_io = AudioIO()

    await agent.run(inputs=[audio_io.input()], outputs=[audio_io.output()])


if __name__ == "__main__":
    asyncio.run(main())

run() keeps the conversation open until you press Ctrl+C or a tool calls agent.cancel(). See the bidirectional streaming quickstart for model configuration, custom I/O, and more.

Documentation

For detailed guidance & examples, explore our documentation:

Development

pip install hatch
hatch test        # run unit tests
hatch fmt         # format & lint

Contributing ❤️

We welcome contributions! See our Contributing Guide for details on:

  • Reporting bugs & features
  • Development setup
  • Contributing via Pull Requests
  • Code of Conduct
  • Reporting of security issues

Stay in touch with the team

Come meet the Strands team and other users on Discord

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Security

See CONTRIBUTING for more information.