Python Strands Agent

Generate a Python Strands Agent for building AI agents with tools, and optionally deploy it to Amazon Bedrock AgentCore Runtime.

What is Strands?

Strands is a lightweight, production-ready Python framework for building AI agents. Key features include:

• Lightweight and customizable: Simple agent loop that gets out of your way
• Production ready: Full observability, tracing, and deployment options for scale
• Model and provider agnostic: Supports many different models from various providers
• Community-driven tools: Powerful set of community-contributed tools
• Multi-agent support: Advanced techniques like agent teams and autonomous agents
• Flexible interaction modes: Conversational, streaming, and non-streaming support

Usage

Generate a Strands Agent

You can generate a Python Strands Agent in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - py#strands-agent
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent

yarn

yarn nx g @aws/nx-plugin:py#strands-agent

npm

npx nx g @aws/nx-plugin:py#strands-agent

bun

bunx nx g @aws/nx-plugin:py#strands-agent

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:py#strands-agent --dry-run

yarn

yarn nx g @aws/nx-plugin:py#strands-agent --dry-run

npm

npx nx g @aws/nx-plugin:py#strands-agent --dry-run

bun

bunx nx g @aws/nx-plugin:py#strands-agent --dry-run

Tip

First use the py#project generator to create a project to add your Strands Agent to.

Options

Parameter	Type	Default	Description
project Required	string	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

Generator Output

The generator will add the following files to your existing Python project:

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (or custom name if specified)

      • __init__.py Python package initialization
      • agent.py Main agent definition with sample tools
      • main.py Entry point for Bedrock AgentCore Runtime
      • agentcore_mcp_client.py Client factory useful for invoking MCP servers also hosted on Bedrock AgentCore runtime
      • Dockerfile Entry point for hosting your agent (excluded when computeType is set to None)
  • pyproject.toml Updated with Strands dependencies
  • project.json Updated with agent serve targets

Infrastructure

Note

If you selected None for computeType, the generator will not vend any infrastructure as code.

Since this generator vends infrastructure as code based on your chosen iacProvider, it will create a project in packages/common which includes the relevant CDK constructs or Terraform modules.

The common infrastructure as code project is structured as follows:

CDK

• Directorypackages/common/constructs

  • Directorysrc

    • Directoryapp/ Constructs for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic constructs which are reused by constructs in app

      • …
    • index.ts Entry point exporting constructs from app
  • project.json Project build targets and configuration

Note

This project is generated using the ts#project generator and therefore configures the same build targets.

Terraform

• Directorypackages/common/terraform

  • Directorysrc

    • Directoryapp/ Terraform modules for infrastructure specific to a project/generator

      • …
    • Directorycore/ Generic modules which are reused by modules in app

      • …
  • project.json Project build targets and configuration

Note

This project is generated using the terraform#project generator and therefore configures the same build targets.

For deploying your Strands Agent, the following files are generated:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts CDK construct for deploying your agent
        • Dockerfile Passthrough docker file used by the CDK construct
  • Directorycore

    • Directoryagent-core

      • runtime.ts Generic CDK construct for deploying to Bedrock AgentCore Runtime

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Module for deploying your agent
  • Directorycore

    • Directoryagent-core

      • runtime.tf Generic module for deploying to Bedrock AgentCore Runtime

Working with Your Strands Agent

Adding Tools

Tools are functions that the AI agent can call to perform actions. The Strands framework uses a simple decorator-based approach for defining tools.

You can add new tools in the agent.py file:

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

The Strands framework automatically handles:

• Type validation based on your function’s type hints
• JSON schema generation for tool calling
• Error handling and response formatting

Using Pre-built Tools

Strands provides a collection of pre-built tools through the strands-tools package:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

Model Configuration

By default, Strands agents use Claude 4 Sonnet, but you can customize the model provider. See the Strands documentation on model providers for configuration options:

from strands import Agent
from strands.models import BedrockModel

# Create a BedrockModel
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

Consuming MCP Servers

You can add tools from MCP servers to your Strands agent.

For consuming MCP Servers which you have created using the py#mcp-server or ts#mcp-server generators (or others hosted on Bedrock AgentCore Runtime), a client factory is generated for you in agentcore_mcp_client.py.

You can update your get_agent method in agent.py to create MCP clients and add tools. The following example shows how to perform this with IAM (SigV4) authentication:

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Obtain the region an credentials
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()

@contextmanager
def get_agent(session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["MCP_AGENTCORE_RUNTIME_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )

    with mcp_client:
        mcp_tools = mcp_client.list_tools_sync()

        yield Agent(
            system_prompt="..."
            tools=[*mcp_tools],
        )

Tip

If your target MCP server uses JWT authentication, you can use the AgentCoreMCPClient.with_jwt_auth method to create the client instead.

With the IAM authentication example above, we need to configure two things in our infrastructure. Firstly, we need to add the environment variable our agent is consuming for our MCP server’s AgentCore Runtime ARN, and secondly we need to grant our agent permissions to invoke the MCP server. This can be achieved as follows:

CDK

import { MyProjectAgent, MyProjectMcpServer } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const mcpServer = new MyProjectMcpServer(this, 'MyProjectMcpServer');

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environment: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# MCP Server
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

# Agent
module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime"
      ]
      Resource = [
        module.my_project_mcp_server.agent_core_runtime_arn,
        "${module.my_project_mcp_server.agent_core_runtime_arn}/*"
      ]
    }
  ]
}

