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

Modèles et instructions

Définissez un harnais une seule 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 lequel d'entre eux lors d'un seul appel lorsque vous souhaitez expérimenter. La ressource du harnais reste inchangée ; seul cet appel utilise les dérogations.

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

Exemple

AWS CLI/boto3

Par défaut, c'est : 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"}]'

Dérogations 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 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

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

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

Pour modifier définitivement les paramètres par défaut, modifiez-les app/<name>/harness.json et agentcore deploy exécutez-les.

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 LiteLLM-compatible tous les 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 discussions terminées sont assurées par Bedrock Mantle.
Si vous sélectionnez LitelLM, 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.

Passez aux étapes restantes (environnement, mémoire, paramètres avancés) et confirmez. Exécutez ensuite agentcore deploy pour appliquer.

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

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

Si vous ne spécifiez aucun modèle, le harnais est configuré 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 annuler par appel à tout moment.

Stockez les 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 la clé au moment de l'invocation. Le code de votre agent ne voit jamais les informations d'identification brutes.

Exemple

AWS CLI/boto3

Enregistrez une clé d'API avec AgentCore Identity :


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

Changez de fournisseur au cours d'une 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é d'API n'est requise, utilise les informations d'identification de votre rôle d'exécution. openAiModelConfigÀ utiliser avec apiKeyArn lorsque vous appelez directement le point de terminaison OpenAI.

AgentCore CLI

Ajoutez une clé d'API à AgentCore Identity :


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

Invoquer avec Bedrock Mantle (format des réponses, aucune clé d'API requise) :


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

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'identifiants clés d'API.

Sélectionnez le format d'API du modèle

Les configurations des modèles Amazon Bedrock et OpenAI acceptent chacune un champ apiFormat 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 point de terminaison. bedrock-runtime Il s’agit de l’option par défaut.
responses- l'API OpenAI-compatible Responses, servie par le bedrock-mantle point de terminaison.
chat_completions- l'API OpenAI-compatible Chat Completions, servie par le bedrock-mantle point de terminaison.

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 Endpoints 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 additionalParams sont transmis au fournisseur de modèles tels quels.

Important

Les paramètres additionalParams peuvent modifier le comportement du fournisseur, notamment le routage des points de terminaison, le traitement 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'appel. Consultez Modèle de responsabilité partagée.

Exemple

Appliquer Amazon Bedrock Guardrails

Utilisez Amazon Bedrock Guardrails pour filtrer le contenu préjudiciable ou bloquer les sujets refusés dans les entrées et 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 est utilisé converse_stream par défaut. Définissez cette configuration dans CreateHarness ou UpdateHarness remplacez-la pour un appel entrant. InvokeHarness

L'exemple Python suivant appelle InvokeHarness avec une configuration de garde-corps. HARNESS_ARNRemplacez-le par l'ARN de votre harnais et SESSION_ID par un ID 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 indique la raison de guardrail_intervened l'arrêt.

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

Utiliser un modèle via LitellM

liteLlmModelConfigÀ utiliser pour contacter tous les fournisseurs pris en charge par LitellM, y compris OpenAI-compatible les terminaux. Défini modelId sur un identifiant 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é d'API (tels que Google ou Anthropic) ont besoin de. apiKeyArn Les modèles Amazon Bedrock accessibles avec le bedrock/ préfixe utilisent les autorisations du rôle d'exécution du harnais et n'ont pas besoin de clé d'API.

modelId(obligatoire) - l'ID de modèle préfixé par le fournisseur LitelLM.
apiKeyArn- l'ARN de la clé d'API du fournisseur, stocké dans AgentCore Identity en tant que fournisseur d'informations d'identification de clé d'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 sont 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 facultatifs maxTokenstemperature, et.

Exemple

Lorsque votre harnais utilise un fournisseur d'informations d'identification de clé d'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 le Documentation sur les API

Rubriques en relation

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 d'API du modèle

Important

Exemple

Note

Appliquer Amazon Bedrock Guardrails

Utiliser un modèle via LitellM

Exemple

Note

Rubriques en relation