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?

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

Uso

Gerar um Agente Strands

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

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - py#strands-agent
5. Preencha os parâmetros obrigatórios
6. Clique em 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Dica

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

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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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

Nota

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

• 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

Nota

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• 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

Nota

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

Para implantar seu Agente Strands, os seguintes arquivos são gerados:

CDK

• 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

Terraform

• 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

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

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

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

agent.py

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

Dica

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

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

Terraform

# 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.

Servidor FastAPI

O gerador usa FastAPI para criar o servidor HTTP para seu Agente Strands. FastAPI fornece um framework web moderno e rápido para construção de APIs com Python, com documentação automática de API e validação de tipos.

O servidor gerado inclui:

• Configuração da aplicação FastAPI com middleware CORS
• Middleware de tratamento de erros
• Geração de schema OpenAPI
• Endpoint de verificação de saúde (/ping)
• Endpoint de invocação do agente (/invocations)

Personalizando Entradas e Saídas de Invocação com Pydantic

O endpoint de invocação do agente usa modelos Pydantic para definir e validar os schemas de requisição e resposta. Você pode personalizar esses modelos em main.py para atender aos requisitos do seu agente.

Definindo Modelos de Entrada

O modelo padrão InvokeInput aceita um prompt e um ID de sessão.

from pydantic import BaseModel

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

Você pode estender este modelo para incluir quaisquer campos adicionais que seu agente necessite.

Cuidado

Você provavelmente desejará abstrair parte ou todo o ID de sessão do chamador se os usuários forem invocar seu agente diretamente. Por exemplo, você pode usar o ID do usuário autenticado como parte do ID de sessão.

Também vale a pena notar que, dependendo do seu caso de uso, você pode precisar implementar autorização para sessões, por exemplo, garantindo que os usuários possam acessar apenas suas próprias sessões e não as de outros usuários.

Definindo Modelos de Saída

Para respostas em streaming, a anotação de tipo de retorno em seu endpoint corresponde ao tipo de cada valor produzido pela sua função geradora. Por padrão, o agente produz strings contendo o texto de resposta do agente conforme ele é transmitido de volta do Strands:

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Entry point for agent invocation"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

Você pode definir um modelo Pydantic para produzir dados estruturados em vez disso:

from pydantic import BaseModel

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

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(handle_invoke(input), media_type="application/json")

Bedrock AgentCore Python SDK

O gerador inclui uma dependência no Bedrock AgentCore Python SDK para as constantes PingStatus. Se desejar, é simples usar BedrockAgentCoreApp em vez de FastAPI, porém note que a segurança de tipos é perdida.

Você pode encontrar mais detalhes sobre as capacidades do SDK na documentação aqui.

Nota

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 Agente Strands

Desenvolvimento Local

O gerador configura um alvo chamado <your-agent-name>-serve, que inicia seu Agente Strands localmente para desenvolvimento e testes.

pnpm

pnpm nx run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

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

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.

CDK

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

Terraform

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

Nota

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.

Cuidado

Docker é necessário para construir e implantar seu Agente Strands. 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 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 usando uv export
• Instala dependências para a plataforma alvo (aarch64-manylinux2014) usando uv 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

Dica

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 do Agente Strands.

Autenticação

IAM

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

CDK

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

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

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

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

Terraform

Para configurar autenticação JWT, você pode editar seu módulo de agente para configurar a variável customJWTAuthorizer da seguinte forma:

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

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

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.