More

For a more in-depth guide to writing Strands agents, refer to the Strands documentation.

FastAPI Server

The generator uses FastAPI to create the HTTP server for your Strands Agent. FastAPI provides a modern, fast web framework for building APIs with Python, with automatic API documentation and type validation.

The generated server includes:

• FastAPI application setup with CORS middleware
• Error handling middleware
• OpenAPI schema generation
• Health check endpoint (/ping)
• Agent invocation endpoint (/invocations)

Customizing Invoke Inputs and Outputs with Pydantic

The agent’s invocation endpoint uses Pydantic models to define and validate the request and response schemas. You can customize these models in main.py to match your agent’s requirements.

Defining Input Models

The default InvokeInput model accepts a prompt and session ID.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str
    session_id: str

You can extend this model to include any additional fields your agent needs.

Caution

You will likely want to abstract some or all of the session ID from the caller if users are to invoke your agent directly. For example, you may use the authenticated user ID as part of the session ID.

It is also worth noting that depending on your use case you may need to implement authorization for sessions, for example ensuring that users may only access their own sessions and not those of other users.

Defining Output Models

For streaming responses, the return type annotation on your endpoint corresponds to the type of each value yielded by your generator function. By default, the agent yields strings containing the agent’s response text as it streams back from Strands:

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Entry point for agent invocation"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

You can define a Pydantic model to yield structured data instead:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(handle_invoke(input), media_type="application/json")

Bedrock AgentCore Python SDK

The generator includes a dependency on the Bedrock AgentCore Python SDK for the PingStatus constants. If desired, it is straightforward to use BedrockAgentCoreApp instead of FastAPI, however note that type-safety is lost.

You can find more details about the SDK’s capabilities in the documentation here.

Note

Since the generator vends CDK or Terraform infrastructure which manages deploying your agent, you do not need to utilise the bedrock-agentcore-starter-toolkit which the docs mention for deploying your agent.

Running Your Strands Agent

Local Development

The generator configures a target named <your-agent-name>-serve, which starts your Strands Agent locally for development and testing.

pnpm

pnpm nx run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

bunx nx run your-project:agent-serve

This command uses uv run to execute your Strands Agent using the Bedrock AgentCore Python SDK.

Deploying Your Strands Agent to Bedrock AgentCore Runtime

Infrastructure as Code

If you selected BedrockAgentCoreRuntime for computeType, the relevant CDK or Terraform infrastructure is generated which you can use to deploy your Strands Agent to Amazon Bedrock AgentCore Runtime.

CDK

A CDK construct is generated for your, named based on the name you chose when running the generator, or <ProjectName>Agent by default.

You can use this CDK construct in a CDK application:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

Terraform

A Terraform module is generated for you, named based on the name you chose when running the generator, or <ProjectName>-agent by default.

You can use this terraform module in a Terraform project:

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

Note

When deploying to Bedrock AgentCore Runtime, you’ll need to ensure that the appropriate foundation models are enabled in your AWS account. By default, Strands agents use Claude 4 Sonnet, but this can be customized as described above.

To enable model access in Amazon Bedrock, follow the instructions here.

Caution

Docker is required to build and deploy your Strands Agent. Make sure you have installed and launched Docker to avoid errors such as:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Bundle and Docker Targets

In order to build your Strands Agent for Bedrock AgentCore Runtime, a bundle target is added to your project, which:

• Exports your Python dependencies to a requirements.txt file using uv export
• Installs dependencies for the target platform (aarch64-manylinux2014) using uv pip install

A docker target specific to your Strands Agent is also added, which:

• Builds a docker image from the Dockerfile which runs your agent, as per the AgentCore runtime contract

Tip

The docker image is built using a tag (for example my-scope-my-project-agent:latest), which is referenced by your CDK or Terraform infrastructure, allowing for your Dockerfile to be co-located with your Strands Agent project.

Authentication

IAM

By default, your Strands Agent will be secured using IAM authentication, simply deploy it without any arguments:

CDK

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

You can grant access to invoke your agent on Bedrock AgentCore Runtime using the grantInvoke method, for example:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.agentCoreRuntime.grantInvoke(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

To grant access to invoke your agent, you will need to add a policy such as the following, referencing the module.my_project_agent.agent_core_runtime_arn output:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Cognito JWT Authentication

The below demonstrates how to configure Cognito authentication for your agent.

CDK

To configure JWT authentication, you can pass the authorizerConfiguration property to your agent construct. Here is an example which configures a Cognito user pool and client to secure the agent:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: {
        customJwtAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

To configure JWT authentication, you can edit your agent module to configure the customJWTAuthorizer variable as follows:

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Replace with your user pool and client ids or expose as variables
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

Observability

Your agent is automatically configured with observability using the AWS Distro for Open Telemetry (ADOT), by configuring auto-instrumentation in your Dockerfile.

You can find traces in the CloudWatch AWS Console, by selecting “GenAI Observability” in the menu. Note that for traces to be populated you will need to enable Transaction Search.

For more details, refer to the AgentCore documentation on observability.