# 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: **defaults at creation time, overrides at invocation time.** You can test N model/prompt/tool combinations in the time it would take to redeploy once.
**Example**
Defaults on `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"}]'
```
Overrides per 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."}]}],
)
```
To change defaults permanently, use `update-harness`.
Set defaults when you create or update the harness:
```
# 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
```
Override on an 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"
```
Overridable at invoke time: `--model-id`, `--tools`, `--system-prompt`, `--max-iterations`, `--max-tokens`, `--harness-timeout`, `--skills`, `--allowed-tools`, `--actor-id`. Add `--verbose` to print raw streaming JSON events for debugging.
To change defaults permanently, edit `app//harness.json` and run `agentcore deploy`.
Run `agentcore` in a project directory to open the TUI, select **add**, then choose **Harness** . The wizard walks you through model and instruction configuration step by step.
1. Choose your model provider. Amazon Bedrock, OpenAI, Google Gemini, and any LiteLLM-compatible provider are supported, each with a default model.
1. Choose the API format. For Amazon Bedrock and OpenAI, select **Converse Stream** (default), **Responses** , or **Chat Completions** . Responses and Chat Completions are served by Bedrock Mantle.
1. If you select **LiteLLM** , the wizard prompts for the LiteLLM-specific fields - an optional API key ARN, an optional API base URL for OpenAI-compatible gateways, and optional additional parameters passed through to the provider.
Continue through the remaining steps (environment, memory, advanced settings) and confirm. Then run `agentcore deploy` to apply.
## 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 don’t specify a model, the harness defaults to Anthropic’s Claude Sonnet 4.6 on Amazon Bedrock (`global.anthropic.claude-sonnet-4-6`) so you can get started immediately. You can change the default or override per invocation at any time.
Store third-party API keys in [AgentCore Identity’s](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) token vault as an API key credential provider. The harness pulls the key at invocation time. Your agent code never sees raw credentials.
**Example**
Register an API key with [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"
```
Switch providers across turns of the same 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."}]}],
)
```
Use `openAiModelConfig` with `"endpoint": {"bedrockMantle": {}}` to call OpenAI models through Amazon Bedrock Mantle — no API key required, uses your execution role credentials. Use `openAiModelConfig` with `apiKeyArn` when calling the OpenAI endpoint directly.
Add an API key to [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
```
Invoke with Bedrock Mantle (Responses format, no API key needed):
```
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."
```
Switch to OpenAI direct on the same 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."
```
Learn more: [AgentCore Identity](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html), [API key credential providers](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity-api-key.html).
### 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 the `bedrock-runtime` endpoint. This is the default.
+ `responses` - the OpenAI-compatible Responses API, served by the `bedrock-mantle` endpoint.
+ `chat_completions` - the OpenAI-compatible Chat Completions API, served by the `bedrock-mantle` endpoint.
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](https://docs.aws.amazon.com/bedrock/latest/userguide/endpoints.html).
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.
**Important**
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](harness-security.md#harness-shared-responsibility).
**Example**
Set the API format when you create or update the harness with the `--api-format` flag:
```
# 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` accepts `converse_stream`, `responses`, or `chat_completions` for `--model-provider bedrock`, and `responses` or `chat_completions` for `--model-provider open_ai`. It does not apply to `gemini` or `lite_llm`.
### Use a model through LiteLLM
Use `liteLlmModelConfig` to reach any provider that [LiteLLM](https://docs.litellm.ai/) supports, including OpenAI-compatible endpoints. Set `modelId` 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/identity.html) 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](harness-security.md#harness-shared-responsibility).
`liteLlmModelConfig` also accepts the optional `maxTokens`, `temperature`, and `topP` fields.
**Example**
Configure a LiteLLM model:
```
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."}]}],
)
```
Configure a LiteLLM model with `--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
```
Reach an OpenAI-compatible gateway with `--api-base`, and pass provider-specific parameters with `--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` and `--additional-params` apply only to `--model-provider lite_llm`. Amazon Bedrock models reached with the `bedrock/` prefix use the execution role’s permissions and don’t need `--api-key-arn`.
When your harness uses an API key credential provider, grant the execution role permission to read the key. See [Security and access controls](harness-security.md).
For additional information on harness configuration, see the [API Documentation](harness-get-started.md#api-documentation)
#### Related topics
+ [Tools](harness-tools.md) - connect tools to your harness
+ [Memory](harness-memory.md) - persist conversations across sessions
+ [Control cost with limits](harness-operations.md#harness-limits) - set execution limits and truncation strategies