Verwenden Sie ein beliebiges Modell und wechseln Sie während der Sitzung

Modelle und Anleitungen

Definieren Sie einmal einen Kabelbaum mit Standardeinstellungen für Modell, Systemprompt, Tools, Speicher und Ausführungslimits. Überschreiben Sie diese Werte bei einem einzigen Aufruf, wenn Sie experimentieren möchten. Die Harness-Ressource bleibt unverändert; nur dieser Aufruf verwendet die Overrides.

Dies ist der Kern des konfigurationsbasierten Modells: Standardwerte zum Zeitpunkt der Erstellung, Überschreibungen zum Zeitpunkt des Aufrufs. Sie können N- und model/prompt Tool-Kombinationen in der Zeit testen, die für eine erneute Bereitstellung erforderlich wäre.

Beispiel

AWS CLI/boto3

Die Standardeinstellung ist: 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"}]'

Überschreibungen pro Aufruf:


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."}]}],
)

Um die Standardeinstellungen dauerhaft zu ändern, verwenden Sie. update-harness

AgentCore CLI

Legen Sie beim Erstellen oder Aktualisieren des Kabelbaums die Standardeinstellungen fest:


# Create a project if one does not already exist.
agentcore create

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

agentcore deploy

Bei einem Aufruf überschreiben:


# 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,code-interpreter \
  "Plot the citation counts as a bar chart"

Zum Zeitpunkt des Aufrufs überschreibbar:--model-id,,,--tools,,--system-prompt,--max-iterations,--max-tokens,--harness-timeout. --skills --allowed-tools --actor-id Hinzufügen--verbose, um rohe Streaming-JSON-Ereignisse für das Debuggen zu drucken.

Um die Standardeinstellungen dauerhaft zu ändern, bearbeiten Sie sie app/<name>/harness.json und führen Sie sie aus. agentcore deploy

Interactive

Führen Sie das agentcore Programm in einem Projektverzeichnis aus, um die TUI zu öffnen, wählen Sie Hinzufügen und anschließend Harness aus. Der Assistent führt Sie Schritt für Schritt durch die Modell- und Befehlskonfiguration.

Wählen Sie Ihren Modellanbieter. Amazon Bedrock, OpenAI, Google Gemini und alle LiteLLM-compatible Anbieter werden unterstützt, jeweils mit einem Standardmodell.
Wählen Sie das API-Format. Wählen Sie für Amazon Bedrock und OpenAI Converse Stream (Standard), Responses oder Chat Completions aus. Antworten und Chat-Abschlüsse werden von Bedrock Mantle bereitgestellt.
Wenn Sie LiteLLM auswählen, fordert der Assistent zur Eingabe der LiteLLM-specific Felder auf: einen optionalen API-Schlüssel-ARN, eine optionale API-Basis-URL für OpenAI-compatible Gateways und optionale zusätzliche Parameter, die an den Anbieter weitergegeben werden.

Fahren Sie mit den verbleibenden Schritten fort (Umgebung, Speicher, erweiterte Einstellungen) und bestätigen Sie. Starten Sie dannagentcore deploy, um sich zu bewerben.

Verwenden Sie ein beliebiges Modell und wechseln Sie während der Sitzung

Verwenden Sie Modelle von Amazon Bedrock, OpenAI, Google Gemini oder anderen Anbietern über LitelLM, einschließlich Endpunkten. OpenAI-compatible Wechseln Sie zwischen den Runden derselben Sitzung zwischen den Anbietern und die Konversation wird fortgesetzt. Der Kontext wird übertragen.

Wenn Sie kein Modell angeben, ist der Kabelbaum standardmäßig auf Claude Sonnet 4.6 von Anthropic auf Amazon Bedrock (global.anthropic.claude-sonnet-4-6) eingestellt, sodass Sie sofort loslegen können. Sie können die Standardeinstellung jederzeit ändern oder sie pro Aufruf überschreiben.

