2026/04/22 - Amazon Bedrock AgentCore - 1 new api methods
Changes Adds support for Amazon Bedrock AgentCore Harness data plane APIs, enabling customers to invoke managed agent loops and execute commands on live agent sessions with streaming responses.
Operation to invoke a Harness.
See also: AWS API Documentation
Request Syntax
client.invoke_harness(
harnessArn='string',
runtimeSessionId='string',
messages=[
{
'role': 'user'|'assistant',
'content': [
{
'text': 'string',
'toolUse': {
'name': 'string',
'toolUseId': 'string',
'input': {...}|[...]|123|123.4|'string'|True|None,
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use',
'serverName': 'string'
},
'toolResult': {
'toolUseId': 'string',
'content': [
{
'text': 'string',
'json': {...}|[...]|123|123.4|'string'|True|None
},
],
'status': 'success'|'error',
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use'
},
'reasoningContent': {
'reasoningText': {
'text': 'string',
'signature': 'string'
},
'redactedContent': b'bytes'
}
},
]
},
],
model={
'bedrockModelConfig': {
'modelId': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...
},
'openAiModelConfig': {
'modelId': 'string',
'apiKeyArn': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...
},
'geminiModelConfig': {
'modelId': 'string',
'apiKeyArn': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...,
'topK': 123
}
},
systemPrompt=[
{
'text': 'string'
},
],
tools=[
{
'type': 'remote_mcp'|'agentcore_browser'|'agentcore_gateway'|'inline_function'|'agentcore_code_interpreter',
'name': 'string',
'config': {
'remoteMcp': {
'url': 'string',
'headers': {
'string': 'string'
}
},
'agentCoreBrowser': {
'browserArn': 'string'
},
'agentCoreGateway': {
'gatewayArn': 'string',
'outboundAuth': {
'awsIam': {}
,
'none': {}
,
'oauth': {
'providerArn': 'string',
'scopes': [
'string',
],
'customParameters': {
'string': 'string'
},
'grantType': 'CLIENT_CREDENTIALS'|'AUTHORIZATION_CODE',
'defaultReturnUrl': 'string'
}
}
},
'inlineFunction': {
'description': 'string',
'inputSchema': {...}|[...]|123|123.4|'string'|True|None
},
'agentCoreCodeInterpreter': {
'codeInterpreterArn': 'string'
}
}
},
],
skills=[
{
'path': 'string'
},
],
allowedTools=[
'string',
],
maxIterations=123,
maxTokens=123,
timeoutSeconds=123,
actorId='string'
)
string
[REQUIRED]
The ARN of the harness to invoke.
string
[REQUIRED]
The session ID for the invocation. Use the same session ID across requests to continue a conversation.
list
[REQUIRED]
The messages to send to the agent.
(dict) --
A message in the conversation.
role (string) -- [REQUIRED]
The role of the message sender.
content (list) -- [REQUIRED]
The content blocks of the message.
(dict) --
A content block within a message.
text (string) --
Text content.
toolUse (dict) --
A tool use request from the model.
name (string) -- [REQUIRED]
The name of the tool to call.
toolUseId (string) -- [REQUIRED]
The unique ID of this tool use.
input (:ref:`document<document>`) -- [REQUIRED]
The JSON input to pass to the tool.
type (string) --
The type of tool use.
serverName (string) --
The name of the MCP server providing this tool.
toolResult (dict) --
A tool execution result.
toolUseId (string) -- [REQUIRED]
The tool use ID that this result corresponds to.
content (list) -- [REQUIRED]
The content of the tool result.
(dict) --
A content block within a tool result.
text (string) --
Text content.
json (:ref:`document<document>`) --
JSON content.
status (string) --
The status of the tool execution.
type (string) --
The type of tool use that produced this result.
reasoningContent (dict) --
Model reasoning content.
reasoningText (dict) --
The reasoning text.
text (string) -- [REQUIRED]
The reasoning text.
signature (string) --
Signature for verifying the reasoning content.
redactedContent (bytes) --
Redacted reasoning content.
dict
The model configuration to use for this invocation. If specified, overrides the harness default.
bedrockModelConfig (dict) --
Configuration for an Amazon Bedrock model.
modelId (string) -- [REQUIRED]
The Bedrock model ID.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
openAiModelConfig (dict) --
Configuration for an OpenAI model.
modelId (string) -- [REQUIRED]
The OpenAI model ID.
apiKeyArn (string) -- [REQUIRED]
The ARN of your OpenAI API key on AgentCore Identity.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
geminiModelConfig (dict) --
Configuration for a Google Gemini model.
modelId (string) -- [REQUIRED]
The Gemini model ID.
apiKeyArn (string) -- [REQUIRED]
The ARN of your Gemini API key on AgentCore Identity.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
topK (integer) --
The topK set when calling the model.
list
The system prompt to use for this invocation. If specified, overrides the harness default.
(dict) --
A content block in the system prompt.
text (string) --
The text content of the system prompt block.
list
The tools available to the agent for this invocation. If specified, overrides the harness default.
(dict) --
A tool available to the agent loop.
type (string) -- [REQUIRED]
The type of tool.
name (string) --
Unique name for the tool. If not provided, a name will be inferred or generated.
config (dict) --
Tool-specific configuration.
remoteMcp (dict) --
Configuration for remote MCP server.
url (string) -- [REQUIRED]
URL of the MCP endpoint.
headers (dict) --
Map of key/value pairs for HTTP headers.
(string) --
The key of an HTTP header.
(string) --
The value of an HTTP header.
agentCoreBrowser (dict) --
Configuration for AgentCore Browser.
browserArn (string) --
If not populated, the built-in Browser ARN is used.
agentCoreGateway (dict) --
Configuration for AgentCore Gateway.
gatewayArn (string) -- [REQUIRED]
The ARN of the desired AgentCore Gateway.
outboundAuth (dict) --
How Loopy authenticates to this Gateway. Defaults to AWS_IAM (SigV4) if omitted.
awsIam (:class:`.EventStream`) --
SigV4-sign requests using the agent's execution role.
none (:class:`.EventStream`) --
No authentication.
oauth (dict) --
OAuth 2.0 authentication via AgentCore Identity.
providerArn (string) -- [REQUIRED]
The ARN of the OAuth 2.0 credential provider in AgentCore Identity.
scopes (list) -- [REQUIRED]
The OAuth 2.0 scopes to request when obtaining an access token.
(string) --
customParameters (dict) --
Additional custom parameters to include in the OAuth 2.0 token request.
(string) --
(string) --
grantType (string) --
The OAuth 2.0 grant type to use for authentication.
defaultReturnUrl (string) --
The default return URL for the OAuth 2.0 authorization flow.
inlineFunction (dict) --
Configuration for an inline function tool.
description (string) -- [REQUIRED]
Description of what the tool does, provided to the model.
inputSchema (:ref:`document<document>`) -- [REQUIRED]
JSON Schema describing the tool's input parameters.
agentCoreCodeInterpreter (dict) --
Configuration for AgentCore Code Interpreter.
codeInterpreterArn (string) --
If not populated, the built-in Code Interpreter ARN is used.
list
The skills available to the agent for this invocation. If specified, overrides the harness default.
(dict) --
A skill available to the agent.
path (string) --
The filesystem path to the skill definition.
list
The tools that the agent is allowed to use for this invocation. If specified, overrides the harness default.
(string) --
integer
The maximum number of iterations the agent loop can execute. If specified, overrides the harness default.
integer
The maximum number of tokens the agent can generate per iteration. If specified, overrides the harness default.
integer
The maximum duration in seconds for the agent loop execution. If specified, overrides the harness default.
string
The actor ID for memory operations. Overrides the actor ID configured on the harness.
dict
The response of this operation contains an :class:`.EventStream` member. When iterated the :class:`.EventStream` will yield events based on the structure below, where only one of the top level keys will be present for any given event.
Response Syntax
{
'stream': EventStream({
'messageStart': {
'role': 'user'|'assistant'
},
'contentBlockStart': {
'contentBlockIndex': 123,
'start': {
'toolUse': {
'toolUseId': 'string',
'name': 'string',
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use',
'serverName': 'string'
},
'toolResult': {
'toolUseId': 'string',
'status': 'success'|'error'
}
}
},
'contentBlockDelta': {
'contentBlockIndex': 123,
'delta': {
'text': 'string',
'toolUse': {
'input': 'string'
},
'toolResult': [
{
'text': 'string',
'json': {...}|[...]|123|123.4|'string'|True|None
},
],
'reasoningContent': {
'text': 'string',
'redactedContent': b'bytes',
'signature': 'string'
}
}
},
'contentBlockStop': {
'contentBlockIndex': 123
},
'messageStop': {
'stopReason': 'end_turn'|'tool_use'|'tool_result'|'max_tokens'|'stop_sequence'|'content_filtered'|'malformed_model_output'|'malformed_tool_use'|'interrupted'|'partial_turn'|'model_context_window_exceeded'|'max_iterations_exceeded'|'max_output_tokens_exceeded'|'timeout_exceeded'
},
'metadata': {
'usage': {
'inputTokens': 123,
'outputTokens': 123,
'totalTokens': 123,
'cacheReadInputTokens': 123,
'cacheWriteInputTokens': 123
},
'metrics': {
'latencyMs': 123
}
},
'internalServerException': {
'message': 'string'
},
'validationException': {
'message': 'string',
'reason': 'CannotParse'|'FieldValidationFailed'|'IdempotentParameterMismatchException'|'EventInOtherSession'|'ResourceConflict',
'fieldList': [
{
'name': 'string',
'message': 'string'
},
]
},
'runtimeClientError': {
'message': 'string'
}
})
}
Response Structure
(dict) --
stream (:class:`.EventStream`) --
The streaming output from the harness invocation.
messageStart (dict) --
Indicates the start of a new message from the agent.
role (string) --
The role of the message sender.
contentBlockStart (dict) --
Indicates the start of a new content block.
contentBlockIndex (integer) --
The index of the content block within the message.
start (dict) --
The content block start payload.
toolUse (dict) --
Start of a tool use content block.
toolUseId (string) --
The unique ID of this tool use.
name (string) --
The name of the tool being called.
type (string) --
The type of tool use.
serverName (string) --
The name of the MCP server providing this tool.
toolResult (dict) --
Start of a tool result content block.
toolUseId (string) --
The tool use ID that this result corresponds to.
status (string) --
The status of the tool execution.
contentBlockDelta (dict) --
A delta update to the current content block.
contentBlockIndex (integer) --
The index of the content block being updated.
delta (dict) --
The delta payload.
text (string) --
A text delta.
toolUse (dict) --
A tool use input delta.
input (string) --
The partial JSON input for the tool call.
toolResult (list) --
A tool result delta.
(dict) --
A delta update to a tool result content block.
text (string) --
A text tool result delta.
json (:ref:`document<document>`) --
A JSON tool result delta.
reasoningContent (dict) --
A reasoning content delta.
text (string) --
Reasoning text delta.
redactedContent (bytes) --
Redacted reasoning content.
signature (string) --
Signature for the reasoning content.
contentBlockStop (dict) --
Indicates the end of the current content block.
contentBlockIndex (integer) --
The index of the content block that ended.
messageStop (dict) --
Indicates the end of the current message.
stopReason (string) --
The reason the agent stopped generating.
metadata (dict) --
Token usage and latency metrics for the invocation.
usage (dict) --
Token usage counts.
inputTokens (integer) --
The number of input tokens consumed.
outputTokens (integer) --
The number of output tokens generated.
totalTokens (integer) --
The total number of tokens consumed.
cacheReadInputTokens (integer) --
The number of input tokens read from cache.
cacheWriteInputTokens (integer) --
The number of input tokens written to cache.
metrics (dict) --
Latency metrics.
latencyMs (integer) --
The end-to-end latency of the invocation in milliseconds.
internalServerException (dict) --
The exception that occurs when the service encounters an unexpected internal error. This is a temporary condition that will resolve itself with retries. We recommend implementing exponential backoff retry logic in your application.
message (string) --
validationException (dict) --
The exception that occurs when the input fails to satisfy the constraints specified by the service. Check the error message for details about which input parameter is invalid and correct your request.
message (string) --
reason (string) --
fieldList (list) --
(dict) --
Stores information about a field passed inside a request that resulted in an exception.
name (string) --
The name of the field.
message (string) --
A message describing why this field failed validation.
runtimeClientError (dict) --
The exception that occurs when there is an error in the runtime client. This can happen due to network issues, invalid configuration, or other client-side problems. Check the error message for specific details about the error.
message (string) --