# 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.
**Example**
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, utilisez`update-harness`.
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//harness.json` et `agentcore deploy` exécutez-les.
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.
1. 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.
1. 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.
1. 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) 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.
**Example**
Enregistrez une clé d'API avec [AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) :
```
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."}]}],
)
```
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.
Ajoutez une clé d'API à [AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) :
```
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é](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html), [fournisseurs d'identifiants clés d'API](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-api-key.html).
### 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.
Pour`bedrockModelConfig`, `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](https://docs.aws.amazon.com/bedrock/latest/userguide/endpoints.html).
Car`openAiModelConfig`, `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](harness-security.md#harness-shared-responsibility).
**Example**
Définissez le format de l'API lorsque vous créez ou mettez à jour le harnais avec le `--api-format` drapeau :
```
# Bedrock model through the OpenAI-compatible Responses API (bedrock-mantle endpoint)
agentcore add harness --name research-agent \
--model-provider bedrock \
--model-id us.anthropic.claude-sonnet-4-5-20250514-v1:0 \
--api-format responses
agentcore deploy
```
```
# OpenAI model using the Chat Completions API
agentcore add harness --name openai-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 \
--api-format chat_completions
agentcore deploy
```
`--api-format`accepte `converse_stream``responses`, ou `chat_completions` pour`--model-provider bedrock`, et `responses` ou `chat_completions` pour`--model-provider open_ai`. Elle ne s'applique pas à `gemini` ou`lite_llm`.
### 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 omettez`apiFormat`, 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\_ARN}}Remplacez-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](harness-security.md#harness-execution-role-policy). 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](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-use-converse-api.html) l'API Converse. Pour plus d'informations sur les autorisations IAM, consultez [Configurer les autorisations pour utiliser Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-permissions.html) Guardrails.
### Utiliser un modèle via LitellM
`liteLlmModelConfig`À utiliser pour contacter tous les fournisseurs pris en charge par [LitellM](https://docs.litellm.ai/), 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) 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](harness-security.md#harness-shared-responsibility).
`liteLlmModelConfig`accepte également les `topP` champs facultatifs `maxTokens``temperature`, et.
**Example**
Configurez un modèle LitellM :
```
response = client.invoke_harness(
harnessArn=HARNESS_ARN,
runtimeSessionId=SESSION_ID,
model={
"liteLlmModelConfig": {
"modelId": "gemini/gemini-2.5-pro",
"apiKeyArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gemini-key",
}
},
messages=[{"role": "user", "content": [{"text": "Summarize this paper."}]}],
)
```
Configurez un modèle LitellM avec : `--model-provider lite_llm`
```
agentcore add harness --name research-agent \
--model-provider lite_llm \
--model-id gemini/gemini-2.5-pro \
--api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gemini-key
agentcore deploy
```
Accédez à une OpenAI-compatible passerelle avec `--api-base` et transmettez les paramètres spécifiques au fournisseur avec : `--additional-params`
```
agentcore add harness --name proxy-agent \
--model-provider lite_llm \
--model-id openai/gpt-5.4 \
--api-base https://my-llm-gateway.example.com/v1 \
--api-key-arn arn:aws:bedrock-agentcore:us-west-2:123456789012:token-vault/default/apikeycredentialprovider/my-gateway-key \
--additional-params '{"timeout": 30}'
agentcore deploy
```
`--api-base`et `--additional-params` s'appliquent uniquement à`--model-provider lite_llm`. Les modèles Amazon Bedrock atteints avec le `bedrock/` préfixe utilisent les autorisations du rôle d'exécution et n'en ont pas besoin. `--api-key-arn`
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](harness-security.md).
Pour plus d'informations sur la configuration du harnais, consultez le [Documentation sur les API](harness-get-started.md#api-documentation)
#### Rubriques en relation
+ [Outils](harness-tools.md)- connectez les outils à votre harnais
+ [Mémoire](harness-memory.md)- poursuivre les conversations d'une session à l'autre
+ [Contrôlez les coûts avec des limites](harness-operations.md#harness-limits)- définir des limites d'exécution et des stratégies de troncature