Agente de Strands em Python

Gere um Strands Agent em Python para construir agentes de IA com ferramentas, e opcionalmente implante-o no Amazon Bedrock AgentCore Runtime.

O que é o Strands?

Strands é um framework Python leve e pronto para produção para construção de agentes de IA. Principais características:

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 em escala
Agnóstico a modelos e provedores: 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 flexíveis de interação: Suporte a conversacional, streaming e não-streaming

Uso

Gerar um Strands Agent

Você pode gerar um Strands Agent em Python de duas formas:

VSCode
CLI

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

Primeiro use o gerador py#project para criar um projeto onde adicionar seu Strands Agent.

Opções

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	CDK	The preferred IaC provider

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 selecionou None para computeType, o gerador não fornecerá nenhuma infraestrutura como código.

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:

CDK
Terraform

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 Strands Agent, os seguintes arquivos são gerados:

CDK
Terraform

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

Trabalhando com Seu Strands Agent

Adicionando Ferramentas

Ferramentas são funções que o agente de IA pode chamar para realizar 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

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

O framework Strands trata automaticamente:

Validação de tipos baseada nas dicas de tipo das funções
Geração de esquema JSON para chamadas de ferramentas
Tratamento de erros e formatação de respostas

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

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

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

Se seu servidor MCP alvo usa autenticação JWT, você pode usar o método AgentCoreMCPClient.with_jwt_auth para criar o cliente.

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:

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 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}/*"
      ]
    }
  ]
}

Mais

Para um guia mais detalhado sobre escrita de agentes Strands, consulte a documentação do Strands.

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.

Como o gerador fornece infraestrutura CDK ou Terraform que gerencia a implantação do seu agente, você não precisa utilizar o bedrock-agentcore-starter-toolkit mencionado na documentação para implantar seu agente.

Executando Seu Strands Agent

Desenvolvimento Local

O gerador configura um alvo chamado <your-agent-name>-serve, que inicia seu Strands Agent 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 Strands Agent usando o Bedrock AgentCore Python SDK.

Implantando Seu Strands Agent no Bedrock AgentCore Runtime

Infraestrutura como Código

Se selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura CDK ou Terraform relevante é gerada para que você possa implantar seu Strands Agent no Amazon Bedrock AgentCore Runtime.

CDK
Terraform

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:

# Agent
module "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/*"
      ]
    }
  ]
}

Ao implantar no Bedrock AgentCore Runtime, você precisará garantir que os modelos de fundação apropriados estejam habilitados em sua conta AWS. Por padrão, agentes Strands usam Claude 4 Sonnet, mas isso pode ser personalizado conforme descrito acima.

Para habilitar acesso a modelos no Amazon Bedrock, siga as instruções aqui.

Docker é necessário para construir e implantar seu Strands Agent. Certifique-se de ter instalado e iniciado o Docker para evitar erros como:

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

Alvos de Bundle e Docker

Para construir seu Strands Agent para Bedrock AgentCore Runtime, um alvo bundle é adicionado ao seu projeto, que:

Exporta suas dependências Python para um arquivo requirements.txt usando uv export
Instala dependências para a plataforma alvo (aarch64-manylinux2014) usando uv pip install

Um alvo docker específico para seu Strands Agent também é adicionado, que:

Constrói uma imagem docker a partir do Dockerfile que executa seu agente, conforme o contrato de runtime do AgentCore

A imagem docker é construída usando uma tag (por exemplo my-scope-my-project-agent:latest), que é referenciada por sua infraestrutura CDK ou Terraform, permitindo que seu Dockerfile fique co-localizado com seu projeto Strands Agent.

Autenticação

IAM

Por padrão, seu Strands Agent será protegido usando autenticação IAM, basta implantá-lo sem argumentos:

CDK
Terraform

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

# Agent
module "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

O exemplo abaixo demonstra como configurar autenticação Cognito para seu agente.

CDK
Terraform

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 com seus IDs de 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

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.