Speichern Sie API-Schlüssel von Drittanbietern im Token-Tresor von AgentCore Identity als Anbieter von API-Schlüsselanmeldeinformationen. Der Kabelbaum zieht den Schlüssel zum Zeitpunkt des Aufrufs. Ihr Agentencode sieht niemals Rohdaten.

Beispiel

AWS CLI/boto3

Registrieren Sie einen API-Schlüssel bei AgentCore Identity:


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

Wechseln Sie während derselben Sitzung abwechselnd den Anbieter:


# 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."}]}],
)

Tipp

Verwenden Sie openAiModelConfig with"endpoint": {"bedrockMantle": {}}, um OpenAI-Modelle über Amazon Bedrock Mantle aufzurufen — kein API-Schlüssel erforderlich, verwendet Ihre Anmeldeinformationen für die Ausführungsrolle. Verwenden Sie openAiModelConfig withapiKeyArn, wenn Sie den OpenAI-Endpunkt direkt aufrufen.

AgentCore CLI

Fügen Sie einen API-Schlüssel zu AgentCore Identity hinzu:


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

Mit Bedrock Mantle aufrufen (Antwortformat, kein API-Schlüssel erforderlich):


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 \
  --api-format responses \
  --session-id "$SESSION_ID" \
  "Analyze this codebase and identify performance bottlenecks."

Wechseln Sie in derselben Sitzung zu OpenAI Direct:


# 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."

Erfahren Sie mehr: AgentCore Identität, API-Schlüsselanbieter für Anmeldeinformationen.

Wählen Sie das API-Modellformat aus

Die Modellkonfigurationen Amazon Bedrock und OpenAI akzeptieren jeweils ein optionales apiFormat Feld, das auswählt, welches API-Protokoll der Harness zum Aufrufen des Modells verwendet.

Für bedrockModelConfig apiFormat wählt sowohl das API-Protokoll als auch den Amazon Bedrock-Endpunkt aus, den der Harness aufruft:

converse_stream- die Amazon Bedrock Converse API, die vom Endpunkt bedient wird. bedrock-runtime Dies ist die Standardeinstellung.
responses- die OpenAI-compatible Responses API, die vom bedrock-mantle Endpunkt bereitgestellt wird.
chat_completions- die OpenAI-compatible Chat-Completions-API, die vom bedrock-mantle Endpunkt bereitgestellt wird.

Der bedrock-mantle Endpunkt unterstützt einen anderen Satz von Modellen und Funktionen als der bedrock-runtime Standardendpunkt. Einzelheiten finden Sie unter Von Amazon Bedrock unterstützte Endgeräte.

FüropenAiModelConfig, apiFormat kann einer der folgenden sein:

responses- die OpenAI Responses API. Dies ist die Standardeinstellung.
chat_completions- die OpenAI Chat Completions API.

Beide Konfigurationen akzeptieren auch ein optionales additionalParams Feld. Provider-specific additionalParamsDie eingegebenen Parameter werden unverändert an den Modellanbieter weitergegeben.

Wichtig

Die eingegebenen Parameter additionalParams können das Verhalten des Anbieters ändern, einschließlich Endpunkt-Routing, Verarbeitung von Anmeldeinformationen und Regionsauswahl. Wenn Ihre Anwendung die vom Anrufer bereitgestellte Modellkonfiguration an weiterleitetInvokeHarness, überprüfen Sie diese Felder vor dem Aufruf. Siehe Modell der geteilten Verantwortung.

Beispiel

Wenden Sie Amazon Bedrock Guardrails an

Verwenden Sie Amazon Bedrock Guardrails, um schädliche Inhalte zu filtern oder abgelehnte Themen in Modelleingaben und -ausgaben zu blockieren. Um jeder Modellanfrage eine Leitplanke zuzuweisen, fügen Sie ein Objekt hinzu. guardrailConfig bedrockModelConfig.additionalParams Der Kabelbaum leitet dieses Objekt bei jeder Modellanfrage an Amazon Bedrock weiter.

