Gunakan model apa pun, beralih di tengah sesi

Model dan instruksi

Tentukan harness sekali dengan default untuk model, prompt sistem, alat, memori, dan batas eksekusi. Ganti salah satu dari mereka pada satu pemanggilan saat Anda ingin bereksperimen. Sumber daya harness tetap tidak berubah; hanya panggilan itu yang menggunakan penggantian.

Ini adalah inti dari model berbasis konfigurasi: default pada waktu pembuatan, diganti pada waktu pemanggilan. Anda dapat menguji kombinasi model/prompt N/tool dalam waktu yang diperlukan untuk menerapkan kembali sekali.

contoh

AWS CLI/boto3

Defaultnya pada: create-harness


aws bedrock-agentcore-control create-harness \
  --harness-name "research-agent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --system-prompt '[{"text": "You are a research assistant."}]' \
  --tools '[{"type": "agentcore_browser", "name": "browser"}]'

Penggantian per pemanggilan:


response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    # These apply only to this call; the harness defaults stay intact
    model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-opus-4-5-20251101-v1:0"}},
    systemPrompt=[{"text": "You are a terse research assistant. One paragraph answers only."}],
    tools=[
        {"type": "agentcore_browser", "name": "browser"},
        {"type": "agentcore_code_interpreter", "name": "code_interpreter"},
    ],
    messages=[{"role": "user", "content": [{"text": "Summarize this paper as a bullet list."}]}],
)

Untuk mengubah default secara permanen, gunakanupdate-harness.

AgentCore CLI

Tetapkan default saat Anda membuat atau memperbarui harness:


# Create an empty project if one does not already exist
agentcore create --project-name ResearchAgentProject --no-agent
cd ResearchAgentProject

# Add a harness to the project
agentcore add harness \
  --name research-agent \
  --model-id us.anthropic.claude-sonnet-4-6 \
  --system-prompt "You are a research assistant." \
  --tools agentcore_browser

agentcore deploy

Mengganti pada pemanggilan:


# Switch the model for one call
agentcore invoke --harness research-agent \
  --model-id us.anthropic.claude-opus-4-5-20251101-v1:0 \
  "Summarize this research paper"

# Swap tools for one call
agentcore invoke --harness research-agent \
  --tools agentcore_browser,agentcore_code_interpreter \
  "Plot the citation counts as a bar chart"

Dapat diganti pada waktu pemanggilan:--model-id,,--tools,,--system-prompt,--max-iterations, --max-tokens--harness-timeout,--skills. --allowed-tools --actor-id Tambahkan --verbose untuk mencetak acara JSON streaming mentah untuk debugging.

Untuk mengubah default secara permanen, edit app/<name>/harness.json dan jalankanagentcore deploy.

Interactive

J agentcore alankan di direktori proyek untuk membuka TUI, pilih add, lalu pilih Harness. Wizard memandu Anda melalui konfigurasi model dan instruksi langkah demi langkah.

Pilih penyedia model Anda. Amazon Bedrock, OpenAI, Google Gemini, dan LiteLLM-compatible penyedia apa pun didukung, masing-masing dengan model default.
Pilih format API. Untuk Amazon Bedrock dan OpenAI, pilih Converse Stream (default), Respons, atau Penyelesaian Obrolan. Tanggapan dan Penyelesaian Obrolan dilayani oleh Bedrock Mantle.
Jika Anda memilih LiteLM, wizard meminta LiteLLM-specific kolom - kunci API opsional ARN, URL dasar API opsional untuk OpenAI-compatible gateway, dan parameter tambahan opsional yang diteruskan ke penyedia.

Lanjutkan melalui langkah-langkah yang tersisa (lingkungan, memori, pengaturan lanjutan) dan konfirmasikan. Kemudian jalankan agentcore deploy untuk menerapkan.

Gunakan model apa pun, beralih di tengah sesi

Gunakan model dari Amazon Bedrock, OpenAI, Google Gemini, atau penyedia lain melalui LiteLM, termasuk titik akhir. OpenAI-compatible Beralih penyedia di antara putaran sesi yang sama dan percakapan berlanjut. Konteks terbawa.

Jika Anda tidak menentukan model, harness default ke Claude Sonnet 4.6 Anthropic di Amazon Bedrock (global.anthropic.claude-sonnet-4-6) sehingga Anda dapat segera memulai. Anda dapat mengubah default atau mengganti per pemanggilan kapan saja.

Simpan kunci API pihak ketiga di AgentCore brankas token Identity sebagai penyedia kredensia kunci API. Harness menarik kunci pada waktu pemanggilan. Kode agen Anda tidak pernah melihat kredenSIAL mentah.

