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

AWS CLI/boto3

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.

AgentCore CLI

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/<name>/harness.json and run agentcore deploy.

Interactive

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.

Choose your model provider. Amazon Bedrock, OpenAI, Google Gemini, and any LiteLLM-compatible provider are supported, each with a default model.
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.
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 token vault as an API key credential provider. The harness pulls the key at invocation time. Your agent code never sees raw credentials.

Example

AWS CLI/boto3


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

Tip

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.

AgentCore CLI

Add an API key to AgentCore Identity:


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

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.

Example

Use a model through LiteLLM

Use liteLlmModelConfig to reach any provider that LiteLLM 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 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 additional information on harness configuration, see the API Documentation

Models and instructions

Example

Use any model, switch mid-session

Example

Tip

Select the model API format

Important

Example

Note

Use a model through LiteLLM

Example

Note

Related topics