Python Strands 代理

生成一个用于构建AI智能体工具的Python Strands Agent，并可选部署到Amazon Bedrock AgentCore Runtime。

什么是Strands？

Strands是一个轻量级、生产就绪的Python框架，用于构建AI智能体。主要特性包括：

轻量且可定制：简洁的智能体循环设计，不干扰开发
生产就绪：完整的可观测性、追踪和规模化部署选项
模型与供应商无关：支持多种不同供应商的模型
社区驱动工具：强大的社区贡献工具集
多智能体支持：支持智能体团队和自主智能体等高级技术
灵活交互模式：支持对话式、流式和非流式交互

使用方式

生成Strands智能体

可通过两种方式生成Python Strands智能体：

VSCode
CLI

安装 Nx Console VSCode Plugin 如果您尚未安装
在VSCode中打开Nx控制台
点击 Generate (UI) 在"Common Nx Commands"部分
搜索 @aws/nx-plugin - py#strands-agent
填写必需参数
点击 Generate

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

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

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

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

您还可以执行试运行以查看哪些文件会被更改

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

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

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

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

选项配置

参数	类型	默认值	描述
project 必需	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.

生成器输出

生成器将在现有Python项目中添加以下文件：

文件夹your-project/
- 文件夹your_module/
  - 文件夹agent/ (可自定义名称)
    __init__.py Python包初始化文件
    agent.py 主智能体定义（含示例工具）
    main.py Bedrock AgentCore Runtime入口点
    agentcore_mcp_client.py 用于调用MCP服务的客户端工厂
    Dockerfile 智能体托管入口文件（当computeType设为None时不生成）
- pyproject.toml 更新Strands依赖
- project.json 更新服务目标配置

基础设施

由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

通用的基础设施即代码项目结构如下：

CDK
Terraform

文件夹packages/common/constructs
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的基础设施构造体
    …
  - 文件夹core/ 被 app 目录构造体重用的通用构造体
    …
  - index.ts 导出 app 目录构造体的入口文件
- project.json 项目构建目标与配置

文件夹packages/common/terraform
- 文件夹src
  - 文件夹app/ 针对特定项目/生成器的 Terraform 模块
    …
  - 文件夹core/ 被 app 目录模块重用的通用模块
    …
- project.json 项目构建目标与配置

部署Strands智能体时生成以下文件：

CDK
Terraform

文件夹packages/common/constructs/src
- 文件夹app
  - 文件夹agents
    文件夹<project-name>
    <project-name>.ts 部署智能体的CDK构造
    Dockerfile CDK构造使用的透传Docker文件
- 文件夹core
  - 文件夹agent-core
    runtime.ts 部署到Bedrock AgentCore Runtime的通用CDK构造

使用Strands智能体

添加工具

工具是AI智能体可调用的功能函数。Strands框架使用基于装饰器的简单方式定义工具。

在agent.py文件中添加新工具：

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """计算数字列表的总和"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """获取城市天气信息"""
    # 此处集成天气API
    return f"{city}天气：晴，25°C"

# 将工具添加到智能体
agent = Agent(
    system_prompt="您是一个拥有多种工具的智能助手。",
    tools=[calculate_sum, get_weather],
)

Strands框架自动处理：

基于函数类型提示的类型验证
工具调用的JSON模式生成
错误处理和响应格式化

使用预置工具

通过strands-tools包使用预置工具：

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="您是一个智能助手。",
    tools=[current_time, http_request, file_read],
)

模型配置

默认使用Claude 4 Sonnet模型，可自定义模型供应商。参考Strands模型供应商文档进行配置：

from strands import Agent
from strands.models import BedrockModel

# 创建Bedrock模型实例
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)

使用MCP服务

可通过添加MCP服务工具扩展智能体功能。

对于使用py#mcp-server或ts#mcp-server生成器创建的MCP服务（或部署在Bedrock AgentCore Runtime的其他服务），生成器会在agentcore_mcp_client.py中创建客户端工厂。

在agent.py中更新get_agent方法以创建MCP客户端并添加工具。以下示例展示使用IAM（SigV4）认证：

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# 获取区域和凭证
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],
        )

上述IAM认证示例需在基础设施中配置两点：添加MCP服务AgentCore Runtime ARN环境变量，并授予智能体调用权限：

CDK
Terraform

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);
  }
}

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

# 智能体
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}/*"
      ]
    }
  ]
}

Bedrock AgentCore Python SDK

生成器配置了Bedrock AgentCore Python SDK来管理AgentCore智能体所需的HTTP协议实现。

SDK功能详情请参阅文档。

运行Strands智能体

本地开发

生成器配置了名为<your-agent-name>-serve的目标，用于本地开发和测试：

pnpm nx run your-project:agent-serve

yarn nx run your-project:agent-serve

npx nx run your-project:agent-serve

bunx nx run your-project:agent-serve

该命令使用uv run通过Bedrock AgentCore Python SDK运行智能体。

部署到Bedrock AgentCore Runtime

基础设施即代码

若选择BedrockAgentCoreRuntime作为computeType，将生成相关CDK或Terraform基础设施用于部署到Amazon Bedrock AgentCore Runtime。

CDK
Terraform

默认生成基于生成器name参数的CDK构造（默认<ProjectName>Agent）：

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

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

    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

默认生成基于生成器name参数的Terraform模块（默认<ProjectName>-agent）：

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

  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

打包与Docker目标

为构建Bedrock AgentCore Runtime部署包，项目中添加了bundle目标：

使用uv export导出Python依赖到requirements.txt
使用uv pip install为目标平台（aarch64-manylinux2014）安装依赖

同时添加智能体专用的docker目标：

根据AgentCore运行时协议构建Docker镜像

认证配置

IAM认证

默认使用IAM认证，直接部署即可：

CDK
Terraform

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

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

// 授权调用示例
agent.agentCoreRuntime.grantInvoke(lambdaFunction);

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

# 授权策略示例
{
  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认证

以下演示如何配置Cognito认证：

CDK
Terraform

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],
        },
      },
    });
  }
}

locals {
  aws_region = data.aws_region.current.name
  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
  }
  # 其他配置...
}

可观测性

通过Dockerfile中的自动配置，使用AWS分布式OpenTelemetry（ADOT）实现可观测性。

在CloudWatch控制台选择”GenAI Observability”查看追踪数据，需启用事务搜索。

详细配置参考AgentCore可观测性文档。