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
-
-
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
-
-
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.
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.
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:
-
Na página inicial dos agentes, escolha Agente anfitrião
-
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
-
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)
-
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
-
-
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
-
-
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.
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:
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.