Python Strands Agent

Generate a Python Strands Agent for building AI agents with tools, and optionally deploy it to Amazon Bedrock AgentCore Runtime. By default, the generator uses FastAPI to expose an HTTP server. Alternatively, you can choose the Agent-to-Agent (A2A) protocol for interoperability with other A2A-compatible agents, or the AG-UI protocol for direct frontend integration via CopilotKit.

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

Project Prerequisite

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)
auth	string	IAM	The method used to authenticate with your Strands Agent. Choose between IAM (default) or Cognito.
protocol	string	HTTP	The server protocol for your Strands Agent. HTTP exposes a FastAPI HTTP server. A2A exposes an Agent-to-Agent protocol server. AG-UI exposes an Agent-User Interaction protocol server for direct frontend integration.
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. The files generated depend on the chosen protocol:

HTTP Protocol (default)

• Directoryyour-project/

  • Directoryyour_module/

    • Directoryagent/ (or custom name if specified)

      • __init__.py Python package initialization
      • init.py FastAPI application setup with CORS and error handling middleware
      • agent.py Main agent definition with sample tools
      • main.py FastAPI entry point for 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

A2A Protocol

When protocol is set to A2A, the entry point uses the Strands A2A Server instead of FastAPI:

• 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 A2A server entry point
      • 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

AG-UI Protocol

When protocol is set to AG-UI, the entry point uses the ag-ui-strands integration, which exposes your agent via the AG-UI protocol for direct frontend integration with CopilotKit:

• 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 AG-UI server entry point using ag-ui-strands
      • Dockerfile Entry point for hosting your agent (excluded when computeType is set to None)
  • pyproject.toml Updated with Strands and AG-UI dependencies
  • project.json Updated with agent serve targets

Connect to a React website

AG-UI agents can be connected to a React frontend using the connection generator, which will set up CopilotKit components for a rich chat experience.

Infrastructure

Serverless Deployment

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

Generated Project

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

Generated Project

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

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 you can make use of the connection generator.

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 - connection
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Refer to the connection generator guide for details about how the connection is set up.

For other MCP servers, please refer to the Strands Documentation.

More

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

Protocol

Your agent’s server protocol determines how it communicates. All options are served by FastAPI — the entry point differs:

• HTTP (default): A standard FastAPI server with a custom /invocations endpoint, CORS, and streaming. Best for custom client integrations.
• A2A: The Strands A2A Server mounted onto a FastAPI app. Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
• AG-UI: The ag-ui-strands integration, which exposes the AG-UI protocol over SSE. Best for direct frontend integration with CopilotKit in a React website.

All protocols expose /ping for the AgentCore runtime health check contract. A2A agents listen on port 9000; HTTP and AG-UI agents listen on port 8080. The generated Dockerfile and infrastructure are configured for you.

FastAPI Server (HTTP protocol)

The generated HTTP 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 message.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

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

The session ID is extracted from the x-amzn-bedrock-agentcore-runtime-session-id HTTP header, consistent with the Bedrock AgentCore Runtime session contract. If the header is not provided, a random UUID is generated as a fallback.

Code Organization

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 generator provides JsonStreamingResponse which automatically serializes Pydantic models to JSON Lines format (application/jsonl). This format is compatible with OpenAPI 3.2’s streaming specification and works seamlessly with the generated TypeScript client.

By default, the agent yields StreamChunk objects containing the agent’s response text:

class StreamChunk(BaseModel):
    content: str

You can customise the StreamChunk model to suit your needs:

from pydantic import BaseModel

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

FastAPI Streaming Limitation

Note that since FastAPI does not currently support generating an OpenAPI specification for streaming responses, we must explicitly set the response model for each streaming operation, ie:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

There is an open feature request for native support in FastAPI.

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.

Infrastructure as Code

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.

A2A Server (A2A protocol)

When protocol=A2A, the generated main.py mounts A2AServer.to_fastapi_app() onto a parent FastAPI app that also exposes /ping. When deployed to AgentCore, the entry point resolves the runtime’s public ARN from AppConfig and advertises it in the agent card.

