Strand Agents SDK

https://github.com/strands-agents/docs
Admin
Strands Agents is a framework for building and running AI agents with a model-driven approach,...
Tokens:604,370
Snippets:5,218
Trust Score:7.8
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Run the example

Source: https://github.com/strands-agents/docs/blob/main/site/docs/examples/typescript/structured_output/README.md

Run this command to start the example.

```bash
npm start
```

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

### Install dependencies and run dev server

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/integrations/ag-ui.mdx

Installs npm dependencies and starts the development server. This is the final step to try out the sample app.

```bash
npm install && npm run dev
```

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

### Basic SDK Integration Setup

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Basic setup for SDK integration: import the runtime, initialize the app, and decorate your function with @app.entrypoint. The app.run() call starts the HTTP server.

```python
from bedrock_agentcore.runtime import BedrockAgentCoreApp
```

```python
app = BedrockAgentCoreApp()
```

```python
@app.entrypoint
def invoke(payload):
    # Your existing code remains unchanged
    return payload

if __name__ == "__main__":
    app.run()
```

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

### Install and run the documentation site

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

Install dependencies and run the documentation site locally. The dev server starts at http://localhost:4321/ and the build command generates a static site.

```bash
npm install
npm run dev        # starts dev server at http://localhost:4321/
npm run build      # generates static site
```

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

### Setup Commands for Banking Email Demo

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/strands-agents-with-agent-control.mdx

Commands to clone the agent-control repository, install dependencies, configure environment, start the Agent Control server, set up controls, and launch the Streamlit app.

```bash
git clone https://github.com/agentcontrol/agent-control.git
cd agent-control

# Install the Strands example dependencies
cd examples/strands_agents
uv pip install -e .

# Configure
cp .env.example .env
# Add OPENAI_API_KEY and AGENT_CONTROL_URL

# Start the Agent Control server (requires Docker)
curl -fsSL https://raw.githubusercontent.com/agentcontrol/agent-control/docker-compose.yml | docker compose -f - up -d

# Set up controls on the server (in a new terminal)
cd steering_demo
uv run setup_email_controls.py

# Launch the Streamlit app
streamlit run email_safety_demo.py
```

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

### Python example: minimal agent and configured agent with BedrockModel

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/contribute/contributing/documentation.mdx

Python example showing the recommended pattern for code examples: start with a minimal agent creation, then add configuration. The configured agent uses a BedrockModel with a specific model ID and a system prompt.

```python
# Good: Start simple
from strands import Agent
agent = Agent()
agent("Hello, world!")

# Then show configuration
from strands import Agent
from strands.models import BedrockModel

agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-20250514"),
    system_prompt="You are a helpful assistant."
)
agent("What's the weather like?")
```

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

### Set up the docs site locally with git clone, npm install, and npm run dev

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/contribute/contributing/documentation.mdx

Clone the docs repository, install dependencies, and start the local Astro development server. The server automatically reloads on save, and the preview is available at http://localhost:4321.

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

# Install dependencies
npm install

# Start the local development server
npm run dev

# Preview at http://localhost:4321
```

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

### Quick Setup All-in-One Bash Command for TypeScript Agent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx

Optional one-command setup that creates the project directory, installs dependencies, writes tsconfig.json, index.ts, and Dockerfile, and adds npm scripts. Run this to skip the remaining Project Setup steps.

```bash
setup_typescript_agent() {
# Create project directory and initialize with npm
mkdir my-typescript-agent && cd my-typescript-agent
npm init -y

# Install required dependencies
npm install @strands-agents/sdk express @types/express typescript ts-node
npm install -D @types/node

# Create TypeScript configuration
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["*.ts"],
  "exclude": ["node_modules", "dist"]
}
EOF

# Add npm scripts
npm pkg set scripts.build="tsc" scripts.start="node dist/index.js" scripts.dev="ts-node index.ts"

# Create the Express agent application
cat > index.ts << 'EOF'
import { Agent } from '@strands-agents/sdk'
import express, { type Request, type Response } from 'express'
import { OpenAIModel } from '@strands-agents/sdk/models/openai'

const PORT = Number(process.env.PORT) || 8080

// Note: Any supported model provider can be configured
// Automatically uses process.env.OPENAI_API_KEY
const model = new OpenAIModel({ api: 'chat' })

const agent = new Agent({ model })

const app = express()

// Middleware to parse JSON
app.use(express.json())

// Health check endpoint
app.get('/ping', (_: Request, res: Response) =>
  res.json({
    status: 'healthy',
  })
)

// Agent invocation endpoint
app.post('/invocations', async (req: Request, res: Response) => {
  try {
    const { input } = req.body
    const prompt = input?.prompt || ''

    if (!prompt) {
      return res.status(400).json({
        detail: 'No prompt found in input. Please provide a "prompt" key in the input.'
      })
    }

    // Invoke the agent
    const result = await agent.invoke(prompt)

    const response = {
      message: result,
      timestamp: new Date().toISOString(),
      model: 'strands-agent',
    }

    return res.json({ output: response })
  } catch (err) {
    console.error('Error processing request:', err)
    return res.status(500).json({
      detail: `Agent processing failed: ${err instanceof Error ? err.message : 'Unknown error'}`
    })
  }
})

