View a markdown version of this page

Lingkungan dan sistem file - Batuan Dasar Amazon AgentCore
Jalankan perintah di lingkunganLingkungan kustom (gambar kontainer)Variabel-variabel lingkunganSistem berkas

Lingkungan dan sistem file

Setiap sesi harness berjalan dalam microVM terisolasi dengan sistem file dan cangkangnya sendiri. Halaman ini mencakup konfigurasi lingkungan eksekusi (default atau custom container), menjalankan perintah langsung pada VM, menyetel variabel lingkungan, dan memasang sistem file persisten.

Jalankan perintah di lingkungan

Tidak semuanya harus melalui loop agen. InvokeAgentRuntimeCommandmemberi Anda akses shell langsung ke harness microVM: eksekusi perintah deterministik tanpa penalaran model, tanpa biaya token, tanpa ambiguitas.

Gunakan untuk:

  • Jalankan skrip pra-pemanggilan atau pasca-pemanggilan deterministik.

  • Siapkan lingkungan sebelum pemanggilan: kloning repo, instal dependensi, salin file input.

  • Bertindak berdasarkan apa yang dihasilkan agen: jalankan tes, komit dan dorong, ekstrak artefak build.

  • Periksa VM selama pengembangan:ls,, catenv, python --version tanpa perjalanan pulang pergi melalui model.

contoh
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"
catatan

Lingkungan dasar termasuk Python dan bash. Untuk alat sepertigit,node, atau runtime lainnya, instal di awal sesi (misalnyaapt-get install -y git) atau gunakan lingkungan khusus.

Di TUI, tekan ! untuk masuk ke mode exec dan jalankan perintah sebaris.

Lihat InvokeAgentRuntimeCommand API untuk detailnya.

catatan

Perintah berjalan sebagai root (uid 0) dalam microVM. Ini analog dengan root pada instance EC2 Anda sendiri - izin IAM adalah gerbang akses, bukan tingkat hak istimewa in-VM. Jika Dockerfile Anda menyertakan USER arahan, itu hanya berlaku untuk proses agen (titik masuk utama wadah). InvokeAgentRuntimeCommandberjalan pada tingkat hak istimewa yang lebih tinggi untuk tujuan operasional, mirip dengan cara docker exec default melakukan root bahkan ketika container berjalan sebagai pengguna non-root. Lihat Menjalankan perintah shell dalam sesi AgentCore Runtime untuk detail selengkapnya tentang keamanan, penanganan kesalahan, dan praktik terbaik.

Lingkungan kustom (gambar kontainer)

Lingkungan dasar termasuk Python dan bash, cukup untuk sebagian besar tugas. Saat Anda membutuhkan lebih banyak, paketkan kode sumber, dependensi, runtime, dan alat Anda ke dalam gambar kontainer, dorong ke ECR, dan rujuk pada harness. Agen Anda berjalan di lingkungan yang tepat. Pasangkan gambar khusus dengan InvokeAgentRuntimeCommand pengaturan khusus sesi yang bervariasi per pemanggilan.

Gambar kontainer harus dibuat untuk linux/arm64 platform.

Harness menggantikan wadah Anda ENTRYPOINT dan CMD membuatnya tetap berjalan sebagai lingkungan. Perangkat lunak, sistem file, dan variabel lingkungan yang diinstal tersedia untuk agen; perintah startup container Anda tidak dijalankan. Jika Anda memerlukan proses latar belakang (seperti server dev), mulailah melalui InvokeAgentRuntimeCommand setelah sesi dimulai.

contoh
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."}]'

Peran eksekusi membutuhkan izin tarik ECR. Lihat kebijakan peran eksekusi untuk detailnya.

AgentCore CLI

Perancah harness dengan Dockerfile:

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

Saat penerapan, CLI membangun gambar, mendorong ke ECR, dan menempelkannya ke harness.

Atau referensi gambar yang sudah dibuat sebelumnya:

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

Variabel-variabel lingkungan

Tetapkan variabel lingkungan yang diteruskan ke wadah runtime. Variabel lingkungan tersedia untuk agen dan wadah khusus apa pun yang berjalan di sesi.

contoh
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

Tetapkan variabel lingkungan diharness.json:

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

Jalankan agentcore deploy untuk melamar.

Sistem berkas

Harness memasang penyimpanan persisten di jalur yang Anda tentukan. File yang ditulis ke mount ini bertahan dari penghentian sesi dan terlihat oleh pemanggilan selanjutnya.

