View a markdown version of this page

Ambiente e sistema de arquivos - Amazon Bedrock AgentCore
Execute comandos no ambienteAmbiente personalizado (imagens de contêiner)Variáveis de ambienteSistema de arquivos

Ambiente e sistema de arquivos

Cada sessão de arnês é executada em uma microVM isolada com seu próprio sistema de arquivos e shell. Esta página aborda a configuração do ambiente de execução (contêiner padrão ou personalizado), a execução de comandos diretamente na VM, a definição de variáveis de ambiente e a montagem de sistemas de arquivos persistentes.

Execute comandos no ambiente

Nem tudo precisa passar pelo ciclo do agente. InvokeAgentRuntimeCommandfornece acesso direto ao shell ao harness microVM: execução de comandos determinísticos sem raciocínio de modelo, sem custo de token, sem ambigüidade.

Use-o para:

  • Execute scripts determinísticos de pré-invocação ou pós-invocação.

  • Prepare o ambiente antes de uma invocação: clone um repositório, instale dependências, copie arquivos de entrada.

  • Aja de acordo com o que o agente produziu: execute testes, confirme e envie, extraia artefatos de construção.

  • Inspecione a VM durante o desenvolvimento:ls,, catenv, python --version sem uma viagem de ida e volta pelo modelo.

exemplo
AWS CLI/boto3
response = client.invoke_agent_runtime_command(
    agentRuntimeArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    body={"command": "ls -la /workspace"},
)

for event in response["stream"]:
    chunk = event.get("chunk", {})
    if "contentDelta" in chunk:
        delta = chunk["contentDelta"]
        if "stdout" in delta:
            print(delta["stdout"], end="", flush=True)
        if "stderr" in delta:
            print(delta["stderr"], end="", flush=True)
    elif "contentStop" in chunk:
        print(f"\n[exit code: {chunk['contentStop']['exitCode']}]")
AgentCore CLI
# Install dependencies before the agent starts
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "pip install pandas matplotlib"

# After the agent finishes, inspect what it created
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "ls -la /tmp && cat /tmp/results.csv"
nota

O ambiente básico inclui Python e bash. Para ferramentas como gitnode, ou outros tempos de execução, instale-as no início da sessão (por exemploapt-get install -y git) ou use um ambiente personalizado.

Na TUI, pressione ! para entrar no modo exec e executar comandos em linha.

Consulte a InvokeAgentRuntimeCommand API para obter detalhes.

nota

Os comandos são executados como root (uid 0) dentro da microVM. Isso é análogo ao root em sua própria instância do EC2: a permissão do IAM é a porta de acesso, não o nível de privilégio na VM. Se o Dockerfile incluir uma USER diretiva, ela se aplicará somente ao processo do agente (o ponto de entrada principal do contêiner). InvokeAgentRuntimeCommandé executado em um nível de privilégio mais alto para fins operacionais, semelhante ao docker exec padrão root, mesmo quando o contêiner é executado como um usuário não root. Consulte Executar comandos shell em sessões AgentCore de tempo de execução para obter detalhes completos sobre segurança, tratamento de erros e melhores práticas.

Ambiente personalizado (imagens de contêiner)

O ambiente básico inclui Python e bash, o suficiente para a maioria das tarefas. Quando precisar de mais, empacote seu código-fonte, dependências, tempos de execução e ferramentas em uma imagem de contêiner, envie-a para o ECR e faça referência a ela no chicote. Seu agente funciona exatamente nesse ambiente. Combine imagens personalizadas com uma InvokeAgentRuntimeCommand configuração específica da sessão que varia de acordo com a invocação.

As imagens de contêiner devem ser criadas para a linux/arm64 plataforma.

O arnês substitui o do seu contêiner ENTRYPOINT e CMD o mantém funcionando como um ambiente. O software, o sistema de arquivos e as variáveis de ambiente instalados estão disponíveis para o agente; o comando de inicialização do contêiner não é executado. Se você precisar de um processo em segundo plano (como um servidor de desenvolvimento), inicie-o InvokeAgentRuntimeCommand após o início da sessão.

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "CodingAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-artifact '{"containerConfiguration": {"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-dev-env:latest"}}' \
  --system-prompt '[{"text": "You are an expert TypeScript developer."}]'

A função de execução precisa de permissões de extração do ECR. Consulte a política da função de execução para obter detalhes.

AgentCore CLI

Monte um arnês com um Dockerfile:

agentcore create --name coding-agent --container ./Dockerfile
agentcore deploy

Na implantação, a CLI cria a imagem, envia para o ECR e a conecta ao chicote.

Ou faça referência a uma imagem pré-criada:

agentcore create --name node-agent \
  --container public.ecr.aws/docker/library/node:slim
agentcore deploy

Variáveis de ambiente

Defina as variáveis de ambiente que são passadas para o contêiner de tempo de execução. As variáveis de ambiente estão disponíveis para o agente e para qualquer contêiner personalizado em execução na sessão.

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-variables '{"MY_API_URL": "https://api.example.com", "LOG_LEVEL": "debug"}'
AgentCore CLI

Defina as variáveis de ambiente emharness.json:

{
  "environmentVariables": {
    "MY_API_URL": "https://api.example.com",
    "LOG_LEVEL": "debug"
  }
}

