View a markdown version of this page

Memulai - Batuan Dasar Amazon AgentCore
PrasyaratMemulaiDokumentasi APIFormat respons streaming

Memulai

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

Prasyarat

  • AWS kredensyal dikonfigurasi di salah satu wilayah yang didukung.

  • Untuk CLI: 20+ Node.js

  • Untuk SDK/boto3: Python 3.10+, boto3diinstal, 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"

Polling 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) - mengatur port server dev (default 8080)

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

Interactive

Instal AgentCore CLI:

npm install -g @aws/agentcore

Jalankan agentcore create 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. Konfigurasikan pengaturan lanjutan secara opsional (alat, autentikasi, jaringan, siklus hidup, batas, pemotongan, penyimpanan sesi):

    Buat wizard: pengaturan lanjutan

  7. Tinjau konfigurasi Anda dan konfirmasikan:

    Buat wizard: tinjau dan konfirmasi

Setelah konfirmasi, wizard merancah proyek Anda. Terapkan denganagentcore deploy, lalu panggil dengan. agentcore 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, memanfaatkan, dan memori atau kredenal apa pun yang dikonfigurasi dalam proyek Anda:

Menyebarkan kemajuan: pembuatan CloudFormation sumber daya

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

Agen inspektur: mengobrol dengan harness Anda

Perluas 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 pengenal 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 acara. Jenis acara utama adalah:

  • messageStart- awal pesan baru (termasukrole)

  • contentBlockStart- awal dari 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

stopReasonDalam messageStop menunjukkan mengapa agen berhenti:

  • end_turn- agen selesai secara normal

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

  • max_tokens- batas token per putaran model tercapai

  • max_iterations_exceeded- maxIterations batasnya tercapai

  • timeout_exceeded- timeoutSeconds batasnya tercapai

  • max_output_tokens_exceeded- maxTokens anggaran habis