Python Strands Agent

Tạo một Python Strands Agent để xây dựng các AI agent với các công cụ, và tùy chọn triển khai nó lên Amazon Bedrock AgentCore Runtime.

Strands là gì?

Strands là một framework Python nhẹ, sẵn sàng cho production để xây dựng các AI agent. Các tính năng chính bao gồm:

• Nhẹ và có thể tùy chỉnh: Vòng lặp agent đơn giản không cản trở bạn
• Sẵn sàng cho production: Khả năng quan sát đầy đủ, theo dõi và các tùy chọn triển khai cho quy mô lớn
• Không phụ thuộc vào model và provider: Hỗ trợ nhiều model khác nhau từ các provider khác nhau
• Công cụ được cộng đồng đóng góp: Bộ công cụ mạnh mẽ do cộng đồng đóng góp
• Hỗ trợ đa agent: Các kỹ thuật nâng cao như nhóm agent và agent tự động
• Chế độ tương tác linh hoạt: Hỗ trợ hội thoại, streaming và non-streaming

Cách sử dụng

Tạo một Strands Agent

Bạn có thể tạo một Python Strands Agent theo hai cách:

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - py#strands-agent
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Điều kiện tiên quyết dự án

Đầu tiên hãy sử dụng generator py#project để tạo một project để thêm Strands Agent của bạn vào.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm Strands Agent vào
computeType	string	BedrockAgentCoreRuntime	Loại compute để host Strands Agent của bạn.
name	string	-	Tên của Strands Agent của bạn (mặc định: agent)
auth	string	IAM	Phương thức được sử dụng để xác thực với Strands Agent của bạn. Chọn giữa IAM (mặc định) hoặc Cognito.
iacProvider	string	Inherit	Nhà cung cấp IaC ưa thích. Mặc định được kế thừa từ lựa chọn ban đầu của bạn.

Kết quả của Generator

Generator sẽ thêm các file sau vào Python project hiện có của bạn:

• Thư mụcyour-project/

  • Thư mụcyour_module/

    • Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)

      • __init__.py Khởi tạo Python package
      • init.py Thiết lập ứng dụng FastAPI với CORS và middleware xử lý lỗi
      • agent.py Định nghĩa agent chính với các công cụ mẫu
      • main.py Entry point cho Bedrock AgentCore Runtime
      • Dockerfile Entry point để host agent của bạn (bị loại trừ khi computeType được đặt thành None)
  • pyproject.toml Được cập nhật với các dependencies của Strands
  • project.json Được cập nhật với các target serve agent

Hạ tầng

Triển khai serverless

Nếu bạn chọn None cho computeType, generator sẽ không tạo bất kỳ infrastructure as code nào.

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK

• Thư mụcpackages/common/constructs

  • Thư mụcsrc

    • Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app

      • …
    • index.ts Entry point xuất các constructs từ app
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator ts#project và do đó cấu hình các build targets giống nhau.

Terraform

• Thư mụcpackages/common/terraform

  • Thư mụcsrc

    • Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator

      • …
    • Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app

      • …
  • project.json Các build targets và cấu hình của dự án

Dự án được tạo

Dự án này được tạo bằng generator terraform#project và do đó cấu hình các build targets giống nhau.

Để triển khai Strands Agent của bạn, các file sau được tạo:

CDK

• Thư mụcpackages/common/constructs/src

  • Thư mụcapp

    • Thư mụcagents

      • Thư mục<project-name>

        • <project-name>.ts CDK construct để triển khai agent của bạn
        • Dockerfile File docker passthrough được sử dụng bởi CDK construct

Terraform

• Thư mụcpackages/common/terraform/src

  • Thư mụcapp

    • Thư mụcagents

      • Thư mục<project-name>

        • <project-name>.tf Module để triển khai agent của bạn
  • Thư mụccore

    • Thư mụcagent-core

      • runtime.tf Module chung để triển khai lên Bedrock AgentCore Runtime

Làm việc với Strands Agent của bạn

Thêm công cụ

Các công cụ là các hàm mà AI agent có thể gọi để thực hiện các hành động. Framework Strands sử dụng phương pháp dựa trên decorator đơn giản để định nghĩa các công cụ.

Bạn có thể thêm các công cụ mới trong file agent.py:

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

Framework Strands tự động xử lý:

• Xác thực kiểu dựa trên type hints của hàm
• Tạo JSON schema cho tool calling
• Xử lý lỗi và định dạng response

Sử dụng các công cụ có sẵn

Strands cung cấp một bộ sưu tập các công cụ có sẵn thông qua package strands-tools:

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

Cấu hình Model

Mặc định, các Strands agent sử dụng Claude 4 Sonnet, nhưng bạn có thể tùy chỉnh model provider. Xem tài liệu Strands về model providers để biết các tùy chọn cấu hình:

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)

