Models and instructions
Define a harness once with defaults for model, system prompt, tools, memory, and execution limits. Override any of those on a single invocation when you want to experiment. The harness resource stays unchanged; only that call uses the overrides.
This is the core of the config-based model: reusable configuration on the harness, overrides at invocation time. You can test multiple model, prompt, and tool combinations without redeploying.
Example
Configure project model credentials
For a project Harness, the CLI can manage the model key alongside the Harness. Supply a key file or stdin when creating the project:
agentcore create --name OpenAIHarness \ --model-provider open_ai \ --api-key file://./openai-key.txt
Or add a Harness to an existing project and pipe the key to --api-key -:
printf '%s' "$OPENAI_API_KEY" | agentcore add harness \ --name openai \ --model '{"provider":"open_ai","modelId":"gpt-5.4"}' \ --api-key - agentcore deploy
The CLI declares a named project credential, stores the key in agentcore/.env.local, and writes apiKeyCredentialName in the Harness model configuration. At deployment, it creates the AgentCore Identity provider, resolves the reference to its ARN, and grants the generated Harness role access. Do not commit the local secret or key file.
To reuse a project credential that you declared with agentcore add credentials api-key, set apiKeyCredentialName to its logical name in --model. You do not need an earlier credential-only deployment or to copy a deployed ARN:
agentcore add harness \ --name shared_key \ --model '{"provider":"open_ai","modelId":"gpt-5.4","apiKeyCredentialName":"my-openai-key"}' agentcore deploy
An existing credential provider ARN remains supported through apiKeyArn. Choose one route: apiKeyArn, apiKeyCredentialName, or --api-key. --api-key cannot be combined with either reference in --model, and the two reference fields are mutually exclusive. Bedrock uses the execution role and does not accept a model API key.
Both flags and wizards reject inline secrets. The CLI flags accept files or stdin; the interactive wizard accepts a key file or a credential provider ARN, not stdin. apiKeyCredentialName is a CLI project extension, not a field to send directly to the service API. For imported execution roles, add the credential-read permissions to the role yourself. See Harness security.
Use any model, switch mid-session
Use models from Amazon Bedrock, OpenAI, Google Gemini, or other providers through LiteLLM, including OpenAI-compatible endpoints. Switch providers between turns of the same session and the conversation continues. Context carries over.
If you create a harness with the API or agentcore harness create and omit the model, the harness uses the service default: the current AgentCore recommended model for your partition. In commercial AWS Regions, that model is Anthropic’s Claude Opus 5 on Amazon Bedrock (global.anthropic.claude-opus-5). The service default can change. To keep a model fixed, set model on the harness.
The AgentCore CLI sets its own model for new projects. If you omit --model, agentcore add harness writes global.anthropic.claude-sonnet-5-5 to harness.yaml, so that harness uses Claude Sonnet 5.5 instead of the service default. The CLI’s create/add wizards prefill provider-specific model IDs: global.anthropic.claude-sonnet-5-5 for Bedrock, gpt-6.1-sol for OpenAI, gemini-3.8-flash for Gemini, and bedrock/global.anthropic.claude-sonnet-5-5 for LiteLLM. These CLI defaults don’t change the service default or guarantee model access. You can configure a model on the harness or override it per invocation at any time.
Automatic prompt caching
For supported Amazon Bedrock models that use the converse_stream API format, the harness automatically enables prompt caching for the system prompt, tool definitions, and conversation history. Repeated model calls can reuse eligible prompt prefixes when the system prompt, selected tools, and earlier conversation remain unchanged. On a cache hit, cached input tokens use the model’s cache-read price, which is lower than its regular input-token price. Creating a cache entry uses the model’s cache-write price.
If bedrockModelConfig.additionalParams contains an explicit cachePoint in system, messages, or toolConfig.tools, the harness passes that configuration through without adding managed cache points. For supported models, cache usage appears in the metadata stream event as cacheReadInputTokens and cacheWriteInputTokens under usage.
For model support, cache behavior, and pricing details, see Prompt caching for faster model inference.
Default instructions and context management
When you omit systemPrompt or truncation, the harness uses AgentCore’s current recommended instructions and context-management policy. These managed defaults can change as the harness improves. To keep either setting fixed, configure it explicitly on the harness or invocation.
You are an agent. Keep working until the task is fully resolved before ending your turn. Only stop to ask the user when you are blocked on a decision or information that is genuinely theirs to provide. # Acting - Once you have enough to act on, act. Do not ask for confirmation of steps you can verify yourself, and do not re-derive facts you have already established. - Explore before you change anything: understand the surrounding context and conventions, then make changes that fit them. - Treat a task as done only when you have verified it, not when it looks plausible. If you cannot verify, say so. # Tools - Prefer the dedicated tool for a job over improvising with a general one. - Independent tool calls can be issued together in a single turn; run them in parallel rather than serially. - A denied or failed tool call is information: adjust your approach, do not retry it verbatim. - `<system-reminder>` tags in messages and tool results are injected by the harness, not the user. # Safety - For actions that are hard to reverse or that reach outside the local environment, confirm first unless you have been explicitly told to proceed. Approval in one context does not carry to the next. - Report outcomes faithfully: if something fails, say so with the output; if you skipped a step, say that; when something is done and verified, state it plainly without hedging. # Context management When the conversation grows long, older turns may be summarized and large tool results moved out of the immediate context, with a way to retrieve them. Work as if the full history remains available; you do not need to wrap up early or hand off mid-task.
When you omit truncation, the harness summarizes older conversation turns using the current default summaryRatio of 0.3 and preserveRecentMessages value of 10. These defaults can change as the harness improves. Configure truncation explicitly when your workload requires a fixed context-management policy. See Context truncation.
Store third-party API keys
Store third-party API keys in AgentCore Identity’s token vault as an API key credential provider. The harness pulls the key at invocation time. Your agent code never sees raw credentials.
Example
Learn more: AgentCore Identity, API key credential providers.
Select the model API format
The Amazon Bedrock and OpenAI model configurations each accept an optional apiFormat field that selects which API protocol the harness uses to call the model.
For bedrockModelConfig, apiFormat selects both the API protocol and the Amazon Bedrock endpoint the harness calls:
-
converse_stream- the Amazon Bedrock Converse API, served by thebedrock-runtimeendpoint. This is the default. -
responses- the OpenAI-compatible Responses API, served by thebedrock-mantleendpoint. -
chat_completions- the OpenAI-compatible Chat Completions API, served by thebedrock-mantleendpoint.
The bedrock-mantle endpoint supports a different set of models and capabilities than the default bedrock-runtime endpoint. For details, see Endpoints supported by Amazon Bedrock.
For openAiModelConfig, apiFormat can be one of:
-
responses- the OpenAI Responses API. This is the default. -
chat_completions- the OpenAI Chat Completions API.
Both configurations also accept an optional additionalParams field. Provider-specific parameters in additionalParams are passed through to the model provider unchanged.
Parameters in additionalParams can alter provider behavior including endpoint routing, credential handling, and region selection. If your application forwards caller-supplied model configuration to InvokeHarness, validate these fields before invocation. See Shared responsibility model.
Example
Apply Amazon Bedrock Guardrails
Use Amazon Bedrock Guardrails to filter harmful content or block denied topics in model inputs and outputs. To apply a guardrail to each model request, add a guardrailConfig object to bedrockModelConfig.additionalParams. The harness passes this object to Amazon Bedrock with each model request.
To use Amazon Bedrock Guardrails with the harness, configure bedrockModelConfig with the converse_stream API format. If you omit apiFormat, the harness uses converse_stream by default. Set this configuration in CreateHarness or UpdateHarness, or override it for one call in InvokeHarness.
The following Python example calls InvokeHarness with a guardrail configuration. Replace HARNESS_ARN with your harness ARN and SESSION_ID with a unique runtime session 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."}]}], )
For the baseline model permissions, see the execution role policy. Add the following JSON statement to the harness execution role policy:
{ "Effect": "Allow", "Action": "bedrock:ApplyGuardrail", "Resource": "arn:aws:bedrock:us-west-2:111122223333:guardrail/abc123def456" }
Use a guardrail in the same AWS Region as the model request. When a guardrail intervenes, the response stream reports guardrail_intervened as the stop reason.
For more information about guardrail configuration fields, see Use a guardrail with the Converse API. For more information about IAM permissions, see Set up permissions to use Amazon Bedrock Guardrails.
Use a model through LiteLLM
Use liteLlmModelConfig to reach any provider that LiteLLMmodelId to a LiteLLM provider-prefixed model ID, such as gemini/gemini-2.5-pro or anthropic/claude-sonnet-4-6.
Providers that authenticate with an API key (such as Google or Anthropic) require apiKeyArn. Amazon Bedrock models accessed with the bedrock/ prefix use the harness execution role’s permissions and don’t need an API key.
-
modelId(required) - the LiteLLM provider-prefixed model ID. -
apiKeyArn- the ARN of the provider’s API key, stored in AgentCore Identity as an API key credential provider. The endpoint must accept this API key. -
apiBase- a custom endpoint URL for an OpenAI-compatible gateway, such as a proxy or self-hosted endpoint. -
additionalParams- provider-specific parameters passed through to LiteLLM unchanged. This includes parameters that can override endpoints (aws_bedrock_runtime_endpoint), assume IAM roles (aws_role_name), or alter request routing. See Shared responsibility model.
liteLlmModelConfig also accepts the optional maxTokens, temperature, and topP fields.
Example
When your harness uses an API key credential provider, grant the execution role permission to read the key. See Security and access controls.
For more information about harness configuration, see API Documentation.
Related topics
-
Tools - connect tools to your harness
-
Memory - persist conversations across sessions
-
Control cost with limits - set execution limits and truncation strategies