Harness mendukung tiga jenis sistem file:

  • Penyimpanan sesi - penyimpanan per sesi yang dikelola layanan yang bertahan di seluruh stop/resume siklus untuk hal yang sama. runtimeSessionId Tidak diperlukan VPC.

  • Jalur akses Amazon EFS - membawa sistem file EFS Anda sendiri, dibagikan di seluruh sesi dan agen. VPC diperlukan.

  • Jalur akses File Amazon S3 - membawa sistem file File S3 Anda sendiri yang disinkronkan secara dua arah dengan bucket S3. VPC diperlukan.

Untuk prasyarat (jaringan VPC, izin IAM, grup keamanan), perbandingan jenis, batasan, dan perilaku siklus hidup, lihat Konfigurasi sistem berkas untuk Runtime. AgentCore Persyaratan yang sama berlaku untuk harness.

Konfigurasikan lingkungan dan sistem file di CLI AgentCore

contoh
Interactive

Jalankan agentcore di direktori proyek untuk membuka TUI, pilih tambah, lalu pilih Harness. Wizard memandu Anda melalui lingkungan eksekusi dan, dalam pengaturan lanjutan, sistem file persisten.

  1. Pada langkah Custom environment, pertahankan lingkungan default atau pilih image container pre-built (ECR URI) atau Dockerfile.

    Tambahkan panduan Harness: lingkungan khusus

  2. Pemasangan sistem file memerlukan mode VPC, jadi pada Pengaturan lanjutan aktifkan Penyimpanan Jaringan dan Sistem File dengan Spasi, lalu tekan Enter.

    Pengaturan lanjutan dengan Jaringan dan Penyimpanan Sistem File diaktifkan

  3. Pilih mode jaringan VPC, lalu berikan subnet dan grup keamanan untuk harness.

    Pilih mode jaringan VPC

  4. Atur jalur pemasangan penyimpanan sesi (di bawah/mnt).

    Masukkan jalur pemasangan penyimpanan sesi

  5. Untuk melampirkan sistem file Amazon EFS, masukkan titik akses EFS ARN (dan jalur pemasangannya pada langkah berikutnya).

    Masukkan titik akses EFS ARN

  6. Untuk melampirkan File Amazon S3, masukkan titik akses File S3 ARN (dan jalur pemasangannya).

    Masukkan titik akses File S3 ARN

Konfirmasikan wizard, lalu jalankan agentcore deploy untuk menerapkan.

Penyimpanan sesi

File yang ditulis ke jalur pemasangan tetap ada di seluruh stop/resume siklus saat Anda memanggil dengan yang sama. runtimeSessionId

contoh
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

Titik akses Amazon EFS

Pasang titik akses EFS ARN di jalur pemasangan di bawah. /mnt Data tetap ada di akun Anda dan dapat dibagikan dengan harness lain atau runtime agen yang memasang titik akses yang sama.

contoh
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

Lampirkan titik akses EFS dengan --efs-access-point as<accessPointArn>:<mountPath>. EFS membutuhkan mode jaringan 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
catatan

Jalur pemasangan harus di bawah/mnt. Bendera dapat diulang (hingga 2 pemasangan EFS); --network-mode VPC dengan --subnets dan --security-groups diperlukan untuk pemasangan EFS dan S3 Files.

Titik akses File Amazon S3

Lampirkan titik akses File S3 ARN di jalur pemasangan di bawah. /mnt File di jalur pemasangan disinkronkan secara dua arah dengan bucket S3 pendukung.

contoh
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

Lampirkan titik akses File S3 dengan --s3-access-point as<accessPointArn>:<mountPath>. File S3 membutuhkan mode jaringan 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
catatan

Titik akses ARN sendiri berisi titik dua; jalur pemasangan diambil dari segmen setelah titik dua terakhir. Bendera dapat diulang (hingga 2 pemasangan File S3).

penting

UpdateHarnessmenggantikan seluruh filesystemConfigurations daftar. Untuk menambahkan mount baru ke harness yang sudah memiliki sistem file yang dikonfigurasi, panggil GetHarness terlebih dahulu, lalu kirim daftar lengkap yang diinginkan (entri yang ada ditambah yang baru) masuk. UpdateHarness

Pelajari lebih lanjut: Konfigurasi sistem file untuk AgentCore Runtime.

Topik terkait