contoh

AWS CLI/boto3

Daftarkan kunci API dengan AgentCore Identitas:


aws bedrock-agentcore-control create-api-key-credential-provider \
  --name my-openai-key \
  --api-key "$OPENAI_API_KEY"

Ganti penyedia di seluruh putaran sesi yang sama:


# Turn 1: Bedrock (native Converse API)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={"bedrockModelConfig": {"modelId": "us.anthropic.claude-sonnet-4-5-20250514-v1:0"}},
    messages=[{"role": "user", "content": [{"text": "Analyze this codebase."}]}],
)

# Turn 2: Bedrock Mantle (OpenAI Responses format, no API key needed)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "bedrockModelConfig": {
            "modelId": "openai.gpt-4o",
            "apiFormat": "responses",
            "additionalParams": {"reasoning": {"effort": "high"}},
        }
    },
    messages=[{"role": "user", "content": [{"text": "Now suggest fixes for the top three issues."}]}],
)

# Turn 3: OpenAI model via Bedrock Mantle (no API key needed)
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "openAiModelConfig": {
            "modelId": "gpt-5.4",
            "apiFormat": "responses",
            "endpoint": {"bedrockMantle": {}},
        }
    },
    messages=[{"role": "user", "content": [{"text": "Summarize the fixes as a bullet list."}]}],
)

Tip

Gunakan openAiModelConfig dengan "endpoint": {"bedrockMantle": {}} untuk memanggil model OpenAI melalui Amazon Bedrock Mantle — tidak diperlukan kunci API, menggunakan kredentif peran eksekusi Anda. Gunakan openAiModelConfig dengan apiKeyArn saat memanggil titik akhir OpenAI secara langsung.

AgentCore CLI

Tambahkan kunci API ke AgentCore Identitas:


agentcore add credential --type api-key --name my-openai-key --api-key $OPENAI_API_KEY
agentcore deploy

Dari direktori AgentCore proyek yang Anda buat sebelumnya, tambahkan harness kedua yang menggunakan format Responses. Kemudian terapkan proyek:


agentcore add harness \
  --name my-agent \
  --model-provider bedrock \
  --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
  --api-format responses
agentcore deploy

Panggil dengan Bedrock Mantle:


SESSION_ID="$(uuidgen)"

# Turn 1: Bedrock Mantle (Responses format)
agentcore invoke --harness my-agent \
  --model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
  --session-id "$SESSION_ID" \
  "Analyze this codebase and identify performance bottlenecks."

Beralih ke OpenAI langsung pada sesi yang sama:


# Turn 2: OpenAI direct on the same session
agentcore invoke --harness my-agent \
  --model-provider open_ai \
  --model-id gpt-5.4 \
  --api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-openai-key \
  --session-id "$SESSION_ID" \
  "Now suggest fixes for the top three issues."

Pelajari lebih lanjut: AgentCore Identi tas, penyedia kredensia kunci API.

Pilih format API model

Konfigurasi model Amazon Bedrock dan OpenAI masing-masing menerima apiFormat bidang opsional yang memilih protokol API mana yang digunakan harness untuk memanggil model.

UntukbedrockModelConfig, apiFormat pilih protokol API dan titik akhir Amazon Bedrock yang dipanggil harness:

converse_stream- Amazon Bedrock Converse API, dilayani oleh titik akhirbedrock-runtime. Ini adalah opsi default.
responses- OpenAI-compatible Responses API, dilayani oleh titik bedrock-mantle akhir.
chat_completions- API Pen OpenAI-compatible yelesaian Obrolan, dilayani oleh titik akhirbedrock-mantle.

T bedrock-mantle itik akhir mendukung serangkaian model dan kemampuan yang berbeda dari titik bedrock-runtime akhir default. Untuk detailnya, lihat T itik Akhir yang didukung oleh Amazon Bed rock.

UntukopenAiModelConfig, apiFormat bisa menjadi salah satu dari:

responses- OpenAI Responses API. Ini adalah opsi default.
chat_completions- API Penyelesaian Obrolan OpenAI.

Kedua konfigurasi juga menerima additionalParams bidang opsional. Provider-specific parameter masuk additionalParams diteruskan ke penyedia model tidak berubah.

penting

Parameter dalam additionalParams dapat mengubah perilaku penyedia termasuk perutean titik akhir, penanganan kredensia, dan pemilihan wilayah. Jika aplikasi Anda meneruskan konfigurasi model yang disediakan pemanggil keInvokeHarness, validasi bidang ini sebelum pemanggilan. Lihat Model tanggung jawab bersama.

