Strands Agents SDK

Build AI agents in Python using the Strands SDK (Apache-2.0 license, from AWS). Use this skill to scaffold autonomous agents, create multi-agent workflows, define custom tools, or integrate with MCP servers.

Validated against: strands-agents==1.23.0, strands-agents-tools==0.2.19

intent

The Strands SDK lets you build production-grade Python agents backed by multiple LLM providers (Bedrock, Anthropic, OpenAI, Ollama, Gemini, etc.). Use it when you need autonomous task execution, tool-calling agents, agent-to-agent coordination (swarms or DAGs), or MCP protocol integration. The skill covers agent scaffolding, custom tool creation, multi-agent patterns, session persistence, and observability.

inputs

Required

• python3: Python 3.8+
• strands-agents: Core SDK. Install via pip install strands-agents or pipx install strands-agents-builder (recommended for isolation)
• strands-agents-tools: Optional pre-built tools library

Model Provider Credentials (one required)

Provider	Env Var(s)	Setup Notes
Bedrock (default)	AWS credentials in ~/.aws/credentials or AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN	Region defaults to us-west-2, override with AWS_REGION or region_name param
Anthropic	ANTHROPIC_API_KEY	Get key from https://console.anthropic.com
OpenAI	OPENAI_API_KEY	Get key from https://platform.openai.com/api-keys
Ollama	None (local)	Ollama server running on localhost:11434 or custom host
Gemini	GOOGLE_API_KEY in client_args	Get key from Google AI Studio
Mistral	MISTRAL_API_KEY	Get key from Mistral console
LiteLLM	Provider-specific env vars (Cohere, Groq, etc.)	Meta-provider wrapper
LlamaAPI	LLAMA_API_KEY	Meta Llama API key
SageMaker	AWS credentials + endpoint URI	Custom AWS SageMaker endpoints
Writer	WRITER_API_KEY	Writer platform API key

Optional Inputs

• MCP server executable or URL: For Model Context Protocol integration (stdio command or SSE endpoint)
• Session file or S3 bucket: For persisting conversation state across runs (FileSessionManager or S3SessionManager)
• OpenTelemetry collector: For tracing and observability (auto-instrumented if available)
• AWS Bedrock Guardrails: Guardrail ID and version for content filtering

procedure

1. Install SDK and Dependencies

Input: Python 3.8+, network access to PyPI

# Option A: Isolated install (recommended)
pipx install strands-agents-builder

# Option B: Direct install
pip install strands-agents strands-agents-tools

Output: Executable python3, strands-agents and strands-agents-tools importable in Python

2. Initialize Agent with Model Provider

Input: Model provider (Bedrock, Anthropic, OpenAI, Ollama, etc.), appropriate env vars or config

Choose your provider and instantiate:

Bedrock (default, requires AWS credentials):

from strands import Agent
agent = Agent()  # Uses us.anthropic.claude-sonnet-4-20250514-v1:0 in us-west-2

Ollama (local, positional host argument):

from strands import Agent
from strands.models.ollama import OllamaModel

model = OllamaModel("http://localhost:11434", model_id="qwen3:latest")
agent = Agent(model=model)

Anthropic (requires ANTHROPIC_API_KEY, max_tokens required):

from strands import Agent
from strands.models.anthropic import AnthropicModel

model = AnthropicModel(model_id="claude-sonnet-4-20250514", max_tokens=4096)
agent = Agent(model=model)

OpenAI (requires OPENAI_API_KEY):

from strands import Agent
from strands.models.openai import OpenAIModel

model = OpenAIModel(model_id="gpt-4.1")
agent = Agent(model=model)

Output: Agent instance ready for tool registration and task execution

3. Define Custom Tools (Optional)

Input: Python functions with type hints and docstrings

Use the @tool decorator. Type hints become the schema; docstrings become descriptions:

from strands import tool

@tool
def read_file(path: str) -> str:
    """Read contents of a file at the given path.
    
    Args:
        path: Filesystem path to read.
    """
    with open(path) as f:
        return f.read()