Sử dụng MCP Servers

Bạn có thể thêm các công cụ từ MCP servers vào Strands agent của bạn.

Để sử dụng các MCP Server mà bạn đã tạo bằng generator py#mcp-server hoặc ts#mcp-server, bạn có thể sử dụng connection generator.

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp 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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Đối với các MCP server khác, vui lòng tham khảo Tài liệu Strands.

Thêm nữa

Để có hướng dẫn chuyên sâu hơn về viết Strands agent, hãy tham khảo tài liệu Strands.

FastAPI Server

Generator sử dụng FastAPI để tạo HTTP server cho Strands Agent của bạn. FastAPI cung cấp một web framework hiện đại, nhanh để xây dựng API với Python, với tài liệu API tự động và xác thực kiểu.

Server được tạo bao gồm:

• Thiết lập ứng dụng FastAPI với CORS middleware
• Middleware xử lý lỗi
• Tạo OpenAPI schema
• Health check endpoint (/ping)
• Agent invocation endpoint (/invocations)

Tùy chỉnh Invoke Inputs và Outputs với Pydantic

Invocation endpoint của agent sử dụng các model Pydantic để định nghĩa và xác thực các schema request và response. Bạn có thể tùy chỉnh các model này trong main.py để phù hợp với yêu cầu của agent.

Định nghĩa Input Models

Model InvokeInput mặc định chấp nhận một prompt và session ID.

from pydantic import BaseModel

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

Bạn có thể mở rộng model này để bao gồm bất kỳ trường bổ sung nào mà agent của bạn cần.

Tổ chức mã nguồn

Bạn có thể muốn trừu tượng hóa một phần hoặc toàn bộ session ID khỏi caller nếu người dùng gọi agent của bạn trực tiếp. Ví dụ, bạn có thể sử dụng ID người dùng đã xác thực như một phần của session ID.

Cũng đáng lưu ý rằng tùy thuộc vào use case của bạn, bạn có thể cần triển khai authorization cho các session, ví dụ đảm bảo rằng người dùng chỉ có thể truy cập các session của riêng họ chứ không phải của người dùng khác.

Định nghĩa Output Models

Đối với streaming responses, generator cung cấp JsonStreamingResponse tự động serialize các Pydantic model sang định dạng JSON Lines (application/jsonl). Định dạng này tương thích với đặc tả streaming của OpenAPI 3.2 và hoạt động liền mạch với TypeScript client được tạo.

Mặc định, agent yield các đối tượng StreamChunk chứa văn bản response của agent:

class StreamChunk(BaseModel):
    content: str

Bạn có thể tùy chỉnh model StreamChunk để phù hợp với nhu cầu của bạn:

from pydantic import BaseModel

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

Hạn chế streaming FastAPI

Lưu ý rằng vì FastAPI hiện không hỗ trợ tạo đặc tả OpenAPI cho streaming responses, chúng ta phải thiết lập rõ ràng response model cho mỗi streaming operation, ví dụ:

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

Có một yêu cầu tính năng mở cho hỗ trợ native trong FastAPI.

Bedrock AgentCore Python SDK

Generator bao gồm một dependency trên Bedrock AgentCore Python SDK cho các hằng số PingStatus. Nếu muốn, việc sử dụng BedrockAgentCoreApp thay vì FastAPI là khá đơn giản, tuy nhiên lưu ý rằng type-safety sẽ bị mất.

Bạn có thể tìm thêm chi tiết về khả năng của SDK trong tài liệu tại đây.

Cơ sở hạ tầng dưới dạng mã

Vì generator tạo ra hạ tầng CDK hoặc Terraform để quản lý việc triển khai agent của bạn, bạn không cần sử dụng bedrock-agentcore-starter-toolkit mà tài liệu đề cập để triển khai agent của bạn.

Chạy Strands Agent của bạn

Phát triển Local

Generator cấu hình một target có tên <your-agent-name>-serve, khởi động Strands Agent của bạn locally để phát triển và kiểm thử.

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

Lệnh này sử dụng uv run để thực thi Strands Agent của bạn bằng Bedrock AgentCore Python SDK.

Triển khai Strands Agent của bạn lên Bedrock AgentCore Runtime

Infrastructure as Code

Nếu bạn đã chọn BedrockAgentCoreRuntime cho computeType, cơ sở hạ tầng CDK hoặc Terraform liên quan sẽ được tạo ra mà bạn có thể sử dụng để triển khai Strands Agent của mình lên Amazon Bedrock AgentCore Runtime.

CDK

