View a markdown version of this page

Lingkungan dan sistem file - Batu Dasar Amazon AgentCore
Jalankan perintah di lingkunganLingkungan khusus (gambar kontainer)Variabel lingkunganSistem berkas

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Lingkungan dan sistem file

Setiap sesi harness berjalan di microVM terisolasi dengan sistem file dan shellnya sendiri. Halaman ini mencakup konfigurasi lingkungan eksekusi (wadah default atau kustom), menjalankan perintah langsung di VM, mengatur 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 deterministik atau pasca-pemanggilan.

  • 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 saat sesi dimulai (mis.apt-get install -y git) atau gunakan lingkungan Lingkungan khusus (gambar kontainer) khusus.

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

Lihat InvokeAgentRuntimeCommand API untuk detailnya.

catatan

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

Lingkungan khusus (gambar kontainer)

Lingkungan dasar termasuk Python dan bash, cukup untuk sebagian besar tugas. Ketika Anda membutuhkan lebih banyak, kemas kode sumber, dependensi, runtime, dan alat Anda ke dalam gambar wadah, dorong ke ECR, dan referensikan 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. Variabel perangkat lunak, sistem file, dan lingkungan yang Anda instal tersedia untuk agen; perintah startup container Anda tidak dijalankan. Jika Anda memerlukan proses latar belakang (seperti server dev), mulailah 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 lingkungan

Tetapkan variabel lingkungan yang diteruskan ke wadah runtime. Variabel lingkungan tersedia untuk agen dan wadah khusus apa pun yang berjalan dalam 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"
  }
}

Jalan agentcore deploy kan untuk mendaftar.

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.

  • Titik akses Amazon EFS - bawa sistem file EFS Anda sendiri, dibagikan di seluruh sesi dan agen. Diperlukan VPC.

  • Titik akses Amazon S3 Files - bawalah sistem file S3 Files Anda sendiri yang disinkronkan secara dua arah dengan bucket S3. Diperlukan VPC.

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

Konfigurasikan lingkungan dan sistem file di CLI AgentCore

contoh
Interactive

J agentcore alankan di direktori proyek untuk membuka TUI, pilih add, 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 pra-build (ECR URI) atau Dockerfile.

    Tambahkan wizard Harness: lingkungan khusus

  2. Pemasangan sistem file memerlukan mode VPC, jadi pada pengaturan lanjutan aktifkan Penyimpanan Jaringan dan Sistem File dengan Ruang, 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 pemasangan 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 S3 Files 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 samaruntimeSessionId.

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 dudukan EFS); --network-mode VPC dengan --subnets dan --security-groups diperlukan untuk pemasangan File EFS dan S3.

Titik akses File Amazon S3

Lampirkan titik akses S3 Files ARN di jalur pemasangan di bawah/mnt. File di jalur pemasangan disinkronkan 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 itu sendiri berisi titik dua; jalur pemasangan diambil dari segmen setelah titik dua terakhir. Bendera dapat diulang (hingga 2 File S3 dipasang).

penting

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

Pelajari lebih lanjut: Konfigurasi sistem file untuk AgentCore Runtime.

Topik terkait