@tool
def write_file(path: str, content: str) -> str:
    """Write content to a file.
    
    Args:
        path: Filesystem path to write.
        content: Text content to write.
    """
    with open(path, 'w') as f:
        f.write(content)
    return f"Wrote {len(content)} bytes to {path}"

Tools with State Access:

from strands import tool
from strands.types.tools import ToolContext

@tool
def stateful_tool(query: str, tool_context: ToolContext) -> str:
    """A tool that accesses agent state.
    
    Args:
        query: Input query.
    """
    count = tool_context.state.get("call_count", 0) + 1
    tool_context.state["call_count"] = count
    return f"Call #{count}: {query}"

Output: Tool functions decorated and ready to pass to Agent

4. Register Tools with Agent

Input: Tool functions (custom-defined or pre-built from strands-agents-tools), optional hot-reload flag

from strands import Agent
from strands_tools import calculator, file_read, file_write, shell

agent = Agent(
    model=model,
    tools=[read_file, write_file, calculator, shell]
)

Hot-reload from directory:

agent = Agent(
    model=model,
    load_tools_from_directory=True  # Watches ./tools/ for changes
)

Available Pre-built Tools (46 total): calculator, file_read, file_write, shell, http_request, editor, image_reader, python_repl, current_time, think, stop, sleep, environment, retrieve, search_video, chat_video, speak, generate_image, generate_image_stability, diagram, journal, memory, agent_core_memory, elasticsearch_memory, mongodb_memory, mem0_memory, rss, cron, batch, workflow, use_agent, use_llm, use_aws, use_computer, load_tool, handoff_to_user, slack, swarm, graph, a2a_client, mcp_client, exa, tavily, bright_data, nova_reels

Output: Agent with tools registered

5. Run Agent on Task

Input: Agent instance, task prompt (string)

result = agent("Read /tmp/test.txt and summarize it")
print(result)

Direct Tool Call (bypass LLM routing):

direct_result = agent.tool.read_file("/tmp/test.txt")

Output: String response from agent or tool

6. Integrate MCP Server (Optional)

Input: MCP server command (stdio) or URL (SSE), MCPClient context manager

Stdio transport (local command):

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

mcp = MCPClient(lambda: stdio_client(StdioServerParameters(
    command="uvx",
    args=["some-mcp-server@latest"]
)))

with mcp:
    agent = Agent(model=model, tools=[mcp])
    agent("Use the MCP tools to fetch data")

SSE transport (remote MCP server):

from mcp.client.sse import sse_client
mcp = MCPClient(lambda: sse_client("http://localhost:8080/sse"))
with mcp:
    agent = Agent(model=model, tools=[mcp])

Output: Agent with MCP tools available

7. Set Up Multi-Agent Pattern

Input: Multiple Agent instances, pattern choice (Swarm, Graph, or nested)

Nested Agents (agents as tools):

researcher = Agent(model=model, system_prompt="You are a research assistant.")
writer = Agent(model=model, system_prompt="You are a writer.")

orchestrator = Agent(
    model=model,
    tools=[researcher, writer],
    system_prompt="You coordinate research and writing tasks."
)
orchestrator("Research quantum computing and write a blog post")

Swarm Pattern (self-organizing, autonomous handoffs):

from strands.multiagent.swarm import Swarm

researcher = Agent(
    model=model,
    name="researcher",
    description="Finds and summarizes information"
)
writer = Agent(
    model=model,
    name="writer",
    description="Creates polished content"
)

swarm = Swarm(
    nodes=[researcher, writer],
    entry_point=researcher,
    max_handoffs=20,
    max_iterations=20,
    execution_timeout=900.0,
    node_timeout=300.0
)
result = swarm("Research AI agents, then hand off to writer for a blog post")

Swarm auto-injects a handoff_to_agent tool. Agents handoff by calling it with target agent name.

Graph Pattern (DAG, deterministic):