Một CDK construct được tạo ra cho agent của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>Agent.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

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.addToRolePolicy(
      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/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

CDK Construct Alpha

Construct này sử dụng module @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Một module Terraform được tạo ra cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>-agent.

Bạn có thể sử dụng module terraform này trong một dự án 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"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Yêu cầu Docker

Docker là bắt buộc để xây dựng và triển khai Strands Agent của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

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

Xác thực

Trình tạo cung cấp tùy chọn auth để cấu hình xác thực cho Strands Agent của bạn. Bạn có thể chọn giữa xác thực IAM (mặc định) hoặc Cognito khi tạo agent của mình.

IAM

Theo mặc định, Strands Agent của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần bất kỳ tham số nào:

CDK

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

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

Bạn có thể cấp quyền truy cập để gọi agent của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvokeAccess, ví dụ:

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

Để cấp quyền truy cập gọi agent của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output module.my_project_agent.agent_core_runtime_arn:

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

Xác thực Cognito

Khi bạn chọn xác thực Cognito, trình tạo sẽ cấu hình agent để sử dụng Cognito cho xác thực.

CDK

Construct được tạo ra chấp nhận một prop identity để cấu hình xác thực Cognito:

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

Construct UserIdentity có thể được tạo bằng trình tạo ts#react-website#auth, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

Terraform

Module được tạo ra chấp nhận các biến user_pool_id và user_pool_client_ids cho xác thực Cognito:

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

Nhà cung cấp OIDC tùy chỉnh

Nếu bạn yêu cầu xác thực JWT tùy chỉnh với nhà cung cấp OIDC không phải Cognito, bạn có thể chỉnh sửa trực tiếp CDK construct hoặc module Terraform được tạo cho agent của mình. Lưu ý rằng trình tạo kết nối sẽ chỉ hỗ trợ xác thực IAM hoặc Cognito.

Bundle và Docker Targets

Để build Strands Agent của bạn cho Bedrock AgentCore Runtime, một target bundle được thêm vào project của bạn, thực hiện:

• Export các Python dependencies của bạn vào file requirements.txt bằng uv export
• Cài đặt dependencies cho nền tảng đích (aarch64-manylinux2014) bằng uv pip install

Một target docker cụ thể cho Strands Agent của bạn cũng được thêm vào, thực hiện:

• Build một docker image từ Dockerfile chạy agent của bạn, theo hợp đồng runtime AgentCore

Tag ảnh Docker

Docker image được build bằng một tag (ví dụ my-scope-my-project-agent:latest), được tham chiếu bởi hạ tầng CDK hoặc Terraform của bạn, cho phép Dockerfile của bạn được đặt cùng với Strands Agent project của bạn.

Khả năng quan sát

Agent của bạn được tự động cấu hình với khả năng quan sát bằng cách sử dụng AWS Distro for Open Telemetry (ADOT), bằng cách cấu hình auto-instrumentation trong Dockerfile của bạn.

Bạn có thể tìm thấy các trace trong AWS Console CloudWatch, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các trace được điền, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, hãy tham khảo tài liệu AgentCore về observability.

Gọi Strands Agent của bạn

Gọi Local Server

Để gọi một Agent đang chạy locally thông qua target <your-agent-name>-serve, bạn có thể gửi một POST request đơn giản tới /invocations trên port mà local agent của bạn đang chạy. Ví dụ, với curl:

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

Cờ streaming Curl

Tham số -N được cung cấp cho curl vô hiệu hóa việc buffer output stream, để bạn có thể xem streaming response theo thời gian thực.

Gọi Agent đã triển khai

Để gọi Agent của bạn đã triển khai lên Bedrock AgentCore Runtime, bạn có thể gửi một yêu cầu POST đến điểm cuối dataplane của Bedrock AgentCore Runtime với ARN runtime đã được mã hóa URL.

Bạn có thể lấy ARN runtime từ cơ sở hạ tầng của mình như sau:

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
}

ARN sẽ có định dạng như sau: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Sau đó, bạn có thể mã hóa URL cho ARN bằng cách thay thế : bằng %3A và / bằng %2F.

Console trình duyệt

Điều này rất đơn giản trong console trình duyệt hoặc Node REPL bằng cách sử dụng phương thức encodeURIComponent có sẵn:

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

URL dataplane của Bedrock AgentCore Runtime để gọi agent như sau:

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

Cách chính xác để gọi URL này phụ thuộc vào phương thức xác thực được sử dụng.

Xác thực IAM

Đối với Xác thực IAM, request phải được ký bằng AWS Signature Version 4 (SigV4).

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

Click here for more details on configuring the above acurl command

Xác thực JWT / Cognito

Đối với Xác thực Cognito, truyền Cognito Access Token trong header Authorization:

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

Bạn có thể lấy access token bằng lệnh cognito-idp admin-initiate-auth của AWS CLI, ví dụ:

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