View a markdown version of this page

Implantação direta de código para Python - Rocha da Amazônia AgentCore

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Implantação direta de código para Python

Com a implantação direta de código, você empacota o código do agente Python e suas dependências em um arquivo de arquivos.zip e o implanta no AgentCore Tempo de execução. Seu agente ainda precisa seguir AgentCore Requisitos de execução : tem um arquivo entrypoint .py que usa o @app.entrypoint anotação de Base da Amazônia AgentCore SDK para Python ou implementos /invocations POST e /ping OBTENHA endpoints do servidor.

Esta página inclui uma descrição concisa AgentCore Caminho da CLI e instruções detalhadas para empacotar e implantar o arquivo.zip manualmente com uv, Boto3 ou o AWS Console de gerenciamento. Para ver o fluxo de trabalho completo da CLI, consulte Comece com AgentCore Tempo de execução usando o AgentCore CLI.

Pré-requisitos

Antes de começar, verifique se você tem:

Etapa 1: Prepare e teste seu agente Python

Seu projeto deve conter os arquivos que você adicionará ao pacote de implantação:

my-agent/ ├── main.py └── pyproject.toml

Execute o agente localmente usando o comando do seu aplicativo. Para um ponto de entrada que inicia seu servidor a partir de main.py, execute:

uv run main.py

Em outro terminal, teste o /invocations ponto final:

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 deter o agente.

Opcionalmente, execute uv add aws-opentelemetry-distro para habilitar Rocha da Amazônia AgentCore traços de observabilidade.

Etapa 2: habilite a observabilidade para seu agente

Base da Amazônia AgentCore Observabilidade ajuda você a rastrear, depurar e monitorar os agentes que você hospeda no AgentCore Tempo de execução. Primeiro habilite CloudWatch Pesquise transações seguindo as instruções em Habilitando o Amazon Bedrock AgentCore observabilidade em tempo de execução . Para observar seu agente, consulte Visualize dados de observabilidade do seu Amazon Bedrock AgentCore agentes.

Etapa 3: empacotar, implantar e invocar

Empacote e implante seu agente usando um dos seguintes métodos:

exemplo
AgentCore CLI
  1. Para um CLI-managed CodeZip projeto, o AgentCore A CLI empacota e implanta o projeto para você. Para implantar seu agente existente com o AgentCore CLI, crie um projeto a partir do modelo mínimo:

    agentcore create --name DirectDeployProject --template agent-python-minimal cd DirectDeployProject

    Copie seu main.py e pyproject.toml em app/agent/, substituindo os arquivos gerados. Em seguida, implante o projeto:

    agentcore deploy

    Opcionalmente, execute agentcore build primeiro a sintetizar e verificar o projeto sem implantá-lo.

    Invoque o Runtime implantado:

    agentcore invoke --runtime agent \ --payload '{"prompt":"Hello!"}'

    Você também pode correr agentcore sem argumentos para abrir a interface de usuário interativa do terminal e, em seguida, escolha disponibilizar para acompanhar o progresso da implantação. Para testes locais, consulte Comece com AgentCore Tempo de execução usando o AgentCore CLI.

Boto3
  1. Para baixar um volante compatível com AgentCore Tempo de execução, você usa o uv pip --python-platform opção. AgentCore O Runtime suporta somente o arm64 arquitetura. Execute o comando a seguir e substitua 3.13 em --python-version com sua versão do Python.

    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 até a 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 Execute ou atualize um existente. Você pode implantar seu pacote.zip usando o AgentCore Runtime API, a AgentCore Console de tempo de execução ou o AWS Interface de linha de comando.

    nota

    O tamanho máximo de um pacote de implantação.zip para AgentCore O tempo de execução é de 250 MB (compactado) e 750 MB (descompactado). Esse limite se aplica ao tamanho combinado de todos os arquivos que você carrega.

    nota

    O AgentCore O Runtime precisa de permissão para ler os arquivos em seu pacote de implantação. Na notação octal de permissões do Linux, AgentCore O 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 chmod 644 <filepath>. Para alterar as permissões de arquivo no Windows, consulte Set, View, Change, or Remove Permissions on an Object na documentação do Microsoft Windows. Se você não conceder AgentCore Execute as permissões necessárias para acessar os diretórios em seu pacote de implantação, AgentCore O Runtime define as permissões para esses diretórios como 755 (rwxr-xr-x).

    Um arquivo ZIP contendo Linux arm64 as dependências precisam ser carregadas no S3 como pré-requisito para criar o Agent Runtime. O código abaixo exige que o bucket S3 especificado já exista. Para criar um bucket, consulte create_bucket na documentação do Boto3. O código boto3 a seguir fará o upload do arquivo de arquivos.zip para um s3 e criará o Amazon Bedrock AgentCore tempo de execução.

    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 Invoque agentes de streaming.