from strands.multiagent.graph import GraphBuilder

builder = GraphBuilder()
research_node = builder.add_node(researcher, node_id="research")
writing_node = builder.add_node(writer, node_id="writing")
builder.add_edge("research", "writing")
builder.set_entry_point("research")

graph = builder.build()
result = graph("Write a blog post about AI agents")

Output: Swarm or Graph instance with agents coordinated

8. Persist Session State (Optional)

Input: Session file path or S3 bucket details

File-based session:

from strands.session.file_session_manager import FileSessionManager

session = FileSessionManager(session_file_path="./sessions/my_session.json")
agent = Agent(model=model, session_manager=session)

S3-backed session:

from strands.session.s3_session_manager import S3SessionManager

session = S3SessionManager(bucket_name="my-bucket", session_id="session-1")
agent = Agent(model=model, session_manager=session)

Session managers work with Agent, Swarm, and Graph.

Output: Agent with conversation history persisted to file or S3

9. Enable Observability (Optional)

Input: Optional trace attributes dict

agent = Agent(
    model=model,
    trace_attributes={"project": "my-agent", "environment": "dev"}
)

Native OpenTelemetry tracing is auto-enabled. Every tool call, model invocation, handoff, and lifecycle event is instrumented.

Output: Agent with tracing enabled

10. Scaffold New Agent from Template (Optional)

Input: Agent name, model provider, model ID (optional)

python3 {baseDir}/scripts/create-agent.py my-agent --provider ollama --model qwen3:latest
python3 {baseDir}/scripts/create-agent.py my-agent --provider anthropic
python3 {baseDir}/scripts/create-agent.py my-agent --provider bedrock
python3 {baseDir}/scripts/create-agent.py my-agent --provider openai --model gpt-4.1

Output: Directory with ready-to-run agent code, tools skeleton, config, and entry point

11. Run Agent Interactively or Programmatically

Input: Agent script path, prompt (or --interactive flag)

python3 {baseDir}/scripts/run-agent.py path/to/agent.py "Your prompt here"
python3 {baseDir}/scripts/run-agent.py path/to/agent.py --interactive

Output: Agent task result printed to stdout

decision points

Model Provider Selection

• If you have AWS credentials and no other preference: Use Bedrock (default). No setup needed beyond AWS credentials.
• If you want to run locally with no API costs: Use Ollama with a stock model (qwen3, llama3.x, mistral). Requires Ollama running on localhost:11434.
• If you have Anthropic API key: Use AnthropicModel. Remember max_tokens is required.
• If you have OpenAI API key: Use OpenAIModel.
• If using a different provider (Gemini, Mistral, Groq via LiteLLM): Use the appropriate class from strands.models.<provider> with required env vars.

Tool-Calling Support (Ollama)

• If using stock Ollama models (qwen3, llama3.x, mistral): Tool-calling works out of the box.
• If using an abliterated model: Tool-calling support is often lost. Test with a stock model first; fall back to manual tool invocation if needed.

Multi-Agent Coordination Pattern

• If you need deterministic DAG execution with fixed dependencies: Use Graph pattern with GraphBuilder.
• If you need self-organizing teams with autonomous handoff and dynamic routing: Use Swarm pattern.
• If you need simple parent-child delegation: Use nested agents (agents as tools).

Session Persistence

• If you need to persist agent state locally: Use FileSessionManager.
• If you need cloud persistence or multi-process sharing: Use S3SessionManager.
• If state persistence is not needed: Omit session_manager parameter.

MCP Integration

• If MCP server is a local command (stdio): Use stdio_client with StdioServerParameters.
• If MCP server is remote (HTTP SSE): Use sse_client with URL.
• Always wrap MCPClient in a context manager (with mcp:) to ensure proper connection lifecycle.

API Key / Credential Expiry

• Bedrock: AWS credential expiry (session tokens expire in ~1 hour by default). Refresh via AWS SDK or credential provider.
• Anthropic, OpenAI, others: API key revocation or rate limiting. Handle gracefully with retry logic or fallback prompts.

