View a markdown version of this page

Memulai - Batu Dasar Amazon AgentCore
PrasyaratMemulaiDokumentasi APIFormat respons streaming

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

Memulai

Anda dapat menggunakan harness melalui AgentCore CLI atau langsung dengan AWS SDK seperti. boto3 CLI adalah jalur tercepat bagi sebagian besar pengembang; SDK adalah untuk penggunaan terprogram dari aplikasi Anda sendiri.

Prasyarat

  • AWS kredenSIAL dikonfigurasi di salah satu wilayah yang didukung.

  • Untuk CLI: 20+ Node.js

  • Untuk SDK/boto3: Python 3.10+, boto3 diinstal, dan peran eksekusi IAM yang dapat diasumsikan oleh harness. Lihat kebijakan peran eksekusi untuk izin minimum.

Memulai

contoh
AWS CLI/boto3

Buat harness dengan nama dan peran eksekusi:

aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"

Jajak pendapat get-harness sampai"status": "READY". Catat arn dalam respons.

aws bedrock-agentcore-control get-harness \
  --harness-id "MyHarness-XyZ123"

Memanggil dari Python. Jika Anda tidak menentukan model, harness default ke Anthropic Claude Sonnet 4.6 di Amazon Bedrock:

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = client.invoke_harness(
    harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123",  # Replace with your harness ARN
    runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",
    messages=[{
        "role": "user",
        "content": [{"text": "Research three tropical vacation options under $3k."}]
    }],
)

for event in response["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"].get("delta", {})
        if "text" in delta:
            print(delta["text"], end="", flush=True)
    elif "runtimeClientError" in event:
        print(f"\nError: {event['runtimeClientError']['message']}")
AgentCore CLI

Instal AgentCore CLI:

npm install -g @aws/agentcore

Buat proyek harness secara non-interaktif dengan flag:

agentcore create --name myresearchagent --model-provider bedrock

Menyebarkan dan memanggil:

agentcore deploy
agentcore invoke --harness myresearchagent \
  --session-id "$(uuidgen)" \
  "Research three tropical vacation options under $3k, within five hours of NYC."

Respons mengalir ke terminal Anda. Gunakan kembali yang sama --session-id di seluruh pemanggilan untuk melanjutkan percakapan di lingkungan yang sama.

Untuk menambahkan lebih banyak harness ke proyek yang ada, gunakanagentcore add harness. Untuk menghasilkan skrip pemanggilan Python mandiri, tambahkan--with-invoke-script.

Bendera yang berguna:

  • --no-browser(-b) - gunakan terminal TUI alih-alih inspektur browser

  • --logs(-l) - jalankan dalam mode non-interaktif dengan log ke stdout

  • --port <port>(-p) - atur port server dev (default 8080)

  • --no-traces- nonaktifkan koleksi jejak OTEL lokal

Interactive

Instal AgentCore CLI:

npm install -g @aws/agentcore

Jalan agentcore create kan tanpa bendera untuk meluncurkan wizard interaktif:

agentcore create

  1. Masukkan nama proyek Anda:

    Buat wizard: masukkan nama proyek

  2. Pilih Harness sebagai jenis proyek:

    Buat wizard: pilih jenis proyek

  3. Pilih penyedia model Anda:

    Buat wizard: pilih penyedia model

  4. Pilih lingkungan Anda (default, URI kontainer, atau Dockerfile):

    Buat wizard: pilih lingkungan

  5. Konfigurasikan memori:

    Buat wizard: konfigurasikan memori

  6. Secara opsional mengkonfigurasi pengaturan lanjutan (alat, autentikasi, jaringan, siklus hidup, batas, pemotongan, penyimpanan sesi):

    Buat wizard: pengaturan lanjutan

  7. Tinjau konfigurasi Anda dan konfirmasikan:

    Buat wizard: tinjau dan konfirmasikan

Setelah konfirmasi, penyihir memancar proyek Anda. Terapkan denganagentcore deploy, lalu panggil denganagentcore invoke.

Periksa status proyek kapan saja denganagentcore status:

AgentCore dasbor status

  1. Pembangunan lokal

Jika Anda ingin menguji harness di lingkungan lokal Anda, Anda dapat menjalankan server dev:

agentcore dev

Saat Anda menjalankanagentcore dev, CLI pertama-tama menyebarkan sumber daya harness Anda ke AWS, membuat peran IAM, harness, dan memori atau kredenSIAL apa pun yang dikonfigurasi dalam proyek Anda:

Menyebarkan kemajuan: pembuatan CloudFormation sumber daya

Setelah penerapan selesai, itu memulai server lokal dan membuka inspektur agen di browser Anda tempat Anda dapat mengobrol dengan harness, memeriksa jejak, dan menelusuri sumber daya proyek:

Inspektur agen: mengobrol dengan harness Anda

Per luas Pengaturan Harness untuk melihat dan mengganti konfigurasi harness untuk sesi saat ini:

Inspektur agen: pengaturan dan konfigurasi harness

Hanya itu yang Anda butuhkan untuk menjalankan harness. Bagian berikut mencakup semua yang dapat Anda konfigurasi.

catatan

Setidaknya runtimeSessionId harus 33 karakter. Gunakan UUID atau pengidentifikasi serupa. Gunakan kembali ID sesi yang sama di seluruh pemanggilan untuk melanjutkan percakapan di lingkungan yang sama.

Dokumentasi API

Untuk detail tambahan, lihat Referensi API:

Format respons streaming

InvokeHarnessmengembalikan aliran peristiwa. Jenis acara utama adalah:

  • messageStart- awal pesan baru (termasukrole)

  • contentBlockStart- awal blok konten (teks,toolUse, atautoolResult)

  • contentBlockDelta- konten tambahan (text, toolUse masukan,reasoningContent)

  • contentBlockStop- akhir dari blok konten

  • messageStop- akhir pesan (termasukstopReason)

  • metadata- penggunaan token dan metrik latensi

  • runtimeClientError- kesalahan selama eksekusi

Di stopReason dalam messageStop menunjukkan mengapa agen berhenti:

  • end_turn- agen selesai secara normal

  • tool_use- agen memanggil fungsi sebaris dan menunggu hasil sisi klien

  • max_tokens- batas token per putaran model tercapai

  • max_iterations_exceeded- bat maxIterations asnya tercapai

  • timeout_exceeded- bat timeoutSeconds asnya tercapai

  • max_output_tokens_exceeded- maxTokens anggaran habis