View a markdown version of this page

Ambiente e sistema de arquivos - Base da Amazônia AgentCore
Execute comandos no ambienteAmbiente personalizado (imagens de contêiner)Variáveis de ambienteSistema de arquivos

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

Ambiente e sistema de arquivos

Cada sessão de harness é 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 circuito do agente. InvokeAgentRuntimeCommandoferece acesso direto ao shell ao equipamento microVM: execução determinística de comandos 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 Ambiente personalizado (imagens de contêiner) 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) na 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, da mesma forma que o 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 referencie-a no equipamento. 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 do contêiner devem ser criadas para a linux/arm64 plataforma.

O chicote 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, a envia para o ECR e a conecta ao equipamento.

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 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 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 encerramento 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 gerenciado 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 do Amazon EFS — traga seu próprio sistema de arquivos EFS, compartilhado entre sessões e agentes. É necessário VPC.

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

Para ver os 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 arreios.

Configurar 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 (URI ECR) 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, ative o armazenamento na rede e no sistema de arquivos com espaço e pressione Enter.

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

  3. Escolha o modo de rede VPC e 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 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).

    Digite o ARN do ponto de acesso do S3 Files

Confirme o assistente e, em seguida, execute agentcore deploy para se inscrever.

Armazenamento de sessões

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

Conecte um ARN do ponto de acesso EFS em um caminho de montagem abaixo/mnt. Os dados persistem em 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 exige 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 abaixo/mnt. O sinalizador pode ser repetido (até 2 montagens EFS); --network-mode VPC com --subnets e --security-groups é necessário para montagens EFS e S3 Files.

Ponto de acesso do 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>. Os arquivos S3 exigem 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 próprio ARN do ponto de acesso contém dois pontos; o caminho de montagem é retirado do segmento após os dois pontos finais. O sinalizador pode ser repetido (até 2 montagens do S3 Files).

Importante

UpdateHarnesssubstitui a filesystemConfigurations lista inteira. Para adicionar uma nova montagem a um equipamento 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