// Start server
app.listen(PORT, '0.0.0.0', () => {
  console.log(`🚀 Strands Agent Server listening on port ${PORT}`)
  console.log(`📍 Endpoints:`)
  console.log(`   POST http://0.0.0.0:${PORT}/invocations`)
  console.log(`   GET  http://0.0.0.0:${PORT}/ping`)
})
EOF

# Create Docker configuration
cat > Dockerfile << 'EOF'
# Use Node 20+
FROM node:20

WORKDIR /app

# Copy source code
COPY . ./

# Install dependencies
RUN npm install

# Build TypeScript
RUN npm run build

# Expose port
EXPOSE 8080

# Start the application
CMD ["npm", "start"]
EOF

echo "Setup complete! Project created in my-typescript-agent/"
}

# Run the setup
setup_typescript_agent
```

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

### Manual installation from source

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/examples/python/cli-reference-agent.mdx

Manual installation steps: clone the repository, create and activate a virtual environment, install dependencies, and create a symlink to the strands executable.

```bash
# Clone repository
git clone https://github.com/strands-agents/agent-builder /path/to/custom/location

# Create virtual environment
cd /path/to/custom/location
python -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -e .

# Create symlink
sudo ln -sf /path/to/custom/location/venv/bin/strands /usr/local/bin/strands
```

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

### Example output from code-assist agent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/introducing-strands-agent-sops.mdx

Example output from the code-assist agent after starting the SOP. Shows the agent requesting required and optional parameters, including task_description, documentation_dir, repo_root, task_name, and mode.

```text
I'll help you implement a code task using the test-driven development workflow. Let me gather the required parameters to get started.

Please provide the following information:

