Agente de Strands em Python
Gere um Agente Strands em Python para construir agentes de IA com ferramentas, e opcionalmente implante-o no Amazon Bedrock AgentCore Runtime.
O que é o Strands?
Seção intitulada “O que é o Strands?”Strands é um framework Python leve e pronto para produção para construção de agentes de IA. Principais recursos incluem:
- Leve e personalizável: Loop de agente simples que não atrapalha
- Pronto para produção: Observabilidade completa, tracing e opções de implantação para escala
- Agnóstico de modelo e provedor: Suporte a diversos modelos de vários provedores
- Ferramentas comunitárias: Conjunto poderoso de ferramentas contribuídas pela comunidade
- Suporte a multiagentes: Técnicas avançadas como equipes de agentes e agentes autônomos
- Modos de interação flexíveis: Suporte a conversacional, streaming e não-streaming
Gerar um Agente Strands
Seção intitulada “Gerar um Agente Strands”Você pode gerar um Agente Strands em Python de duas formas:
- Instale o Nx Console VSCode Plugin se ainda não o fez
- Abra o console Nx no VSCode
- Clique em
Generate (UI)
na seção "Common Nx Commands" - Procure por
@aws/nx-plugin - py#strands-agent
- Preencha os parâmetros obrigatórios
- Clique em
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
Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados
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
Parâmetro | Tipo | Padrão | Descrição |
---|---|---|---|
project Obrigatório | 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. |
Saída do Gerador
Seção intitulada “Saída do Gerador”O gerador adicionará os seguintes arquivos ao seu projeto Python existente:
Directoryyour-project/
Directoryyour_module/
Directoryagent/ (ou nome personalizado se especificado)
- __init__.py Inicialização do pacote Python
- agent.py Definição principal do agente com ferramentas de exemplo
- main.py Ponto de entrada para Bedrock AgentCore Runtime
- agentcore_mcp_client.py Fábrica de clientes útil para invocar servidores MCP também hospedados no Bedrock AgentCore Runtime
- Dockerfile Ponto de entrada para hospedar seu agente (excluído quando
computeType
éNone
)
- pyproject.toml Atualizado com dependências do Strands
- project.json Atualizado com alvos de serviço do agente
Infraestrutura
Seção intitulada “Infraestrutura”Como este gerador fornece infraestrutura como código com base no iacProvider
escolhido, ele criará um projeto em packages/common
que inclui os constructs CDK ou módulos Terraform relevantes.
O projeto comum de infraestrutura como código está estruturado da seguinte forma:
Directorypackages/common/constructs
Directorysrc
Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador
- …
Directorycore/ Constructs genéricos reutilizados pelos constructs em
app
- …
- index.ts Ponto de entrada exportando os constructs de
app
- project.json Metas de build e configuração do projeto
Directorypackages/common/terraform
Directorysrc
Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador
- …
Directorycore/ Módulos genéricos reutilizados pelos módulos em
app
- …
- project.json Metas de build e configuração do projeto
Para implantar seu Agente Strands, os seguintes arquivos são gerados:
Directorypackages/common/constructs/src
Directoryapp
Directoryagents
Directory<project-name>
- <project-name>.ts Construct CDK para implantar seu agente
- Dockerfile Arquivo Docker repassado usado pelo construct CDK
Directorycore
Directoryagent-core
- runtime.ts Construct CDK genérico para implantação no Bedrock AgentCore Runtime
Directorypackages/common/terraform/src
Directoryapp
Directoryagents
Directory<project-name>
- <project-name>.tf Módulo para implantar seu agente
Directorycore
Directoryagent-core
- runtime.tf Módulo genérico para implantação no Bedrock AgentCore Runtime
Trabalhando com Seu Agente Strands
Seção intitulada “Trabalhando com Seu Agente Strands”Adicionando Ferramentas
Seção intitulada “Adicionando Ferramentas”Ferramentas são funções que o agente de IA pode chamar para executar ações. O framework Strands usa uma abordagem simples baseada em decoradores para definir ferramentas.
Você pode adicionar novas ferramentas no arquivo agent.py
:
from strands import Agent, tool
@tooldef calculate_sum(numbers: list[int]) -> int: """Calculate the sum of a list of numbers""" return sum(numbers)
@tooldef 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 agentagent = Agent( system_prompt="You are a helpful assistant with access to various tools.", tools=[calculate_sum, get_weather],)
O framework Strands trata automaticamente:
- Validação de tipos baseada nas dicas de tipo da função
- Geração de schema JSON para chamadas de ferramentas
- Tratamento de erros e formatação de respostas
Usando Ferramentas Pré-construídas
Seção intitulada “Usando Ferramentas Pré-construídas”Strands fornece uma coleção de ferramentas pré-construídas através do pacote 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],)
Configuração de Modelo
Seção intitulada “Configuração de Modelo”Por padrão, agentes Strands usam Claude 4 Sonnet, mas você pode personalizar o provedor de modelo. Consulte a documentação do Strands sobre provedores de modelos para opções de configuração:
from strands import Agentfrom strands.models import BedrockModel
# Create a BedrockModelbedrock_model = BedrockModel( model_id="anthropic.claude-sonnet-4-20250514-v1:0", region_name="us-west-2", temperature=0.3,)
agent = Agent(model=bedrock_model)
Consumindo Servidores MCP
Seção intitulada “Consumindo Servidores MCP”Você pode adicionar ferramentas de servidores MCP ao seu agente Strands.
Para consumir servidores MCP criados usando os geradores py#mcp-server
ou ts#mcp-server
(ou outros hospedados no Bedrock AgentCore Runtime), uma fábrica de clientes é gerada para você em agentcore_mcp_client.py
.
Você pode atualizar seu método get_agent
em agent.py
para criar clientes MCP e adicionar ferramentas. O exemplo abaixo mostra como fazer isso com autenticação IAM (SigV4):
import osfrom contextlib import contextmanager
import boto3from strands import Agent
from .agentcore_mcp_client import AgentCoreMCPClient
# Obtain the region an credentialsregion = os.environ["AWS_REGION"]boto_session = boto3.Session(region_name=region)credentials = boto_session.get_credentials()
@contextmanagerdef 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], )
Com o exemplo de autenticação IAM acima, precisamos configurar duas coisas em nossa infraestrutura. Primeiro, adicionar a variável de ambiente que nosso agente consome para a ARN do AgentCore Runtime do servidor MCP, e segundo, conceder permissões ao nosso agente para invocar o servidor MCP. Isso pode ser feito da seguinte forma:
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 Servermodule "my_project_mcp_server" { source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"}
# Agentmodule "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}/*" ] } ]}
Para um guia mais detalhado sobre escrita de agentes Strands, consulte a documentação do Strands.
Bedrock AgentCore Python SDK
Seção intitulada “Bedrock AgentCore Python SDK”O gerador configura o Bedrock AgentCore Python SDK para gerenciar o contrato HTTP subjacente que agentes no AgentCore devem implementar.
Você pode encontrar mais detalhes sobre as capacidades do SDK na documentação aqui.
Executando Seu Agente Strands
Seção intitulada “Executando Seu Agente Strands”Desenvolvimento Local
Seção intitulada “Desenvolvimento Local”O gerador configura um alvo chamado <your-agent-name>-serve
, que inicia seu Agente Strands localmente para desenvolvimento e testes.
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
Este comando usa uv run
para executar seu Agente Strands usando o Bedrock AgentCore Python SDK.
Implantando Seu Agente Strands no Bedrock AgentCore Runtime
Seção intitulada “Implantando Seu Agente Strands no Bedrock AgentCore Runtime”Infraestrutura como Código
Seção intitulada “Infraestrutura como Código”Se selecionou BedrockAgentCoreRuntime
para computeType
, a infraestrutura CDK ou Terraform relevante é gerada para você implantar seu Agente Strands no Amazon Bedrock AgentCore Runtime.
Um construct CDK é gerado para você, nomeado com base no name
escolhido ao executar o gerador, ou <ProjectName>Agent
por padrão.
Você pode usar este construct CDK em uma aplicação CDK:
import { MyProjectAgent } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { // Adicione o agente à sua stack const agent = new MyProjectAgent(this, 'MyProjectAgent');
// Conceda permissões para invocar os modelos relevantes no bedrock agent.agentCoreRuntime.role.addToPolicy( new PolicyStatement({ actions: [ 'bedrock:InvokeModel', 'bedrock:InvokeModelWithResponseStream', ], // Você pode restringir abaixo aos modelos específicos que usa resources: ['arn:aws:bedrock:*::foundation-model/*'], }), ); }}
Um módulo Terraform é gerado para você, nomeado com base no name
escolhido ao executar o gerador, ou <ProjectName>-agent
por padrão.
Você pode usar este módulo Terraform em um projeto Terraform:
# Agentmodule "my_project_agent" { # Caminho relativo para o módulo gerado no projeto common/terraform source = "../../common/terraform/src/app/agents/my-project-agent"
# Conceda permissões para invocar os modelos relevantes no bedrock additional_iam_policy_statements = [ { Effect = "Allow" Action = [ "bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream" ] Resource = [ "arn:aws:bedrock:*::foundation-model/*" ] } ]}
Alvos Bundle e Docker
Seção intitulada “Alvos Bundle e Docker”Para construir seu Agente Strands para o Bedrock AgentCore Runtime, um alvo bundle
é adicionado ao seu projeto, que:
- Exporta suas dependências Python para um arquivo
requirements.txt
usandouv export
- Instala dependências para a plataforma alvo (
aarch64-manylinux2014
) usandouv pip install
Um alvo docker
específico para seu Agente Strands também é adicionado, que:
- Constrói uma imagem Docker a partir do
Dockerfile
que executa seu agente, conforme o contrato de runtime do AgentCore
Autenticação
Seção intitulada “Autenticação”Por padrão, seu Agente Strands será protegido usando autenticação IAM. Basta implantá-lo sem argumentos:
import { MyProjectAgent } from ':my-scope/common-constructs';
export class ExampleStack extends Stack { constructor(scope: Construct, id: string) { new MyProjectAgent(this, 'MyProjectAgent'); }}
Você pode conceder acesso para invocar seu agente no Bedrock AgentCore Runtime usando o método grantInvoke
, por exemplo:
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); }}
# Agentmodule "my_project_agent" { # Caminho relativo para o módulo gerado no projeto common/terraform source = "../../common/terraform/src/app/agents/my-project-agent"}
Para conceder acesso para invocar seu agente, você precisará adicionar uma política como a seguinte, referenciando a saída 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}/*" ]}
Autenticação Cognito JWT
Seção intitulada “Autenticação Cognito JWT”O exemplo abaixo demonstra como configurar autenticação Cognito para seu agente.
Para configurar autenticação JWT, você pode passar a propriedade authorizerConfiguration
para seu construct de agente. Aqui está um exemplo que configura um user pool e client Cognito para proteger o agente:
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], }, }, }); }}
Para configurar autenticação JWT, você pode editar seu módulo de agente para configurar a variável customJWTAuthorizer
da seguinte forma:
data "aws_region" "current" {}
locals { aws_region = data.aws_region.current.name
# Substitua pelos IDs do seu user pool e client ou exponha como variáveis 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}
Observabilidade
Seção intitulada “Observabilidade”Seu agente é configurado automaticamente com observabilidade usando o AWS Distro for Open Telemetry (ADOT), através da configuração de auto-instrumentação em seu Dockerfile
.
Você pode encontrar traces no Console AWS CloudWatch, selecionando “GenAI Observability” no menu. Note que para os traces serem populados, você precisará habilitar o Transaction Search.
Para mais detalhes, consulte a documentação do AgentCore sobre observabilidade.