BedrockAgentCore / Client / invoke_harness

invoke_harness¶

BedrockAgentCore.Client.invoke_harness(**kwargs)¶

Operation to invoke a Harness.

Request Syntax

response = 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'|'TOKEN_EXCHANGE',
                            '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'
)

Parameters:

harnessArn (string) –
[REQUIRED]

The ARN of the harness to invoke.
runtimeSessionId (string) –
[REQUIRED]

The session ID for the invocation. Use the same session ID across requests to continue a conversation.
messages (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.
      
      Note
      This is a Tagged Union structure. Only one of the following top level keys can be set: text, toolUse, toolResult, reasoningContent.
      - 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 (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.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: text, json.
        
        text (string) –
        
        Text content.
        
        json (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.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: reasoningText, redactedContent.
        
        reasoningText (dict) –
        
        The reasoning text.
        
        text (string) – [REQUIRED]
        
        The reasoning text.
        
        signature (string) –
        
        Signature for verifying the reasoning content.
        
        redactedContent (bytes) –
        
        Redacted reasoning content.
model (dict) –
The model configuration to use for this invocation. If specified, overrides the harness default.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: bedrockModelConfig, openAiModelConfig, geminiModelConfig.
- 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.
systemPrompt (list) –
The system prompt to use for this invocation. If specified, overrides the harness default.
- (dict) –
  
  A content block in the system prompt.
  
  Note
  This is a Tagged Union structure. Only one of the following top level keys can be set: text.
  - text (string) –
    
    The text content of the system prompt block.
tools (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.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: remoteMcp, agentCoreBrowser, agentCoreGateway, inlineFunction, agentCoreCodeInterpreter.
    - remoteMcp (dict) –
      
      Configuration for remote MCP server.
      - url (string) – [REQUIRED]
        
        URL of the MCP endpoint.
      - headers (dict) –
        
        Custom headers to include when connecting to the remote MCP server.
        
        (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 harness authenticates to this Gateway. Defaults to AWS_IAM (SigV4) if omitted.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: awsIam, none, oauth.
        
        awsIam (dict) –
        
        SigV4-sign requests using the agent’s execution role.
        
        none (dict) –
        
        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 (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.
skills (list) –
The skills available to the agent for this invocation. If specified, overrides the harness default.
- (dict) –
  
  A skill available to the agent.
  
  Note
  This is a Tagged Union structure. Only one of the following top level keys can be set: path.
  - path (string) –
    
    The filesystem path to the skill definition.
allowedTools (list) –
The tools that the agent is allowed to use for this invocation. If specified, overrides the harness default.
- (string) –
maxIterations (integer) – The maximum number of iterations the agent loop can execute. If specified, overrides the harness default.
maxTokens (integer) – The maximum number of tokens the agent can generate per iteration. If specified, overrides the harness default.
timeoutSeconds (integer) – The maximum duration in seconds for the agent loop execution. If specified, overrides the harness default.
actorId (string) – The actor ID for memory operations. Overrides the actor ID configured on the harness.

Return type:

dict

Returns:

The response of this operation contains an EventStream member. When iterated the 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 (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.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: toolUse, toolResult. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - 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.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: text, toolUse, toolResult, reasoningContent. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - 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.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: text, json. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        text (string) –
        
        A text tool result delta.
        
        json (document) –
        
        A JSON tool result delta.
      - reasoningContent (dict) –
        
        A reasoning content delta.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: text, redactedContent, signature. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        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) –

Exceptions

BedrockAgentCore.Client.exceptions.AccessDeniedException
BedrockAgentCore.Client.exceptions.ValidationException
BedrockAgentCore.Client.exceptions.ResourceNotFoundException
BedrockAgentCore.Client.exceptions.ThrottlingException
BedrockAgentCore.Client.exceptions.InternalServerException