contoh

Terapkan Amazon Bedrock Guardrails

Gunakan Amazon Bedrock Guardrails untuk menyaring konten berbahaya atau memblokir topik yang ditolak dalam input dan output model. Untuk menerapkan pagar pembatas ke setiap permintaan model, tambahkan guardrailConfig objek ke. bedrockModelConfig.additionalParams Harness meneruskan objek ini ke Amazon Bedrock dengan setiap permintaan model.

Untuk menggunakan Amazon Bedrock Guardrails dengan harness, konfigurasikan bedrockModelConfig dengan format API. converse_stream Jika Anda menghilangkanapiFormat, harness menggunakan secara converse_stream default. Setel konfigurasi ini di CreateHarness atauUpdateHarness, atau ganti untuk satu panggilan masukInvokeHarness.

Contoh Python berikut memanggil InvokeHarness dengan konfigurasi pagar pembatas. Ganti HARNESS_ARN dengan harness ARN Anda dan SESSION_ID dengan ID sesi runtime yang unik.


import boto3

client = boto3.client("bedrock-agentcore")
response = client.invoke_harness(
    harnessArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    model={
        "bedrockModelConfig": {
            "modelId": "us.amazon.nova-micro-v1:0",
            "apiFormat": "converse_stream",
            "additionalParams": {
                "guardrailConfig": {
                    "guardrailIdentifier": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456",
                    "guardrailVersion": "1",
                    "trace": "enabled_full",
                }
            },
        }
    },
    messages=[{"role": "user", "content": [{"text": "Help me plan a trip."}]}],
)

Untuk izin model dasar, lihat kebijakan peran eksekusi. Tambahkan pernyataan JSON berikut ke kebijakan peran eksekusi harness:


{
  "Effect": "Allow",
  "Action": "bedrock:ApplyGuardrail",
  "Resource": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456"
}

Gunakan pagar pembatas di Wilayah yang sama AWS dengan permintaan model. Ketika pagar pembatas mengintervensi, aliran respons dilaporkan guardrail_intervened sebagai alasan berhenti.

Untuk informasi selengkapnya tentang bidang konfigurasi pagar pembatas, lihat Menggunakan pagar pembatas dengan API Converse. Untuk informasi selengkapnya tentang izin IAM, lihat Menyi apkan izin untuk menggunakan Amazon Bedrock Guardrails.

Gunakan model melalui LiteLM

Gunakan liteLlmModelConfig untuk menjangkau penyedia apa pun yang didukung LiteLM, termasuk OpenAI-compatible titik akhir. Setel modelId ke ID model prefiksasi penyedia LiteLM, seperti atau. gemini/gemini-2.5-pro anthropic/claude-sonnet-4-6

Penyedia yang mengotentikasi dengan kunci API (seperti Google atau Anthropic) memerlukan. apiKeyArn Model Amazon Bedrock yang diakses dengan bedrock/ awalan menggunakan izin peran eksekusi harness dan tidak memerlukan kunci API.

modelId(wajib) - ID model prefiksasi penyedia LiteLM.
apiKeyArn- ARN kunci API penyedia, disimpan di AgentCore Identity sebagai penyedia kredensia kunci API. Titik akhir harus menerima kunci API ini.
apiBase- URL titik akhir khusus untuk OpenAI-compatible gateway, seperti proxy atau titik akhir yang di-host sendiri.
additionalParams- Parameter khusus penyedia yang diteruskan ke LiteLM tidak berubah. Ini termasuk parameter yang dapat mengganti titik akhir (aws_bedrock_runtime_endpoint), mengasumsikan peran IAM (aws_role_name), atau mengubah perutean permintaan. Lihat Model tanggung jawab bersama.

liteLlmModelConfigjuga menerima topP bidang opsional maxTokenstemperature,, dan.

contoh

Saat harness Anda menggunakan penyedia kredensia kunci API, berikan izin peran eksekusi untuk membaca kunci. Lihat Kontrol keamanan dan akses.

Untuk informasi tambahan tentang konfigurasi harness, lihat Dokumentasi API

Topik terkait

Alat- sambungkan alat ke harness Anda
Memori- Pertahankan percakapan di seluruh sesi
Kontrol biaya dengan batas- menetapkan batas eksekusi dan strategi pemotongan

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Memulai

Alat

Model dan instruksi

contoh

Gunakan model apa pun, beralih di tengah sesi

contoh

Tip

Pilih format API model

penting

contoh

catatan

Terapkan Amazon Bedrock Guardrails

Gunakan model melalui LiteLM

contoh

catatan

Topik terkait