**Required:**
- **task_description**: What would you like to implement? (You can provide a detailed specification, requirements, acceptance criteria, or even a rough idea that we'll refine together. You can also provide a file path or URL if the description is in a document)

**Optional:**
- **additional_context**: Any supplementary information that would help with understanding the implementation context (can also be a file path or URL)
- **documentation_dir**: Directory for planning documents (default: ".sop/planning")
- **repo_root**: Root directory of the repository (default: current working directory)
- **task_name**: A short, descriptive name for the task (I'll generate one if not provided)
- **mode**: Interaction mode:
  - "interactive" (default): I'll collaborate with you and ask for confirmation at each step
  - "auto": I'll execute autonomously after setup with no further interaction required

Please provide these details so we can begin the implementation process.
```

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

### Install SDK on Linux (Ubuntu/Debian)

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx

Install PortAudio development files and PyAudio on Ubuntu/Debian, then install the SDK with all providers.

```bash
sudo apt-get install portaudio19-dev python3-pyaudio
pip install "strands-agents[bidi-all]"
```

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

### Start SGLang Server with Qwen3-4B-Instruct-2507

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/model-providers/sglang.mdx

Launches an SGLang server on port 30000 with the specified model. Required before using the SGLangModel in agent examples.

```bash
python -m sglang.launch_server \
    --model-path Qwen/Qwen3-4B-Instruct-2507 \
    --port 30000 \
    --host 0.0.0.0
```

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

### Install all bidirectional streaming providers

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx

Install all bidirectional streaming providers at once.

```bash
pip install 'strands-agents[bidi-all]'
```

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

### Install dependencies and prepare environment

Source: https://github.com/strands-agents/docs/blob/main/site/docs/examples/cdk/deploy_to_apprunner/README.md

Commands to install Node.js and Python dependencies, create a virtual environment, and install Python packages from requirements.txt.

```bash
# Install Node.js dependencies including CDK and TypeScript locally
npm install

# Create a Python virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install Python dependencies for the local development
pip install -r ./docker/requirements.txt
```

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

### Complete Strands robot agent example

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/robots.mdx

Complete example for setting up a Strands robot agent with a GR00T inference service. It creates a Robot with two OpenCV cameras, builds an Agent with the robot and tools, starts the inference service, runs an interactive command loop, and stops the service on exit.

```python
from strands import Agent
from strands_robots import Robot, gr00t_inference, lerobot_camera, pose_tool

robot = Robot(
    tool_name="orange_arm",
    robot="so101_follower",
    cameras={
        "wrist": {"type": "opencv", "index_or_path": "/dev/video0", "fps": 15},
        "front": {"type": "opencv", "index_or_path": "/dev/video2", "fps": 15},
    },
    port="/dev/ttyACM0",
    data_config="so100_dualcam",
)

agent = Agent(tools=[robot, gr00t_inference, lerobot_camera, pose_tool])

agent.tool.gr00t_inference(
    action="start",
    checkpoint_path="/data/checkpoints/gr00t-wave/checkpoint-300000",
    port=5555,
    data_config="so100_dualcam",
)

while True:
    user_input = input("\n> ")
    if user_input.lower() in ["exit", "quit"]:
        break
    agent(user_input)

agent.tool.gr00t_inference(action="stop", port=5555)
```

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

### Build and Start Server

Source: https://github.com/strands-agents/docs/blob/main/site/docs/examples/typescript/deploy_to_bedrock_agentcore/README.md

Builds the TypeScript project and starts the server locally.

```bash
npm run build
npm start
```

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

### Install bidi-io extra for BidiAudioIO

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/io.mdx

Installs the `bidi-io` extra required for `BidiAudioIO`.

```bash
pip install "strands-agents[bidi,bidi-io]"
```

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

### Install strands-hubspot

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-hubspot.mdx

Install the strands-hubspot package from PyPI.

```bash
pip install strands-hubspot
```

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

### Install strands-valkey-session-manager

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/session-managers/strands-valkey-session-manager.mdx

Install the package via pip.

```bash
pip install strands-valkey-session-manager
```

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

### Install strands-agents-spraay

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-spraay.mdx

Install the strands-agents-spraay package from PyPI.

```bash
pip install strands-agents-spraay
```

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

### Install strands-google with pip

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-google.mdx

Install the strands-google package using pip.

```bash
pip install strands-google
```

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

### Install strands-perplexity with pip

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-perplexity.mdx

Install the package using pip.

```bash
pip install strands-perplexity
```

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

### Step 1: Create Project Directory and Initialize

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx

Creates the project directory and initializes a Python 3.11 project with uv.

```bash
mkdir my-python-agent && cd my-python-agent
uv init --python 3.11
```

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

### Set up AgentControlPlugin and AgentControlSteeringHandler for Strands

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/plugins/agent-control.mdx

These two examples show the standard setup for the AgentControlPlugin and the advanced setup with AgentControlSteeringHandler for output correction. The first registers the plugin to deny tool calls raised as exceptions, while the second converts steer matches into Guide() retries. Use them together to cover both deny and steer controls in a Strands agent.

```python
import agent_control
from agent_control.integrations.strands import AgentControlPlugin
from strands import Agent
from strands.models.openai import OpenAIModel

# Initialize once at startup — registers the agent and fetches controls
agent_control.init(agent_name="my-agent")

# Attach the plugin — all lifecycle events are intercepted automatically
agent_control_plugin = AgentControlPlugin(agent_name="my-agent")

agent = Agent(
    model=OpenAIModel(model_id="gpt-4o-mini"),
    system_prompt="You are a helpful assistant.",
    tools=[...],
    plugins=[agent_control_plugin],
)

result = await agent.invoke_async("Hello!")
```

```python
from agent_control.integrations.strands import AgentControlPlugin, AgentControlSteeringHandler
from strands.hooks import BeforeToolCallEvent, AfterToolCallEvent

# Plugin handles tool-stage deny checks
agent_control_plugin = AgentControlPlugin(
    agent_name="my-agent",
    event_control_list=[BeforeToolCallEvent, AfterToolCallEvent],
)

# Steering handler converts steer matches into Strands Guide() retries
steering = AgentControlSteeringHandler(agent_name="my-agent")

agent = Agent(
    model=model,
    system_prompt="...",
    tools=[...],
    plugins=[agent_control_plugin, steering],  # both registered as plugins
)
```

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

### Install uv

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx

Installs the uv package manager, required for the project setup steps.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Install LLM Guard

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/safety-security/pii-redaction.mdx

Installs the LLM Guard library, which is used for PII detection and redaction in the integration guide.

```bash
pip install llm-guard
```

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

### Initialize and run BidiGeminiLiveModel

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/models/gemini_live.mdx

Shows how to import and initialize the Gemini Live provider, create an agent with tools, and run it with audio and text I/O.

```python
import asyncio

from strands.experimental.bidi import BidiAgent
from strands.experimental.bidi.io import BidiAudioIO, BidiTextIO
from strands.experimental.bidi.models import BidiGeminiLiveModel
from strands_tools import stop

from strands_tools import calculator


async def main() -> None:
    model = BidiGeminiLiveModel(
        model_id="gemini-2.5-flash-native-audio-preview-09-2025",
        provider_config={
            "audio": {
                "voice": "Kore",
            },
        },
        client_config={"api_key": "<GOOGLE_AI_API_KEY>"},
    )
    # stop tool allows user to verbally stop agent execution.
    agent = BidiAgent(model=model, tools=[calculator, stop])

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


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

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

### Install strands-ai-functions with pip or uv

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/ai-functions.mdx

Install the strands-ai-functions package using either pip or uv. The uv command is recommended for running the provided examples.

```bash
pip install strands-ai-functions
```

```bash
uv add strands-ai-functions
```

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

### Basic Setup with ValkeySessionManager

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/session-managers/strands-valkey-session-manager.mdx

Create a Valkey client, instantiate a ValkeySessionManager with a unique session ID, create an Agent, and use it. Messages are automatically persisted and can be listed later.

```python
from strands import Agent
from strands_valkey_session_manager import ValkeySessionManager
from uuid import uuid4
import valkey

# Create a Valkey client
client = valkey.Valkey(host="localhost", port=6379, decode_responses=True)

# Create a session manager with a unique session ID
session_id = str(uuid4())
session_manager = ValkeySessionManager(
    session_id=session_id,
    client=client
)

# Create an agent with the session manager
agent = Agent(session_manager=session_manager)

# Use the agent - all messages are automatically persisted
agent("Hello! Tell me about Valkey.")

# The conversation is now stored in Valkey and can be resumed later using the same session_id

# Display conversation history
messages = session_manager.list_messages(session_id, agent.agent_id)
for msg in messages:
    role = msg.message["role"]
    content = msg.message["content"][0]["text"]
    print(f"** {role.upper()}**: {content}")
```

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

### Install strands-sglang and Strands Agents SDK

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/model-providers/sglang.mdx

Install the strands-sglang package along with the Strands Agents SDK using pip. This is the required setup for using the SGLang provider.

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

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

### Create Project Directory and Initialize npm

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx

Step 1: Creates the project directory and initializes a new npm package with default settings.

```bash
mkdir my-typescript-agent && cd my-typescript-agent
npm init -y
```

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

### Complete Example: Multi-Step Dataset Generation

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/evals-sdk/experiment_generator.mdx

Complete example showing multi-step dataset generation: initial generation with topic planning, expansion with update_current_experiment_async, adding a helpfulness evaluator, saving to file, and examining results.

```python
import asyncio
from strands_evals.generators import ExperimentGenerator
from strands_evals.evaluators import TrajectoryEvaluator, HelpfulnessEvaluator

async def create_comprehensive_dataset():
    # Initialize generator with trajectory support
    generator = ExperimentGenerator[str, str](
        input_type=str,
        output_type=str,
        include_expected_output=True,
        include_expected_trajectory=True,
        include_metadata=True
    )
    
    # Step 1: Generate initial experiment with topic planning
    print("Step 1: Generating initial experiment...")
    experiment = await generator.from_context_async(
        context="""
        Multi-agent system with:
        - Research agent: Searches and analyzes information
        - Writing agent: Creates content and summaries
        - Review agent: Validates and improves outputs
        
        Tools available:
        - web_search(query: str) -> str
        - summarize(text: str) -> str
        - fact_check(claim: str) -> bool
        """,
        task_description="Research and content creation assistant",
        num_cases=15,
        num_topics=3,  # Research, Writing, Review
        evaluator=TrajectoryEvaluator
    )
    
    print(f"Generated {len(experiment.cases)} cases across 3 topics")
    
    # Step 2: Add more cases to expand coverage
    print("\nStep 2: Expanding experiment...")
    expanded_experiment = await generator.update_current_experiment_async(
        source_experiment=experiment,
        task_description="Research and content creation with edge cases",
        num_cases=5,
        context="Focus on error handling and complex multi-step scenarios",
        add_new_cases=True,
        add_new_rubric=False  # Keep existing rubric
    )
    
    print(f"Expanded to {len(expanded_experiment.cases)} total cases")
    
    # Step 3: Add helpfulness evaluator
    print("\nStep 3: Adding helpfulness evaluator...")
    helpfulness_eval = await generator.construct_evaluator_async(
        prompt="Evaluate helpfulness for research and content creation tasks",
        evaluator=HelpfulnessEvaluator
    )
    expanded_experiment.evaluators.append(helpfulness_eval)
    
    # Step 4: Save experiment
    expanded_experiment.to_file("comprehensive_dataset", "json")
    print("\nDataset saved to ./experiment_files/comprehensive_dataset.json")
    
    return expanded_experiment

# Run the multi-step generation
experiment = asyncio.run(create_comprehensive_dataset())

# Examine results
print(f"\nFinal experiment:")
print(f"- Total cases: {len(experiment.cases)}")
print(f"- Evaluators: {len(experiment.evaluators)}")
print(f"- Categories: {set(c.metadata.get('category', 'unknown') for c in experiment.cases if c.metadata)}")
```

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

### Setup Evaluation Project

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/evals-sdk/eval-sop.mdx

Create a self-contained evaluation workspace and copy your agent into it.

```bash
mkdir agent-evaluation-project
cd agent-evaluation-project

# Copy your agent to evaluate (must be self-contained)
cp -r /path/to/your/agent .
```

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

### Teleoperation tool start action

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/robots.mdx

Start recording demonstrations for imitation learning using a leader-follower teleoperation setup. Specify the follower robot, leader teleop device, and dataset details.

```python
from strands_robots import lerobot_teleoperate

agent.tool.lerobot_teleoperate(
    action="start",
    robot_type="so101_follower",
    robot_port="/dev/ttyACM0",
    teleop_type="so101_leader",
    teleop_port="/dev/ttyACM1",
    dataset_repo_id="my_user/cube_picking",
    dataset_single_task="Pick up the red cube",
    dataset_num_episodes=50,
)
```

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

### Manual start() and stop() lifecycle control

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx

Manually control the agent lifecycle by calling start() and stop() explicitly. Use this when you need to manage the agent's start and stop outside of the run() method. The example sends a message and waits for a BidiResponseCompleteEvent before stopping.

```python
import asyncio
from strands.experimental.bidi import BidiAgent
from strands.experimental.bidi.models import BidiNovaSonicModel
from strands.experimental.bidi.types.events import BidiResponseCompleteEvent

async def main():
    model = BidiNovaSonicModel()
    agent = BidiAgent(model=model)
    
    # Manually start the agent
    await agent.start()
    
    try:
        await agent.send("What is Python?")
        
        async for event in agent.receive():
            if isinstance(event, BidiResponseCompleteEvent):
                break
    finally:
        # Always stop after exiting receive loop
        await agent.stop()

asyncio.run(main())
```

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

### Quick Start with MCPClient in Python

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/tools/mcp-tools.mdx

Quick start example for Python: creates an MCP client using stdio transport and passes it directly to the Agent constructor. The connection lifecycle is managed automatically.

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

# Create MCP client with stdio transport
mcp_client = MCPClient(lambda: stdio_client(
    StdioServerParameters(
        command="uvx",
        args=["awslabs.aws-documentation-mcp-server@latest"]
    )
))

# Pass MCP client directly to agent - lifecycle managed automatically
agent = Agent(tools=[mcp_client])
agent("What is AWS Lambda?")
```

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

### Install AgentCore Starter Toolkit

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Install the bedrock-agentcore-starter-toolkit package via pip for quick prototyping. This method is being superseded by the AgentCore CLI (@aws/agentcore), which is now recommended for new projects.

```bash
pip install bedrock-agentcore-starter-toolkit
```

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

### Quick Setup All-in-One Bash Command

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/python.mdx

Optional all-in-one bash command that creates the project directory, initializes uv, adds dependencies, writes agent.py and Dockerfile, and prints a completion message. It removes the auto-generated main.py.

```bash
setup_agent() {
mkdir my-python-agent && cd my-python-agent
uv init --python 3.11
uv add fastapi "uvicorn[standard]" pydantic strands-agents "strands-agents[openai]"

# Remove the auto-generated main.py
rm -f main.py

cat > agent.py << 'EOF'
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime, timezone
from strands import Agent
from strands.models.openai import OpenAIModel

app = FastAPI(title="Strands Agent Server", version="1.0.0")

# Note: Any supported model provider can be configured
# Automatically uses process.env.OPENAI_API_KEY
model = OpenAIModel(model_id="gpt-4o")

strands_agent = Agent(model=model)

class InvocationRequest(BaseModel):
    input: Dict[str, Any]

class InvocationResponse(BaseModel):
    output: Dict[str, Any]

@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
    try:
        user_message = request.input.get("prompt", "")
        if not user_message:
            raise HTTPException(
                status_code=400,
                detail="No prompt found in input. Please provide a 'prompt' key in the input."
            )

        result = strands_agent(user_message)
        response = {
            "message": result.message,
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "model": "strands-agent",
        }

        return InvocationResponse(output=response)

    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Agent processing failed: {str(e)}")

@app.get("/ping")
async def ping():
    return {"status": "healthy"}

def main():
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080)

if __name__ == "__main__":
    main()
EOF

cat > Dockerfile << 'EOF'
# Use uv's Python base image
FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim

WORKDIR /app

# Copy uv files
COPY pyproject.toml uv.lock ./

# Install dependencies
RUN uv sync --frozen --no-cache

# Copy agent file
COPY agent.py ./

# Expose port
EXPOSE 8080

# Run application
CMD ["uv", "run", "python", "agent.py"]
EOF

echo "Setup complete! Project created in my-python-agent/"
}

setup_agent
```

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

### TypeScript ModelContentBlockStartEvent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/model-providers/custom_model_provider.mdx

Signals the start of a content block. Includes separate examples for text blocks and tool use blocks.

```typescript
// For text blocks
const textBlockStart: ModelContentBlockStartEventData = {
  type: 'modelContentBlockStartEvent',
}
```

```typescript
// For tool use blocks
const toolUseStart: ModelContentBlockStartEventData = {
  type: 'modelContentBlockStartEvent',
  start: {
    type: 'toolUseStart',
    toolUseId: 'tool_123',
    name: 'calculator',
  },
}
```

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

### Project Structure for Starter Toolkit

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Shows the required directory structure for a Starter Toolkit project: agent_example.py, requirements.txt, and __init__.py.

```text
your_project_directory/
├── agent_example.py # Your main agent code
├── requirements.txt # Dependencies for your agent
└── __init__.py # Makes the directory a Python package
```

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

### Create a basic agent with the Strands Agents TypeScript SDK

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/strands-agents-typescript-v1.mdx

Import the Agent class and create a simple agent. This is the quick start example.

```typescript
import { Agent } from '@strands-agents/sdk'

--8<-- "../blog/strands-agents-typescript-v1.ts:hello_world"
```

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

### Create Dockerfile for TypeScript Agent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_docker/typescript.mdx

Step 6: Dockerfile that uses Node 20, copies the source, installs dependencies, builds TypeScript, exposes port 8080, and starts the application.

```dockerfile
# Use Node 20+
FROM node:20

WORKDIR /app

# Copy source code
COPY . ./

# Install dependencies
RUN npm install

# Build TypeScript
RUN npm run build

# Expose port
EXPOSE 8080

# Start the application
CMD ["npm", "start"]
```

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

### Deploy with Starter Toolkit CLI

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Commands to configure, optionally test locally, deploy to AWS, and invoke the agent using the AgentCore CLI. The local deploy requires Docker, Finch, or Podman.

```bash
# Configure your agent
agentcore configure --entrypoint agent_example.py

# Optional: Local testing (requires Docker, Finch, or Podman)
agentcore deploy --local

# Deploy to AWS
agentcore deploy

# Test your agent with CLI
agentcore invoke '{"prompt": "Hello"}'
```

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

### Python tool interrupt example

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/interrupts.mdx

Shows how to define a tool that raises an interrupt using `tool_context.interrupt` with a unique name and reason. The tool returns `False` if the approval is not 'y'. Includes an `Agent` setup with the tool and a callback handler.

```python
from typing import Any

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


class DeleteTool:
    def __init__(self, app_name: str) -> None:
        self.app_name = app_name

    @tool(context=True)
    def delete_files(self, tool_context: ToolContext, paths: list[str]) -> bool:
        approval = tool_context.interrupt(f"{self.app_name}-approval", reason={"paths": paths})
        if approval.lower() != "y":
            return False

        # Implementation here

        return True


@tool
def inspect_files(paths: list[str]) -> dict[str, Any]:
    # Implementation here
    pass


agent = Agent(
    system_prompt="You delete files older than 5 days",
    tools=[DeleteTool("myapp").delete_files, inspect_files],
    callback_handler=None,
)

...
```

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

### Create Dockerfile for deployment

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/typescript.mdx

This Dockerfile sets up a Node.js environment on linux/arm64, copies the source, installs dependencies, builds the TypeScript project, exposes port 8080, and starts the application. Use this to containerize the agent service for deployment.

```dockerfile
FROM --platform=linux/arm64 public.ecr.aws/docker/library/node:latest

WORKDIR /app

# Copy source code
COPY . ./

# Install dependencies
RUN npm install

# Build TypeScript
RUN npm run build

# Expose port
EXPOSE 8080

# Start the application
CMD ["npm", "start"]
```

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

### Basic A2A server setup in Python

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/multi-agent/agent-to-agent.mdx

Creates a Strands agent with a calculator tool and starts an A2A server with streaming enabled by default. The server serves the agent card at /.well-known/agent-card.json and handles JSON-RPC requests at the root path.

```python
import logging
from strands_tools.calculator import calculator
from strands import Agent
from strands.multiagent.a2a import A2AServer

logging.basicConfig(level=logging.INFO)

# Create a Strands agent
strands_agent = Agent(
    name="Calculator Agent",
    description="A calculator agent that can perform basic arithmetic operations.",
    tools=[calculator],
    callback_handler=None
)

# Create A2A server (streaming enabled by default)
a2a_server = A2AServer(agent=strands_agent)

# Start the server
a2a_server.serve()
```

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

### Clone the examples repository

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/examples/README.mdx

Clone the Strands Agents documentation repository and navigate to the examples directory.

```bash
git clone https://github.com/strands-agents/docs.git
cd docs/docs/examples
```

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

### Run Libero simulation with GR00T policy using SimEnv

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/introducing-strands-labs.mdx

Initializes a Libero simulation environment, starts the GR00T inference service on port 8000, randomly selects a task, and controls the robot via natural language for a specified number of episodes. Requires Libero installed, GR00T inference service operational, and Docker with isaac-gr00t containers accessible. Prints final status or an error with installation instructions.

```python
import asyncio
import argparse
import random
from strands import Agent
from strands_robots_sim import SimEnv, gr00t_inference

def main(max_episodes=10):
    # Create simulation environment
    sim_env = SimEnv(
        tool_name="my_libero_sim",
        env_type="libero",
        task_suite="libero_10",
        data_config="libero_10"
    )

    # Create agent
    agent = Agent(tools=[sim_env, gr00t_inference])

    try:
       # Start GR00T inference
        result = agent.tool.gr00t_inference(
            action="start",
            checkpoint_path="/data/checkpoints/gr00t-n1.5-libero-long-posttrain",
            port=8000,
            data_config="examples.Libero.custom_data_config:LiberoDataConfig"
        )

        async def init_sim_env():
            return await sim_env.sim_env.initialize()

        if not asyncio.run(init_sim_env()):
            raise RuntimeError("Failed to initialize simulation environment")

        # Randomly select a task
        selected_task = random.choice(sim_env.sim_env.available_tasks)

        # Set the task name in the environment
        sim_env.sim_env.set_task_name(selected_task)

        # Control simulated robot with natural language
        agent(f"Run the task '{selected_task}' for {max_episodes} episode(s) with max_steps_per_episode=500 and record video")

        # Check final status
        final_status = agent.tool.my_libero_sim(action="status")
        print(f"Final status: {final_status}")
    except Exception as e:
        print(f"Example failed with error: {e}")
        print("- Install simulation dependencies: pip install strands-robots[sim]")

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Run Libero simulation with GR00T policy')
    parser.add_argument('--max-episodes', type=int, default=10,
                        help='Maximum number of episodes to run (default: 10)')
    args = parser.parse_args()
    main(max_episodes=args.max_episodes)
```

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

### Simulate a flight search tool with initial state and run an agent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/toolsimulator-scalable-tool-testing-ai-agents.mdx

Complete example that creates a simulator, registers a tool with an initial_state_description, retrieves the simulated tool via get_tool(), attaches it to an Agent, and runs the agent. The agent call triggers the mocked tool response.

```python
from strands import Agent
from strands_evals.simulation.tool_simulator import ToolSimulator

# 1. Create a simulator instance
tool_simulator = ToolSimulator()

# 2. Register a tool for simulation with initial state context
@tool_simulator.tool(
    initial_state_description="Flight database: SEA->JFK flights available at 8am, 12pm, and 6pm. Prices range from $180 to $420.",
)
def search_flights(origin: str, destination: str, date: str) -> dict:
    """Search for available flights between two airports on a given date."""
    pass

# 3. Create an agent with the simulated tool and run it
flight_tool = tool_simulator.get_tool("search_flights")
agent = Agent(
    system_prompt="You are a flight search assistant.",
    tools=[flight_tool],
)

response = agent("Find me flights from Seattle to New York on March 15.")
print(response)
```

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

### Example requirements.txt

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Lists the dependencies for the agent: strands-agents and bedrock-agentcore.

```text
strands-agents
bedrock-agentcore
```

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

### Stepped execution mode with SteppedSimEnv and gr00t_inference

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/robots-sim.mdx

Complete example of stepped execution mode where the agent plans and adapts. It sets up a SteppedSimEnv with Libero configuration, starts the gr00t inference server, runs the agent with a task prompt, and stops the server.

```python
from strands import Agent
from strands_robots_sim import SteppedSimEnv, gr00t_inference

stepped_sim = SteppedSimEnv(
    tool_name="my_stepped_sim",
    env_type="libero",
    task_suite="libero_10",
    data_config="libero_10",
    steps_per_call=10,
    max_steps_per_episode=500,
)

agent = Agent(tools=[stepped_sim, gr00t_inference])

agent.tool.gr00t_inference(
    action="start",
    checkpoint_path="/data/checkpoints/model",
    port=8000,
    data_config="examples.Libero.custom_data_config:LiberoDataConfig",
)

agent("""
Task: open the top drawer

You are a robot task planner. Decompose this task into subtasks and execute
them step-by-step using the my_stepped_sim tool.

1. Reset the episode with action="reset_episode"
2. For each subtask, call action="execute_steps" with the subtask as instruction
3. Observe camera images and state after each batch
4. Adapt your approach based on what you see
5. Continue until reward reaches 1.0 or the episode ends
""")

agent.tool.gr00t_inference(action="stop", port=8000)
```

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

### Install dependencies and run the agent

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/introducing-strands-agents.mdx

Install the required packages and run the agent. The -u flag ensures unbuffered output so you can see the agent's progress in real time.

```bash
pip install strands-agents strands-agents-tools
python -u agent.py
```

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

### Configure EC2 user data script for application setup

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_amazon_ec2.mdx

Creates a user data script for the EC2 instance that installs Python and dependencies, downloads and extracts the application and dependency packages from S3, and sets up the application as a systemd service with a specified ExecStart command.

```typescript
 // Create user data script to set up the application
 const userData = ec2.UserData.forLinux();
 userData.addCommands(
   "#!/bin/bash",
   "set -o verbose",
   "yum update -y",
   "yum install -y python3.12 python3.12-pip git unzip ec2-install-connect",

   // Create app directory
   "mkdir -p /opt/agent-app",

   // Download application files from S3
   `aws s3 cp ${appAsset.s3ObjectUrl} /tmp/app.zip`,
   `aws s3 cp ${dependenciesAsset.s3ObjectUrl} /tmp/dependencies.zip`,

   // Extract application files
   "unzip /tmp/app.zip -d /opt/agent-app",
   "unzip /tmp/dependencies.zip -d /opt/agent-app/_dependencies",

   // Create a systemd service file
   "cat > /etc/systemd/system/agent-app.service << 'EOL'",
   "[Unit]",
   "Description=Weather Agent Application",
   "After=network.target",
   "",
   "[Service]",
   "User=ec2-user",
   "WorkingDirectory=/opt/agent-app",
   "ExecStart=/usr/bin/python3.12 -m uvicorn app:app --host=0.0.0.0 --port=8000 --workers=2",
   "Restart=always",
   "Environment=PYTHONPATH=/opt/agent-app:/opt/agent-app/_dependencies",
   "Environment=LOG_LEVEL=INFO",
   "",
   "[Install]",
   "WantedBy=multi-user.target",
   "EOL",

   // Enable and start the service
   "systemctl enable agent-app.service",
   "systemctl start agent-app.service",
 );
```

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

### SteppedSimEnv iterative agent control

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/robots-sim.mdx

Use SteppedSimEnv for iterative control where the agent acts as a planner. It executes a limited number of steps per call and receives camera images and state back. The example shows resetting to a specific task, executing steps, and getting state.

```python
from strands_robots_sim import SteppedSimEnv

stepped_sim = SteppedSimEnv(
    tool_name="my_stepped_sim",
    env_type="libero",
    task_suite="libero_10",
    data_config="libero_10",
    steps_per_call=10,
    max_steps_per_episode=500,
)

agent = Agent(tools=[stepped_sim, gr00t_inference])

# Reset to a specific task
agent.tool.my_stepped_sim(
    action="reset_episode",
    task_name="KITCHEN_SCENE1_put_the_black_bowl_on_top_of_the_cabinet",
)

# Execute steps - returns camera images, state, reward, done status
agent.tool.my_stepped_sim(
    action="execute_steps",
    instruction="move gripper toward the bowl",
    policy_port=8000,
    num_steps=10,
)

# Agent observes the result and decides what to do next
agent.tool.my_stepped_sim(action="get_state")
```

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

### Run the browser agent example

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/strands-agents-typescript-sdk.mdx

Clone the repository and run the browser agent example, which demonstrates an AI agent manipulating a live canvas element through natural language.

```bash
git clone https://github.com/strands-agents/sdk-typescript.git
cd sdk-typescript/strands-ts/examples/browser-agent
npm install && npm run dev
```

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

### Run the graph loops example

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/examples/python/graph_loops_example.mdx

Basic usage to run the example script from the command line.

```bash
python graph_loops_example.py
```

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

### BidiAgent low-level send/receive usage

Source: https://github.com/strands-agents/docs/blob/main/site/team/DECISIONS.md

Low-level usage of BidiAgent's send and receive APIs. Requires managing concurrency, lifecycle, and event routing manually. The example shows starting the agent, reading input events and sending them, receiving events in a loop, and stopping the agent.

```python
await agent.start()

async def read_input():
    while True:
        event = await input_source.read()
        await agent.send(event)

asyncio.create_task(read_input())

async for event in agent.receive():
    ...

await agent.stop()
```

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

### Create a Strands Agent with Claude 4 Sonnet and tools

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/blog/interleaved-thinking-claude-4.mdx

Define an agent with the Strands SDK, using the Claude 4 Sonnet model and two built-in tools: http_request and python_repl. The prompt asks for the closest city to the ISS and includes the current altitude, distance, and vector. This example assumes you have completed the quickstart.

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

agent = Agent(
    model="us.anthropic.claude-sonnet-4-20250514-v1:0",
    tools=[http_request, python_repl]
)

prompt="""
Which of the following cities is closest to the ISS?
Portland, Vancouver, Seattle, or New York?

Include the current altitude of the ISS, and the distance and vector from the closest city to the ISS.
"""

agent(prompt)
```

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

### Setup Docker buildx

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Creates and activates a Docker buildx builder, required for building ARM64 images.

```bash
docker buildx create --use
```

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

### Install SDK for Google Gemini Live

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/concepts/bidirectional-streaming/quickstart.mdx

Install the SDK for Google Gemini Live. The first command includes local audio I/O; the second is for server-side deployments without PyAudio.

```bash
# With local audio I/O
pip install "strands-agents[bidi,bidi-io,bidi-gemini]"

# Server-side only
pip install "strands-agents[bidi,bidi-gemini]"
```

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

### Install strands-robots-sim

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/labs/robots-sim.mdx

Install the strands-robots-sim library. The second command installs additional dependencies for simulation environments like Libero.

```bash
pip install strands-robots-sim

# For simulation environment dependencies (e.g. Libero)
pip install strands-robots-sim[sim]
```

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

### Install dependencies with npm install

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

Installs the project dependencies required for local development. Requires Node.js 20+ and npm.

```bash
npm install
```

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

### Clone and set up Python SDK repository

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/contribute/contributing/core-sdk.mdx

Clones the Python SDK repository and enters the directory. This is the first step in setting up the Python development environment.

```bash
git clone https://github.com/strands-agents/sdk-python.git
cd sdk-python
```

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

### Run OAuth authentication helper

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-google.mdx

Run the authentication helper to set up OAuth.

```bash
python -m strands_google.google_auth
```

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

### Install and run Strands CLI with pipx

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/examples/python/cli-reference-agent.mdx

Standard installation using pipx. Installs the strands-agents-builder package and runs the Strands CLI.

```bash
# Install
pipx install strands-agents-builder

# Run Strands CLI
strands
```

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

### Install openai dependency for troubleshooting

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/model-providers/fireworksai.mdx

Installation command shown in troubleshooting when the `openai` module is missing. Ensures the OpenAI compatibility package is installed.

```bash
pip install 'strands-agents[openai]'
```

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

### Project Structure

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/user-guide/deploy/deploy_to_bedrock_agentcore/python.mdx

Shows the expected project structure after running the setup commands, with agent.py and Dockerfile to be created in later steps.

```text
my-custom-agent/
├── agent.py                 # FastAPI application
├── Dockerfile               # ARM64 container configuration
├── pyproject.toml          # Created by uv init
└── uv.lock                 # Created automatically by uv
```

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

### Install strands-telegram

Source: https://github.com/strands-agents/docs/blob/main/site/src/content/docs/community/tools/strands-telegram.mdx

Install the strands-telegram package from PyPI.

```bash
pip install strands-telegram
```
Tokens:
Raw