AWS Management Console

Você pode implantar seu agente usando o Amazon Bedrock AgentCore console com suporte de tempo de execução gerenciado.

Para implantar usando o console, primeiro crie seu pacote de implantação seguindo as etapas na Boto 3 guia acima.

Crie um agente por meio do console

Para criar seu agente:

  1. Na página inicial dos agentes, escolha Agente anfitrião

  2. Escolha sua seleção de fonte:

    • Fonte S3 - Carregar do bucket S3

    • Upload local - Carregue o arquivo ZIP do seu computador

    • Modelos - Use modelos de agentes pré-criados

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

  4. Escolha Criar agente para implantar

Crie um endpoint

Escolha Criar endpoint para criar um novo endpoint para seu agente. O nome do endpoint e a versão associada serão preenchidos previamente.

Ponto final de teste

Selecione um endpoint e escolha Ponto final de teste para navegar até o Playground/Sandbox para testar.

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 AgentCore Permissões de execução . A função de execução deve incluir o Amazon Bedrock básico AgentCore permissões de tempo de execução, permissões de acesso ao S3 para seu pacote de implantação e CloudWatch Registra permissões para observabilidade.

Etapa 4: interromper uma sessão, atualizar ou limpar

Pare sua sessão de tempo de execução, atualize ou limpe seu agente usando um dos seguintes métodos:

exemplo
AgentCore CLI
  1. Implante o projeto novamente para atualizar o Runtime:

    agentcore deploy

    Para excluir os recursos implantados do projeto, remova os recursos do projeto e implante a configuração atualizada:

    agentcore remove all --yes agentcore deploy --yes

    Para interromper uma sessão ativa do Runtime, use o StopRuntimeSession Operação da API.

Boto3
  1. O código boto3 a seguir atualizará um AgentCore Tempo de execução.

    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='<your-agent-id>', 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 economize 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 Amazon Bedrock AgentCore tempo de execução e 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='<agent-id>' ) 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!")
AWS Management Console

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 “excluir” 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

Saiba mais sobre Python-specific conceitos ao usar a implantação direta de código com o Amazon Bedrock AgentCore Tempo de execução.

Tópicos

    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 tempo de execução 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 para seu AgentCore Agente de tempo de execução 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 em 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

    Recomendamos que você não inclua pycache pastas no pacote de implantação do seu agente. O bytecode Python compilado em uma máquina de compilação com uma arquitetura ou sistema operacional diferente pode não ser compatível com o AgentCore Ambiente de execução em tempo de execução.

    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 populares de Python, incluindo NumPy e Pandas, não são Python puro e contêm código escrito em C ou C. Quando você adiciona bibliotecas contendo C/C código para seu pacote de implantação, você deve criar seu pacote corretamente para torná-lo compatível com o AgentCore Ambiente de execução em tempo de execução.

    A maioria dos pacotes disponíveis no Python Package Index ( PyPI ) estão disponíveis como “rodas” (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 Runtime, você instala o volante para sistemas operacionais Linux e arm64 arquitetura do conjunto de instruções.

    Alguns pacotes podem estar disponíveis apenas como distribuições de origem. Para esses pacotes, você precisa compilar e construir o C/C++ componentes você mesmo.

    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.

    2. Escolha a versão do pacote que você deseja usar.

    3. Escolha Baixar arquivos.

    Se seu pacote estiver disponível apenas como distribuição de origem, você precisará criar o C/C++ bibliotecas você mesmo. Para tornar seu pacote compatível com o Amazon Bedrock AgentCore Ambiente de execução de tempo de execução, você precisa construí-lo em um ambiente que usa o mesmo sistema operacional Amazon Linux com arm64 conjunto de instruções. 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 no Guia do usuário do Amazon EC2.