Pular para o conteúdo
@aws/nx-plugin
Blog

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

Uso

Seção intitulada “Uso”

Gerar um Agente Strands

Seção intitulada “Gerar um Agente Strands”

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

  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
    • Clique em Generate

    Opções

    Seção intitulada “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

    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

    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

    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
    

    @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

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

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

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

    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', {
          environmentVariables: {
            MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.agentRuntimeArn,
          },
        });
    

        mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
      }
    }

    Mais

    Seção intitulada “Mais”

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

    Servidor FastAPI

    Seção intitulada “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

    Seção intitulada “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

    Seção intitulada “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.

    Definindo Modelos de Saída

    Seção intitulada “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. Para fazer isso, você precisará serializar os modelos pydantic produzidos por handle_invoke:

    from pydantic import BaseModel
    

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

    def handle_invoke(...):
        ...
        yield StreamChunk(content="xx", timestamp="yy", token_count=5)
    

    def serialize_stream(generator):
        async for output in generator:
            yield (output.model_dump_json() + "\n").encode("utf-8")
    

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

    Bedrock AgentCore Python SDK

    Seção intitulada “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.

    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.

    Terminal window
    pnpm 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 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.

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

    Autenticação

    Seção intitulada “Autenticação”

    IAM

    Seção intitulada “IAM”

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

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

    Autenticação Cognito JWT

    Seção intitulada “Autenticação Cognito JWT”

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

    Para configurar a autenticação JWT usando Cognito, use o método de fábrica RuntimeAuthorizerConfiguration.usingCognito():

    import { MyProjectAgent } from ':my-scope/common-constructs';
    import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';
    

    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: RuntimeAuthorizerConfiguration.usingCognito(
            userPool,
            [client],
          ),
        });
      }
    }

    Alternativamente, para autenticação JWT personalizada com seu próprio provedor OIDC, use RuntimeAuthorizerConfiguration.usingJWT():

    import { MyProjectAgent } from ':my-scope/common-constructs';
    import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        new MyProjectAgent(this, 'MyProjectAgent', {
          authorizerConfiguration: RuntimeAuthorizerConfiguration.usingJWT(
            'https://example.com/.well-known/openid-configuration',
            ['client1', 'client2'], // Allowed Client IDs (optional)
            ['audience1'],          // Allowed Audiences (optional)
          ),
        });
      }
    }

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

    Autenticação

    Seção intitulada “Autenticação”

    IAM

    Seção intitulada “IAM”

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

    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 usando Cognito, use o método de fábrica RuntimeAuthorizerConfiguration.usingCognito():

    import { MyProjectAgent } from ':my-scope/common-constructs';
    import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';
    

    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: RuntimeAuthorizerConfiguration.usingCognito(
            userPool,
            [client],
          ),
        });
      }
    }

    Alternativamente, para autenticação JWT personalizada com seu próprio provedor OIDC, use RuntimeAuthorizerConfiguration.usingJWT():

    import { MyProjectAgent } from ':my-scope/common-constructs';
    import { RuntimeAuthorizerConfiguration } from '@aws-cdk/aws-bedrock-agentcore-alpha';
    

    export class ExampleStack extends Stack {
      constructor(scope: Construct, id: string) {
        new MyProjectAgent(this, 'MyProjectAgent', {
          authorizerConfiguration: RuntimeAuthorizerConfiguration.usingJWT(
            'https://example.com/.well-known/openid-configuration',
            ['client1', 'client2'], // IDs de Cliente Permitidos (opcional)
            ['audience1'],          // Audiências Permitidas (opcional)
          ),
        });
      }
    }

    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.

    Invocando seu Agente Strands

    Seção intitulada “Invocando seu Agente Strands”

    Invocar o Servidor Local

    Seção intitulada “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:

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

    Invocar o Agente Implantado

    Seção intitulada “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:

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

    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.

    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

    Seção intitulada “Autenticação IAM”

    Para Autenticação IAM, a requisição deve ser assinada usando AWS Signature Version 4 (SigV4).

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

    Seção intitulada “Autenticação JWT / Cognito”

    Para Autenticação Cognito, passe o Token de Acesso Cognito no cabeçalho Authorization:

    Terminal window
    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:

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