Utilisez n'importe quel modèle, changez en cours de session

Modèles et instructions

Définissez un harnais une fois avec les valeurs par défaut pour le modèle, l'invite système, les outils, la mémoire et les limites d'exécution. Remplacez n'importe laquelle de ces options lors d'une seule invocation lorsque vous souhaitez expérimenter. La ressource de harnais reste inchangée ; seul cet appel utilise les remplacements.

C'est le cœur du modèle basé sur la configuration : les valeurs par défaut au moment de la création, les remplacements au moment de l'invocation. Vous pouvez tester les combinaisons N model/prompt /tool pendant le temps qu'il faudrait pour effectuer un seul redéploiement.

Exemple

AWS CLI/boto3

La valeur par défaut est activée 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"}]'

Remplacements par invocation :


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

Pour modifier définitivement les valeurs par défaut, utilisezupdate-harness.

AgentCore CLI

Définissez les valeurs par défaut lorsque vous créez ou mettez à jour le harnais :


# 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

Annuler une invocation :


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

Remplaçable au moment de l'invocation :--model-id,--tools,,--system-prompt,--max-iterations,--max-tokens,--harness-timeout,--skills. --allowed-tools --actor-id Ajoutez --verbose pour imprimer des événements JSON en streaming bruts à des fins de débogage.

Pour modifier définitivement les valeurs par défaut, modifiez-les app/<name>/harness.json et exécutezagentcore deploy.

Interactive

Exécutez agentcore dans un répertoire de projet pour ouvrir le TUI, sélectionnez Ajouter, puis choisissez Harness. L'assistant vous guide étape par étape dans la configuration du modèle et des instructions.

Choisissez votre fournisseur de modèles. Amazon Bedrock, OpenAI, Google Gemini et tous les LiteLLM-compatible fournisseurs sont pris en charge, chacun avec un modèle par défaut.
Choisissez le format de l'API. Pour Amazon Bedrock et OpenAI, sélectionnez Converse Stream (par défaut), Responses ou Chat Completions. Les réponses et les réponses aux discussions sont assurées par Bedrock Mantle.
Si vous sélectionnez LiteLM, l'assistant vous invite à saisir les LiteLLM-specific champs suivants : un ARN de clé d'API facultatif, une URL de base d'API facultative pour les OpenAI-compatible passerelles et des paramètres supplémentaires facultatifs transmis au fournisseur.

Poursuivez les étapes restantes (environnement, mémoire, paramètres avancés) et confirmez. Exécutez ensuite agentcore deploy pour postuler.

Utilisez n'importe quel modèle, changez en cours de session

Utilisez des modèles d'Amazon Bedrock, d'OpenAI, de Google Gemini ou d'autres fournisseurs via LiteLLM, y compris des points de terminaison. OpenAI-compatible Changez de fournisseur entre les tours de la même session et la conversation se poursuit. Le contexte est conservé.

Si vous ne spécifiez pas de modèle, le harnais est défini par défaut sur Claude Sonnet 4.6 d'Anthropic sur Amazon Bedrock (global.anthropic.claude-sonnet-4-6) afin que vous puissiez commencer immédiatement. Vous pouvez modifier la valeur par défaut ou la remplacer par appel à tout moment.

Stockez des clés d'API tierces dans le coffre à jetons AgentCore d'Identity en tant que fournisseur d'informations d'identification de clés d'API. Le harnais tire sur la clé au moment de l'invocation. Votre code d'agent ne voit jamais les informations d'identification brutes.

Exemple

AWS CLI/boto3

Enregistrez une clé API auprès d'AgentCore Identity :


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

Changez de fournisseur à tour de rôle au cours de la même session :


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

Astuce

Utilisez openAiModelConfig with "endpoint": {"bedrockMantle": {}} pour appeler des modèles OpenAI via Amazon Bedrock Mantle. Aucune clé API n'est requise, utilise les informations d'identification de votre rôle d'exécution. À utiliser openAiModelConfig avec apiKeyArn lorsque vous appelez directement le point de terminaison OpenAI.

AgentCore CLI

Ajoutez une clé API à AgentCore Identity :


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

Dans le répertoire de AgentCore projet que vous avez créé précédemment, ajoutez un deuxième harnais utilisant le format Responses. Déployez ensuite le projet :


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

Invoquez avec 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."

Passez directement à OpenAI au cours de la même session :


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

En savoir plus : AgentCore Identité, fournisseurs d'informations d'identification clés d'API.

Sélectionnez le format de l'API du modèle

Les configurations des modèles Amazon Bedrock et OpenAI acceptent chacune un apiFormat champ facultatif qui sélectionne le protocole d'API utilisé par le harnais pour appeler le modèle.

PourbedrockModelConfig, apiFormat sélectionne à la fois le protocole API et le point de terminaison Amazon Bedrock que le harnais appelle :

converse_stream- l'API Amazon Bedrock Converse, desservie par le bedrock-runtime terminal. Il s’agit de l’option par défaut.
responses- l'API OpenAI-compatible Responses, servie par le bedrock-mantle terminal.
chat_completions- l'API OpenAI-compatible Chat Completions, desservie par le bedrock-mantle terminal.

