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

Pré-requisito do projeto

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	-	O projeto ao qual adicionar o Strands Agent
computeType	string	BedrockAgentCoreRuntime	O tipo de computação para hospedar seu Strands Agent.
name	string	-	O nome do seu Strands Agent (padrão: agent)
auth	string	IAM	O método usado para autenticar com seu Strands Agent. Escolha entre IAM (padrão) ou Cognito.
iacProvider	string	Inherit	O provedor de IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

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
      • init.py Configuração da aplicação FastAPI com middleware CORS e tratamento de erros
      • agent.py Definição principal do agente com ferramentas de exemplo
      • main.py Ponto de entrada para 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

Implantação serverless

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

Projeto gerado

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

Projeto gerado

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

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, você pode usar o gerador connection.

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 - connection
5. Preencha os parâmetros obrigatórios
6. Clique em 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

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

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

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Para outros servidores MCP, consulte a Documentação do Strands.

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.

Organização do código

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, o gerador fornece JsonStreamingResponse que serializa automaticamente modelos Pydantic para o formato JSON Lines (application/jsonl). Este formato é compatível com a especificação de streaming do OpenAPI 3.2 e funciona perfeitamente com o cliente TypeScript gerado.

Por padrão, o agente produz objetos StreamChunk contendo o texto de resposta do agente:

class StreamChunk(BaseModel):
    content: str

Você pode personalizar o modelo StreamChunk para atender às suas necessidades:

from pydantic import BaseModel

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

Limitação de streaming do FastAPI

Note que como o FastAPI atualmente não suporta a geração de uma especificação OpenAPI para respostas em streaming, devemos definir explicitamente o modelo de resposta para cada operação de streaming, ou seja:

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

Existe uma solicitação de recurso aberta para suporte nativo no FastAPI.

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.

Infraestrutura como código

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

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 você selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura CDK ou Terraform relevante é gerada, que você pode usar para implantar seu Strands Agent no Amazon Bedrock AgentCore Runtime.

CDK

Um construto CDK é gerado para o seu agente, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>Agent por padrão.

Você pode usar este construto CDK em uma aplicação 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/*',
        ],
      }),
    );
  }
}

Construto CDK Alpha

Este construto usa o módulo @aws-cdk/aws-bedrock-agentcore-alpha.

Terraform

Um módulo Terraform é gerado para você, nomeado com base no name que você escolheu 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" {
  # 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/*"
      ]
    }
  ]
}

Docker necessário

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.

Autenticação

O gerador fornece uma opção auth para configurar a autenticação para o seu Strands Agent. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu agente.

IAM

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

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 grantInvokeAccess, 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.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"
}

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

Quando você seleciona autenticação Cognito, o gerador configura o agente para usar Cognito para autenticação.

CDK

O construto gerado aceita uma propriedade identity que configura a autenticação 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,
    });
  }
}

O construto UserIdentity pode ser gerado usando o gerador ts#react-website#auth, ou você pode criar seu próprio UserPool e UserPoolClient CDK.

Terraform

O módulo gerado aceita variáveis user_pool_id e user_pool_client_ids para autenticação 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]
}

Provedores OIDC personalizados

Se você precisar de autenticação JWT personalizada com um provedor OIDC não-Cognito, você pode modificar o construto CDK gerado ou o módulo Terraform para o seu agente diretamente. Note que o gerador de conexão suportará apenas autenticação IAM ou Cognito.

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

Tags de imagem Docker

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.

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.

Invocando seu Agente Strands

Invocar o Servidor Local

Para invocar um Agente executando localmente através do alvo <your-agent-name>-serve, você pode enviar uma requisição POST simples para /invocations na porta em que seu agente local está sendo executado. Por exemplo, com curl:

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

Flag de streaming do Curl

O argumento -N dado ao curl desabilita o buffering do fluxo de saída, para que você possa ver a resposta em streaming em tempo real.

Invocar o Agente Implantado

Para invocar seu Agent implantado no Bedrock AgentCore Runtime, você pode enviar uma requisição POST para o endpoint do dataplane do Bedrock AgentCore Runtime com seu ARN de runtime codificado em URL.

Você pode obter o ARN de runtime da sua infraestrutura da seguinte forma:

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
}

O ARN terá o seguinte formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Você pode então codificar o ARN em URL substituindo : por %3A e / por %2F.

Console do navegador

Isso é simples em um console do navegador ou Node REPL usando o método integrado encodeURIComponent:

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

A URL do dataplane do Bedrock AgentCore Runtime para invocar o agent é a seguinte:

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

A maneira exata de invocar esta URL depende do método de autenticação usado.

Autenticação IAM

Para Autenticação IAM, a requisição deve ser assinada usando 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'

Clique aqui para mais detalhes sobre como configurar o comando acurl acima

Autenticação JWT / Cognito

Para Autenticação Cognito, passe o Token de Acesso Cognito no cabeçalho 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>"

Você pode obter o token de acesso usando o comando cognito-idp admin-initiate-auth da AWS CLI, por exemplo:

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