Rate Limiting and Timeouts

• Model API rate limits: All providers have per-minute/per-day caps. On 429 (rate limit), backoff and retry.
• Swarm execution timeout: Defaults to 900s (15 min). Set execution_timeout= param if tasks run longer.
• Node timeout in Swarm: Defaults to 300s (5 min) per node. Set node_timeout= if a single agent needs more time.
• Network timeouts: MCP connections may hang. Implement socket timeouts on MCPClient or wrap in try-except.

Empty Result Sets

• Tool returns None or empty string: Agent continues; pass empty result to LLM context.
• No tools available: Agent responds based on base model only; may fail on tasks requiring tool execution.
• MCP server has no tools: Agent starts with empty MCP tool set; fallback to other tools.

Bedrock Cross-Region Inference

• If using cross-region inference (model ID prefixed with us.): Bedrock automatically routes to the correct region. Verify region policy in AWS account.
• If using direct regional models: Specify region_name param on BedrockModel or set AWS_REGION env var.

output contract

Agent Invocation Output

Synchronous call:

result = agent("Your prompt")

Returns: str (agent response text)

Tool Execution Output

Custom tools return typed values (str, dict, list, etc.) as declared in function signature. Pre-built tools return structured outputs (e.g., calculator returns int/float, file_read returns str).

Session Persistence Output

FileSessionManager writes to session_file_path as JSON with keys:

• messages: List of conversation turns
• metadata: Agent config and state snapshots

S3SessionManager writes to s3://{bucket_name}/{session_id}.json with same schema.

Swarm Execution Output

Swarm returns final output from the last agent to speak, plus metadata:

• result: Final response string
• handoffs: List of agent-to-agent handoff events
• iteration_count: Number of swarm iterations

Graph Execution Output

Graph returns final node output plus execution log:

• result: Output from final node
• executed_nodes: List of node IDs executed in order
• node_outputs: Dict mapping node ID to its output

Observability / Tracing Output

OpenTelemetry traces are emitted to configured collector (if available) with these span names:

• agent.invoke: Top-level agent call
• agent.tool_call: Tool execution
• agent.handoff: Multi-agent handoff
• model.invoke: LLM API call

Traces include trace_attributes dict passed at agent init.

Scaffolding Output

create-agent.py creates:

my-agent/
  agent.py          # Entry point with model init
  tools/            # Custom tools directory
  config.yaml       # Agent config (if applicable)
  README.md         # Usage instructions

outcome signal

1. Agent responds to prompt: Call agent("Your prompt") and receive a non-empty string response. No exceptions raised.

2. Tools are invoked: Agent calls custom or pre-built tools during execution. Check agent logs or set trace_attributes and inspect OpenTelemetry spans for agent.tool_call events.

3. Tool output appears in response: Agent response includes results from tool execution (e.g., file contents, calculation results, search results). Verify by examining response text.

4. MCP tools are available: When MCPClient is active, agent can call MCP-exposed tools without error. MCP server stays connected (no connection refused errors).

5. Multi-agent handoff occurs: In Swarm, agents call handoff_to_agent and pass control. Check swarm result for handoffs key with non-empty list.

6. Session state persists: Run agent, stop process, restart with same session_manager. Agent recalls prior conversation turns. Verify by checking session file for new messages.

7. Scaffold runs without error: create-agent.py completes and agent.py is executable (python3 my-agent/agent.py "test").

8. Observability emits traces: Set OpenTelemetry exporter (e.g., OTEL_EXPORTER_OTLP_ENDPOINT), run agent, and traces appear in backend (Jaeger, Datadog, etc.). Each tool call and handoff has its own span.

9. Rate limit handled gracefully: Agent retries on 429 response; no crash. Response may be slower but eventual.

10. Timeout triggered: Swarm or Graph execution hits execution_timeout or node_timeout and halts cleanly, returning partial result with metadata (not a hang or exception).