Corra agentcore deploy para se inscrever.

Sistema de arquivos

O chicote monta o armazenamento persistente nos caminhos que você especificar. Os arquivos gravados nessas montagens sobrevivem ao término da sessão e ficam visíveis para invocações posteriores.

Um chicote suporta três tipos de sistema de arquivos:

  • Armazenamento de sessão — armazenamento por sessão gerenciado por serviço que persiste em todos os stop/resume ciclos da mesma forma. runtimeSessionId Não é necessário VPC.

  • Ponto de acesso Amazon EFS — traga seu próprio sistema de arquivos EFS, compartilhado entre sessões e agentes. É necessário um VPC.

  • Ponto de acesso Amazon S3 Files - traga seu próprio sistema de arquivos S3 Files que sincroniza bidirecionalmente com um bucket S3. É necessário um VPC.

Para pré-requisitos (rede VPC, permissões do IAM, grupos de segurança), comparação de tipos, limites e comportamento do ciclo de vida, consulte Configurações do sistema de arquivos para o Runtime. AgentCore Os mesmos requisitos se aplicam aos arneses.

Configure o ambiente e o sistema de arquivos na CLI AgentCore

exemplo
Interactive

Execute agentcore em um diretório de projeto para abrir a TUI, selecione adicionar e escolha Harness. O assistente orienta você pelo ambiente de execução e, nas configurações avançadas, pelo sistema de arquivos persistente.

  1. Na etapa Ambiente personalizado, mantenha o ambiente padrão ou escolha uma imagem de contêiner pré-criada (ECR URI) ou um Dockerfile.

    Adicionar assistente Harness: ambiente personalizado

  2. As montagens do sistema de arquivos exigem o modo VPC, portanto, nas configurações avançadas, habilite o armazenamento em rede e no sistema de arquivos com espaço e pressione Enter.

    Configurações avançadas com armazenamento em rede e sistema de arquivos ativado

  3. Escolha o modo de rede VPC e, em seguida, forneça as sub-redes e os grupos de segurança para o equipamento.

    Selecione o modo de rede VPC

  4. Defina o caminho de montagem do armazenamento da sessão (abaixo/mnt).

    Insira o caminho de montagem do armazenamento da sessão

  5. Para anexar um sistema de arquivos do Amazon EFS, insira o ARN do ponto de acesso EFS (e seu caminho de montagem na próxima etapa).

    Insira o ARN do ponto de acesso EFS

  6. Para anexar arquivos do Amazon S3, insira o ARN do ponto de acesso do S3 Files (e seu caminho de montagem).

    Insira o ARN do ponto de acesso do S3 Files

Confirme o assistente e execute agentcore deploy para se inscrever.

Armazenamento da sessão

Os arquivos gravados no caminho de montagem persistem em todos stop/resume os ciclos quando você invoca com o mesmo. runtimeSessionId

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}'
AgentCore CLI
# At create time
agentcore create --name myagent --session-storage-mount-path /mnt/data/

# Or add to an existing harness
agentcore add harness --name my-agent --session-storage /mnt/data/
agentcore deploy

Ponto de acesso Amazon EFS

Anexe um ARN do ponto de acesso EFS em um caminho de montagem abaixo. /mnt Os dados persistem na sua conta e podem ser compartilhados com outros equipamentos ou tempos de execução de agentes que montam o mesmo ponto de acesso.

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "SharedToolsAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "efsAccessPoint": {
            "accessPointArn": "arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/efs"
          }
        }
      ]
    }
  }'
AgentCore CLI

Conecte um ponto de acesso EFS com --efs-access-point as<accessPointArn>:<mountPath>. O EFS requer o modo de rede VPC:

agentcore add harness --name shared-tools-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --efs-access-point arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0:/mnt/efs
agentcore deploy
nota

O caminho de montagem deve estar embaixo/mnt. O sinalizador é repetível (até 2 montagens EFS); --network-mode VPC com --subnets e --security-groups é necessário para montagens de arquivos EFS e S3.

Ponto de acesso ao Amazon S3 Files

Anexe um ARN do ponto de acesso do S3 Files em um caminho de montagem abaixo. /mnt Os arquivos no caminho de montagem são sincronizados bidirecionalmente com o bucket S3 de apoio.

exemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "DataAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "s3FilesAccessPoint": {
            "accessPointArn": "arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/s3data"
          }
        }
      ]
    }
  }'
AgentCore CLI

Anexe um ponto de acesso do S3 Files com --s3-access-point as<accessPointArn>:<mountPath>. O S3 Files requer o modo de rede VPC:

agentcore add harness --name data-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --s3-access-point arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0:/mnt/s3data
agentcore deploy
nota

O ARN do ponto de acesso em si contém dois pontos; o caminho de montagem é retirado do segmento após os dois pontos finais. O sinalizador é repetível (até 2 montagens de arquivos S3).

Importante

UpdateHarnesssubstitui a filesystemConfigurations lista inteira. Para adicionar uma nova montagem a um chicote que já tenha sistemas de arquivos configurados, chame GetHarness primeiro e, em seguida, envie a lista completa desejada (entradas existentes mais a nova). UpdateHarness

Saiba mais: Configurações do sistema de arquivos para o AgentCore Runtime.

Tópicos relacionados