Um Amazon Bedrock Guardrails mit dem Kabelbaum zu verwenden, konfigurieren Sie es bedrockModelConfig mit dem converse_stream API-Format. Wenn Sie es weglassenapiFormat, verwendet der Kabelbaum standardmäßig. converse_stream Stellen Sie diese Konfiguration in CreateHarness oder einUpdateHarness, oder überschreiben Sie sie für einen Anruf inInvokeHarness.

Das folgende Python-Beispiel ruft InvokeHarness mit einer Guardrail-Konfiguration auf. HARNESS_ARNErsetzen Sie es durch Ihren Harness-ARN und SESSION_ID durch eine eindeutige Runtime-Sitzungs-ID.


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."}]}],
)

Die Berechtigungen für das Basismodell finden Sie in der Richtlinie für Ausführungsrollen. Fügen Sie der Richtlinie für die Harness-Ausführungsrolle die folgende JSON-Anweisung hinzu:


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

Verwenden Sie eine Leitplanke in derselben AWS Region wie die Modellanforderung. Wenn eine Leitplanke eingreift, meldet guardrail_intervened der Antwortstream den Grund für den Stopp.

Weitere Informationen zu Guardrail-Konfigurationsfeldern findest du unter Verwenden einer Guardrail mit der Converse-API. Weitere Informationen zu IAM-Berechtigungen finden Sie unter Berechtigungen für die Verwendung von Amazon Bedrock Guardrails einrichten.

Verwenden Sie ein Modell über LitelLM

Verwenden Sie diese liteLlmModelConfig Option, um jeden Anbieter zu erreichen, den LitelLM unterstützt, einschließlich Endpunkten. OpenAI-compatible Auf eine LiteLM-Modell-ID mit modelId dem Präfix eines LiteLM-Anbieters, z. B. oder, eingestellt. gemini/gemini-2.5-pro anthropic/claude-sonnet-4-6

Anbieter, die sich mit einem API-Schlüssel authentifizieren (wie Google oder Anthropic), benötigen. apiKeyArn Amazon Bedrock-Modelle, auf die mit dem bedrock/ Präfix zugegriffen wird, verwenden die Berechtigungen der Harness-Ausführungsrolle und benötigen keinen API-Schlüssel.

modelId(erforderlich) — die LiteLM-Modell-ID mit dem Präfix des Anbieters.
apiKeyArn- der ARN des API-Schlüssels des Anbieters, der in AgentCore Identity als Anbieter von API-Schlüsselanmeldedaten gespeichert ist. Der Endpunkt muss diesen API-Schlüssel akzeptieren.
apiBase- eine benutzerdefinierte Endpunkt-URL für ein OpenAI-compatible Gateway, z. B. einen Proxy oder einen selbst gehosteten Endpunkt.
additionalParams- Anbieterspezifische Parameter, die unverändert an LiteLLM weitergegeben werden. Dazu gehören Parameter, die Endpunkte (aws_bedrock_runtime_endpoint) überschreiben, IAM-Rollen (aws_role_name) annehmen oder die Weiterleitung von Anfragen ändern können. Siehe Modell der geteilten Verantwortung.

liteLlmModelConfigakzeptiert auch die optionalen Felder maxTokenstemperature, undtopP.

Beispiel

Wenn Ihr Harness einen API-Schlüsselanbieter für Anmeldeinformationen verwendet, gewähren Sie der Ausführungsrolle die Berechtigung, den Schlüssel zu lesen. Siehe Sicherheit und Zugriffskontrollen.

Weitere Informationen zur Harness-Konfiguration finden Sie im API-Dokumentation

Modelle und Anleitungen

Beispiel

Verwenden Sie ein beliebiges Modell und wechseln Sie während der Sitzung

Beispiel

Tipp

Wählen Sie das API-Modellformat aus

Wichtig

Beispiel

Anmerkung

Wenden Sie Amazon Bedrock Guardrails an

Verwenden Sie ein Modell über LitelLM

Beispiel

Anmerkung

Verwandte Themen