# Implantação direta de código para Python A implantação direta de código permite que você leve seu Python-based agente para o Amazon Bedrock AgentCore Runtime simplesmente empacotando o código do agente e suas dependências em um arquivo de arquivos.zip. Seu agente ainda precisa seguir [os requisitos de AgentCore tempo de execução](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html): ter um arquivo de ponto de entrada .py que use a `@app.entrypoint` anotação do [Amazon Bedrock AgentCore Python](https://github.com/aws/bedrock-agentcore-sdk-python) SDK ou implemente endpoints de servidor POST e GET. `/invocations` `/ping` ## Pré-requisitos Antes de começar, verifique se você tem: + ** AWS Conta** com credenciais configuradas. Para definir suas AWS credenciais, consulte [Configuração e configurações do arquivo de credenciais na CLI AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). + [Uv](https://docs.astral.sh/uv/getting-started/installation/) **instalado** e [Python](https://docs.astral.sh/uv/guides/install-python/) 3.10\+ instalado + ** AWS Permissões**: para criar e implantar um agente com a AgentCore CLI, você deve ter as permissões apropriadas. Para obter mais informações, consulte [Usar a AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli). + **Acesso ao modelo**: Anthropic Claude Sonnet 4.0 [habilitado no console](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) Amazon Bedrock. Para obter informações sobre como usar um modelo diferente com os Strands Agents, consulte a seção *Model Providers* na documentação do [SDK do Strands Agents](https://strandsagents.com/latest/documentation/docs/). ## Etapa 1: configurar o projeto e instalar dependências Inicialize seu projeto com os seguintes comandos: ``` uv init agentcore_runtime_direct_deploy --python 3.13 cd agentcore_runtime_direct_deploy ``` Adicione pacotes principais: ``` uv add bedrock-agentcore strands-agents ``` Instale a AgentCore CLI (necessária para as etapas a seguir): ``` npm install -g @aws/agentcore ``` Descrições do pacote: + **bedrock-agentcore** — O Amazon AgentCore Bedrock SDK para criar agentes de IA + **strands-agents** [- O SDK do Strands Agents](https://strandsagents.com/latest/) + **@ aws/agentcore** - A AgentCore CLI Opcionalmente, execute `uv add aws-opentelemetry-distro` para habilitar os rastreamentos de [ AgentCore observabilidade do Amazon Bedrock](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). O Uv criará automaticamente um `pyproject.toml` arquivo com dependências, `uv.lock` arquivo com fechamento de dependência e `.venv` diretório. ## Etapa 2: criar seu projeto de agente Use o `agentcore create` comando para configurar um projeto de agente esqueleto com a estrutura de sua escolha: ``` agentcore create ``` O comando solicitará que você: + Escolha uma estrutura (escolha Strands Agents para este tutorial) + Forneça um nome de projeto + Escolha um modelo (básico ou de produção) + Escolha modelo, fornecedor e outras opções Esse comando gera: + Código do agente com sua estrutura selecionada + Um `pyproject.toml` arquivo com as dependências necessárias + Um arquivo `agentcore/agentcore.json` de configuração + Arquivos de infraestrutura como código (IaC) se o modelo de produção for selecionado ## Etapa 3: testar localmente Certifique-se de que a porta 8080 esteja livre antes de iniciar. Consulte *Porta 8080 em uso (somente local)* em [Problemas e soluções comuns](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). Abra uma janela de terminal e inicie seu agente com o seguinte comando: ``` agentcore dev --no-browser ``` Teste seu agente abrindo outra janela do terminal e digite o seguinte comando: ``` curl -X POST http://localhost:8080/invocations \ -H "Content-Type: application/json" \ -d '{"prompt": "Hello!"}' ``` **Sucesso:** Você deve ver uma resposta como`{"result": "Hello! I’m here to help…​"}`. Na janela do terminal que está executando o agente, digite `Ctrl+C` para interromper o agente. ## Etapa 4: habilitar a observabilidade para seu agente [O Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) ajuda você a rastrear, depurar e monitorar agentes que você hospeda no Runtime. AgentCore Primeiro, habilite a Pesquisa de CloudWatch transações seguindo as instruções em [Habilitando a observabilidade do tempo de AgentCore execução do Amazon Bedrock](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Para observar seu agente, consulte [Visualizar dados de observabilidade de seus agentes do Amazon Bedrock AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html). ## Etapa 5: implantar no AgentCore Runtime e invocar Implante seu agente usando um dos seguintes métodos: **Example** 1. As etapas a seguir serão necessárias para implantar um agente no AgentCore Runtime. Para obter mais informações, consulte [Introdução à AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html). Se o Uv estiver disponível, a AgentCore CLI recomendará a implantação direta do código. Caso contrário, o padrão será o tipo de implantação de contêiner. Depois de configurar seu agente usando`agentcore create`, use o `deploy` comando para criar um pacote de implantação zip, carregá-lo no bucket especificado e implantar o agente. ``` agentcore deploy ``` Vamos pedir ao agente que conte uma piada\! ``` agentcore invoke "Tell me a joke" ``` A primeira implantação leva tempo para instalar dependências, mas as atualizações subsequentes do agente otimizam isso reutilizando dependências compactadas. **Gerenciamento de configuração** Você pode modificar a configuração do seu agente a qualquer momento usando os `agentcore add` comandos ou editando diretamente o arquivo de `agentcore/agentcore.json` configuração. O arquivo de configuração permite que você atualize os parâmetros de implantação, como sua configuração de VPC, funções de execução, tempos limite de sessão e configurações do autorizador OAuth. 1. Execute `agentcore` para abrir a TUI e selecione **implantar**. A tela de implantação mostra o progresso em tempo real à medida que valida seu projeto, sintetiza e provisiona CloudFormation recursos: AWS ![AgentCore progresso da implantação mostrando as atualizações CloudFormation da pilha](http://docs.aws.amazon.com/pt_br/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) Após a conclusão da implantação, use `agentcore invoke` para testar seu agente. 1. Para baixar uma roda compatível com o AgentCore Runtime, você usa a `--python-platform` opção uv pip. AgentCore O Runtime suporta apenas a arquitetura do conjunto de instruções **arm64**, execute o comando a seguir. Substitua `--python 3.x` pela versão do runtime do Python que você está usando. ``` uv pip install \ --python-platform aarch64-manylinux2014 \ --python-version 3.13 \ --target=deployment_package \ --only-binary=:all: \ -r pyproject.toml ``` Crie um arquivo.zip com as bibliotecas instaladas na raiz do projeto. ``` cd deployment_package zip -r ../deployment_package.zip . ``` Adicione o `main.py` arquivo e outros arquivos em seu pacote à raiz do arquivo.zip. ``` cd .. zip deployment_package.zip main.py ``` Depois de criar seu pacote de implantação.zip, você pode usá-lo para criar um novo AgentCore Runtime ou atualizar um existente. Você pode implantar seu pacote.zip usando a API AgentCore Runtime, o console AgentCore Runtime e a interface de linha de AWS comando. A AgentCore CLI cuidará das etapas acima para criar .zip. **nota** . O tamanho máximo de um pacote de implantação.zip para AgentCore Runtime é 250 MB (compactado) e 750 MB (descompactado). Observe que esse limite se aplica ao tamanho combinado de todos os arquivos que você carrega. O AgentCore Runtime precisa de permissão para ler os arquivos em seu pacote de implantação. Na notação octal de permissões do Linux, o AgentCore Runtime precisa de 644 permissões para arquivos não executáveis (rw-r—r--) e 755 permissões (rwxr-xr-x) para diretórios e arquivos executáveis. No Linux e no MacOS, use o comando `chmod` para alterar as permissões de arquivo em arquivos e diretórios do seu pacote de implantação. Por exemplo, para dar a um arquivo não executável as permissões corretas, execute o comando a seguir,. `chmod 644 ` Para alterar as permissões de arquivo no Windows, consulte [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) na documentação do Microsoft Windows. \+.. Se você não conceder ao AgentCore Runtime as permissões necessárias para acessar os diretórios em seu pacote de implantação, o AgentCore Runtime definirá as permissões desses diretórios como 755 (rwxr-xr-x). Um arquivo ZIP contendo dependências Linux **arm64** precisa ser carregado no S3 como pré-requisito para criar o Agent Runtime. O código abaixo exige que o bucket S3 especificado já exista. Siga a AWS documentação [aqui](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html) para criar um bucket usando o boto3. O código boto3 a seguir carregará o arquivo de arquivo.zip em um s3 e criará o tempo de execução do Amazon Bedrock. AgentCore ``` import boto3 account_id = "your aws account id" agent_name = "strands_10_23" s3_client = boto3.client('s3', region_name='us-west-2') print("Uploading deployment.zip to S3...") s3_client.upload_file( 'deployment_package.zip', # archive on file system f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name f"{agent_name}/deployment_package.zip", # prefix ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check ) print("Upload completed successfully!") print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip") agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') response = agentcore_client.create_agent_runtime( agentRuntimeName=agent_name, agentRuntimeArtifact={ 'codeConfiguration': { 'code': { 's3': { 'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2", 'prefix': f"{agent_name}/deployment_package.zip" } }, 'runtime': 'PYTHON_3_13', 'entryPoint': ['opentelemetry-instrument', 'main.py'] } # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array }, networkConfiguration={"networkMode": "PUBLIC"}, roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2", lifecycleConfiguration={ 'idleRuntimeSessionTimeout': 300, # 5 min, configurable 'maxLifetime': 1800 # 30 minutes, configurable }, ) print(f"Agent Runtime created successfully!") print(f"Agent Runtime ARN: {response['agentRuntimeArn']}") print(f"Status: {response['status']}") ``` Para obter mais informações sobre como invocar um agente programaticamente, consulte [Invocar](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically) um agente programaticamente. 1. Você pode implantar seu agente usando o AgentCore console Amazon Bedrock com suporte gerenciado ao tempo de execução. O console fornece uma interface intuitiva para carregar arquivos ZIP e definir as configurações do agente. Para implantar usando o console, primeiro crie seu pacote de implantação seguindo as etapas na guia *Custom zip \+ boto3* acima. **Crie um agente por meio do console** Para criar seu agente: 1. Na página inicial dos Agentes, escolha **Host Agent** 1. Escolha sua seleção de fonte: + **Fonte do S3** - Carregar do bucket do S3 + **Upload local** - Carregue o arquivo ZIP do seu computador + **Modelos** - Use modelos de agente pré-criados 1. Defina as configurações do seu agente: + Nome do agente + Versão Runtime (Python 3.13 recomendado) + Ponto de entrada (por exemplo,`main.py`) + Função de execução (criar uma nova ou usar a existente) 1. Escolha **Criar agente** para implantar **Criar endpoint** Escolha **Criar endpoint** para criar um novo endpoint para seu agente. O nome do endpoint e a versão associada serão pré-preenchidos. **Ponto final do teste** Selecione um endpoint e escolha **Test Endpoint** para navegar até o Playground/Sandbox para teste. **Requisitos da função de execução** Seu agente exige uma função de execução com as permissões apropriadas. Para obter informações detalhadas sobre funções e permissões de execução, consulte [Permissões AgentCore de tempo de execução](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). A função de execução deve incluir permissões básicas de tempo de AgentCore execução do Amazon Bedrock, permissões de acesso ao S3 para seu pacote de implantação e permissões de CloudWatch registros para observabilidade. ## Etapa 6: interromper a sessão, atualizar ou limpar Interrompa sua sessão de tempo de execução, atualize ou limpe seu agente usando um dos seguintes métodos: **Example** 1. Para atualizar o AgentCore Runtime implantado anteriormente, execute: ``` agentcore deploy ``` Para interromper uma sessão em execução antes do configurável `IdleRuntimeSessionTimeout` (o padrão é de 15 minutos) e economizar em possíveis custos descontrolados, use a operação da API. [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) Atualmente, a AgentCore CLI não oferece suporte direto à interrupção direta de sessões. Para excluir todos os recursos relacionados a um AgentCore Runtime, primeiro remova todos os recursos e depois implante para eliminar AWS os recursos: ``` agentcore remove all agentcore deploy ``` 1. O código boto3 a seguir atualizará um AgentCore Runtime. ``` import boto3 account_id = "your aws account id" agent_name = "strands_10_23" s3_client = boto3.client('s3', region_name='us-west-2') print("Uploading deployment.zip to S3...") s3_client.upload_file( 'deployment_package.zip', # archive on file system f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name f"{agent_name}/deployment_package.zip", # prefix ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check ) print("Upload completed successfully!") print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip") bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') response = bedrock_agentcore_client.update_agent_runtime( agentRuntimeId='', agentRuntimeArtifact={ 'codeConfiguration': { 'code': { 's3': { 'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2", 'prefix': f"{agent_name}/deployment_package.zip" } }, 'runtime': 'PYTHON_3_13', 'entryPoint': ['opentelemetry-instrument', 'main.py'] } # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array }, networkConfiguration={"networkMode": "PUBLIC"}, roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2" ) print(f"Agent Runtime updated successfully!") print(f"Agent Runtime ARN: {response['agentRuntimeArn']}") print(f"Status: {response['status']}") ``` Para interromper a sessão em execução antes do configurável `IdleRuntimeSessionTimeout` (o padrão é de 15 minutos) e economizar em possíveis custos descontrolados, use o seguinte código boto3: ``` import boto3 agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2') response = agent_core_client.stop_runtime_session( agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/agent-name-suffix', runtimeSessionId='your-session-id', qualifier="DEFAULT" ) ``` O código boto3 a seguir excluirá o tempo de AgentCore execução do Amazon Bedrock e o arquivo de arquivamento .zip no s3. ``` import boto3 account_id = "your aws account id" agent_name = "strands_10_23" bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2') print("Deleting Agent from Amazon Bedrock AgentCore Runtime!") response = bedrock_agentcore_client.delete_agent_runtime( agentRuntimeId='' ) print(f"Agent Runtime delete successfully!") print(f"Status: {response['status']}") s3_client = boto3.client('s3', region_name='us-west-2') print("Deleting deployment archive from S3...") s3_client.delete_object( Bucket=f"bedrock-agentcore-code-{account_id}-us-west-2", Key=f"{agent_name}/deployment_package.zip", ExpectedBucketOwner=account_id ) print("Archive deleted successfully from S3!") ``` 1. ====== Agente de atualização Na página de detalhes do agente, escolha **Atualizar hospedagem** para criar uma nova versão com código ou configuração atualizados. **Atualizar endpoint** Selecione um endpoint na tabela Endpoints e escolha **Editar** para atualizar a descrição ou a versão associada. **Excluir endpoint** Selecione um endpoint e escolha **Excluir**. Você precisará digitar “delete” para confirmar a exclusão. **Excluir agente** Na lista de agentes ou na página de detalhes, selecione seu agente e escolha **Excluir** para remover o agente e todos os recursos associados. ## Python-specific conceitos para implantação direta de código Aprenda sobre Python-specific conceitos ao usar a implantação direta de código com o Amazon Bedrock AgentCore Runtime. **Topics** ### Caminho de pesquisa de dependências e bibliotecas incluídas no runtime Quando você usa uma instrução `import` no código, o runtime do Python pesquisa os diretórios no caminho de pesquisa até encontrar o módulo ou pacote. Por padrão, o primeiro local que o runtime pesquisa é o diretório no qual seu pacote de implantação .zip é descompactado e montado (). `/var/task` Você pode ver o caminho de pesquisa completo do seu agente AgentCore Runtime adicionando o seguinte trecho de código. ``` import sys search_path = sys.path print(search_path) ``` Você também pode adicionar dependências em uma pasta separada dentro do pacote .zip. Por exemplo, você pode adicionar uma versão do SDK do Boto3 a uma pasta no seu pacote.zip chamada. `common` Quando o pacote .zip é descompactado e montado, essa pasta é colocada dentro do diretório `/var/task`. Para usar uma dependência proveniente de uma pasta do pacote de implantação .zip no código, use uma instrução `import from`. Por exemplo, para usar uma versão do Boto3 proveniente de uma pasta denominada `common` no pacote.zip, use a instrução a seguir. ``` from common import boto3 ``` ### Bytecode Python e *pycache* pastas Recomendamos que você não inclua ` pycache ` pastas no pacote de implantação do seu agente. O bytecode do Python compilado em uma máquina de compilação com uma arquitetura ou sistema operacional diferente pode não ser compatível com o ambiente de execução do AgentCore Runtime. ### Pacotes de implantação com bibliotecas nativas Se a função usar somente pacotes e módulos Python puros, você poderá usar o comando `uv pip install` para instalar as dependências em qualquer máquina de compilação local e criar o arquivo .zip. Muitas bibliotecas Python populares, incluindo NumPy e Pandas, não são Python puro e contêm código escrito em C ou C. Ao adicionar bibliotecas contendo C/C código ao seu pacote de implantação, você deve criar seu pacote corretamente para torná-lo compatível com o ambiente de execução do Runtime. AgentCore A maioria dos pacotes disponíveis no Python Package Index ([PyPI](https://pypi.org/)) está disponível como “wheels” (arquivos.whl). Um arquivo .whl é um tipo de arquivo ZIP que contém uma distribuição criada com binários pré-compilados para um sistema operacional específico e uma arquitetura de conjunto de instruções. Para tornar seu pacote de implantação compatível com o Amazon Bedrock AgentCore AgentCore Runtime, você instala a roda para sistemas operacionais Linux e a arquitetura do conjunto de instruções **arm64**. Alguns pacotes podem estar disponíveis apenas como distribuições de origem. Para esses pacotes, você mesmo precisa compilar e criar os componentes C/C \+\+. Para ver quais distribuições estão disponíveis para o pacote necessário, faça o seguinte: 1. Pesquise o nome do pacote na [página principal do Python Package Index](https://pypi.org/). 1. Escolha a versão do pacote que você deseja usar. 1. Escolha **Baixar arquivos**. ### Trabalhar com distribuições de origem Se seu pacote estiver disponível apenas como distribuição de origem, você mesmo precisará criar as bibliotecas C/C \+\+. Para tornar seu pacote compatível com o ambiente de AgentCore AgentCore execução do Amazon Bedrock Runtime, você precisa criá-lo em um ambiente que use o mesmo sistema operacional Amazon Linux com o conjunto de instruções **arm64**. Você pode fazer isso compilando o pacote em uma instância Linux do Amazon Elastic Compute Cloud (Amazon EC2). Para saber como iniciar e se conectar a uma instância do Linux no Amazon EC2, consulte [Comece a usar o Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) no *Guia do usuário do Amazon EC2*.