Le bedrock-mantle point de terminaison prend en charge un ensemble de modèles et de fonctionnalités différent de celui du point de bedrock-runtime terminaison par défaut. Pour plus de détails, consultez la section Points de terminaison pris en charge par Amazon Bedrock.

CaropenAiModelConfig, apiFormat peut être l'un des suivants :

responses- l'API OpenAI Responses. Il s’agit de l’option par défaut.
chat_completions- l'API OpenAI Chat Completions.

Les deux configurations acceptent également un additionalParams champ facultatif. Provider-specific les paramètres in additionalParams sont transmis au fournisseur de modèles sans modification.

Important

Les paramètres saisis additionalParams peuvent modifier le comportement du fournisseur, notamment le routage des terminaux, la gestion des informations d'identification et la sélection des régions. Si votre application transmet la configuration du modèle fournie par l'appelant àInvokeHarness, validez ces champs avant l'invocation. Consultez Modèle de responsabilité partagée.

Exemple

Appliquez Amazon Bedrock Guardrails

Utilisez Amazon Bedrock Guardrails pour filtrer les contenus dangereux ou bloquer les sujets refusés dans les entrées et les sorties du modèle. Pour appliquer un garde-corps à chaque demande de modèle, ajoutez un guardrailConfig objet à. bedrockModelConfig.additionalParams Le harnais transmet cet objet à Amazon Bedrock à chaque demande de modèle.

Pour utiliser Amazon Bedrock Guardrails avec le harnais, configurez bedrockModelConfig avec le converse_stream format API. Si vous omettezapiFormat, le harnais l'utilise converse_stream par défaut. Définissez cette configuration dans CreateHarness ouUpdateHarness, ou redéfinissez-la pour un appel entrant. InvokeHarness

L'exemple Python suivant appelle InvokeHarness avec une configuration de garde-corps. Remplacez-le HARNESS_ARN par l'ARN de votre harnais et SESSION_ID par un identifiant de session d'exécution unique.


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

Pour les autorisations du modèle de base, consultez la politique relative aux rôles d'exécution. Ajoutez l'instruction JSON suivante à la politique de rôle d'exécution du harnais :


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

Utilisez un garde-corps dans la même AWS région que le modèle demandé. Lorsqu'un garde-corps intervient, le flux de réponse est indiqué guardrail_intervened comme motif d'arrêt.

Pour plus d'informations sur les champs de configuration du garde-corps, voir Utiliser un garde-corps avec l'API Converse. Pour plus d'informations sur les autorisations IAM, consultez la section Configuration des autorisations pour utiliser Amazon Bedrock Guardrails.

Utiliser un modèle via LiteLM

liteLlmModelConfigÀ utiliser pour contacter tous les fournisseurs pris en charge par LiteLM, y compris OpenAI-compatible les points de terminaison. Définissez un identifiant modelId de modèle LiteLLM préfixé par le fournisseur, tel que ou. gemini/gemini-2.5-pro anthropic/claude-sonnet-4-6

Les fournisseurs qui s'authentifient à l'aide d'une clé API (comme Google ou Anthropic) en ont besoin. apiKeyArn Les modèles Amazon Bedrock auxquels on accède par le bedrock/ préfixe utilisent les autorisations du rôle d'exécution du harnais et n'ont pas besoin de clé API.

modelId(obligatoire) - l'ID de modèle préfixé par le fournisseur LiteLM.
apiKeyArn- l'ARN de la clé API du fournisseur, stocké dans AgentCore Identity en tant que fournisseur d'informations d'identification de clé API. Le point de terminaison doit accepter cette clé d'API.
apiBase- une URL de point de terminaison personnalisée pour une OpenAI-compatible passerelle, telle qu'un proxy ou un point de terminaison auto-hébergé.
additionalParams- les paramètres spécifiques au fournisseur transmis à LiteLLM restent inchangés. Cela inclut les paramètres qui peuvent remplacer les points de terminaison (aws_bedrock_runtime_endpoint), assumer des rôles IAM (aws_role_name) ou modifier le routage des demandes. Consultez Modèle de responsabilité partagée.

liteLlmModelConfigaccepte également les topP champs temperature facultatifs maxTokens et.

Exemple

Lorsque votre harnais utilise un fournisseur d'informations d'identification de clé API, accordez au rôle d'exécution l'autorisation de lire la clé. Consultez Sécurité et contrôles d'accès.

Pour plus d'informations sur la configuration du harnais, consultez Documentation sur les API

Rubriques associées

Outils- connectez les outils à votre harnais
Mémoire- poursuivre les conversations d'une session à l'autre
Contrôlez les coûts avec des limites- définir des limites d'exécution et des stratégies de troncature

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Prise en main

Outils

Modèles et instructions

Exemple

Utilisez n'importe quel modèle, changez en cours de session

Exemple

Astuce

Sélectionnez le format de l'API du modèle

Important

Exemple

Note

Appliquez Amazon Bedrock Guardrails

Utiliser un modèle via LiteLM

Exemple

Note

Rubriques associées