Most users will not need to modify this file — edit agent.py to change tools or the system prompt. The A2A server populates the agent card (/.well-known/agent-card.json) from the Agent constructor’s name and description.

AG-UI Server (AG-UI protocol)

When protocol=AG-UI, the generated main.py wraps your Strands Agent in an ag_ui_strands.StrandsAgent and creates a FastAPI app via create_strands_app(). The resulting app exposes a single POST endpoint that streams AG-UI events over Server-Sent Events (SSE), as well as /ping for the AgentCore runtime health check.

Most users will not need to modify this file — edit agent.py to change tools or the system prompt.

Connecting to a React website

AG-UI agents are designed to be consumed directly by a frontend. Use the connection generator to wire your React website up to the agent with a CopilotKit provider and AG-UI HttpAgent client.

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 agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

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 agent, 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) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Alpha CDK Construct

This construct uses the @aws-cdk/aws-bedrock-agentcore-alpha module.

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"
}

Bedrock Model Permissions

The generated agent construct grants permission to invoke all Bedrock foundation models and inference profiles by default (bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream on arn:aws:bedrock:*:*:foundation-model/* and arn:aws:bedrock:*:*:inference-profile/*).

You may wish to scope this down to the specific model(s) your agent uses. You can find the default model used by Strands agents in the Strands documentation; see the Strands model providers guide for configuring a different model.

Docker Required

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.

Authentication

The generator provides an auth option to configure authentication for your Strands Agent. You can choose between IAM (default) or Cognito authentication when generating your agent.

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 grantInvokeAccess 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.grantInvokeAccess(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 Authentication

When you select Cognito authentication, the generator configures the agent to use Cognito for authentication.

CDK

The generated construct accepts an identity prop which configures Cognito authentication:

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

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

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

The UserIdentity construct can be generated using the ts#react-website#auth generator, or you can create your own CDK UserPool and UserPoolClient.

Terraform

The generated module accepts user_pool_id and user_pool_client_ids variables for Cognito authentication:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Custom OIDC Providers

If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your agent directly. Note that the connection generator will only support IAM or Cognito authentication.

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-manylinux_2_28) using uv pip install

A docker target specific to your Strands Agent is also added, which copies the Dockerfile and bundled artifacts into a docker context directory. This co-locates the Dockerfile with the built output, allowing CDK to build the Docker image directly using AgentRuntimeArtifact.fromAsset.

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.

Invoking your Strands Agent

Invoke the Local Server

To invoke an Agent running locally via the <your-agent-name>-serve target, you can send a simple POST request to /invocations on the port your local agent is running on. For example, with curl:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Curl Streaming Flag

The -N argument given to curl disables buffering the output stream, so you can see the streaming response in real-time.

Invoke the Deployed Agent

To invoke your Agent deployed to Bedrock AgentCore Runtime, you can send a POST request to the Bedrock AgentCore Runtime dataplane endpoint with your URL-encoded runtime ARN.

You can obtain the runtime ARN from your infrastructure as follows:

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

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

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

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"
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

The ARN will have the following format: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

You can then URL-encode the ARN by replacing : with %3A and / with %2F.

Browser Console

This is straightforward in a browser console or Node REPL using the built in encodeURIComponent method:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

The exact way to invoke this URL depends upon the authentication method used.

IAM Authentication

For IAM Authentication, the request must be signed using AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"message": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Click here for more details on configuring the above acurl command

JWT / Cognito Authentication

For Cognito Authentication, pass the Cognito Access Token in the Authorization header:

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

You can obtain the access token using the AWS CLI’s cognito-idp admin-initiate-auth command, for example:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Browser / React Website

For invoking your Strands Agent from a React website, you can make use of the connection generator, which automatically sets up a client with the correct authentication (IAM or Cognito).

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 - connection
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Refer to the connection generator guide for details about how the connection is set up.

Invoking an A2A Agent as a Tool

To delegate work from this agent to a remote A2A agent (either TypeScript or Python), use the connection generator. It vends a SigV4-authenticated client for the target agent and AST-transforms this agent’s agent.py to register the remote A2A agent as a @tool-decorated delegate.

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 - connection
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Refer to the connection generator guide for details about how the connection is set up.