Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

InvokeAgentRuntime

Sends a request to an agent runtime in Amazon Bedrock and receives responses in real-time. The agent processes the request using the configured foundation model and any associated knowledge bases or action groups.

To invoke an agent runtime, you must specify the agent runtime ARN and provide a payload containing your request. You can optionally specify a qualifier to target a specific version or alias of the agent.

This operation supports streaming responses, allowing you to receive partial responses as they become available. We recommend using pagination to ensure that the operation returns quickly and successfully when processing large responses.

Request Syntax


POST /runtimes/agentRuntimeArn/invocations?qualifier=qualifier HTTP/1.1
Content-Type: contentType
Accept: accept
Mcp-Session-Id: mcpSessionId
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: runtimeSessionId
Mcp-Protocol-Version: mcpProtocolVersion
X-Amzn-Bedrock-AgentCore-Runtime-User-Id: runtimeUserId
X-Amzn-Trace-Id: traceId
traceparent: traceParent
tracestate: traceState
baggage: baggage

payload

URI Request Parameters

The request uses the following URI parameters.

accept

The desired MIME type for the response from the agent runtime. This tells the agent runtime what format to use for the response data. Common values include application/json for JSON data.

Length Constraints: Minimum length of 1. Maximum length of 256.

agentRuntimeArn

The AWS Resource Name (ARN) of the agent runtime to invoke. The ARN uniquely identifies the agent runtime resource in Amazon Bedrock.

Required: Yes

baggage

Additional context information for distributed tracing.

Length Constraints: Minimum length of 0. Maximum length of 8192.

contentType

The MIME type of the input data in the payload. This tells the agent runtime how to interpret the payload data. Common values include application/json for JSON data.

Length Constraints: Minimum length of 1. Maximum length of 256.

mcpProtocolVersion

The version of the MCP protocol being used.

Length Constraints: Minimum length of 1. Maximum length of 1024.

mcpSessionId

The identifier of the MCP session.

Length Constraints: Minimum length of 1. Maximum length of 1024.

qualifier

The qualifier to use for the agent runtime. This can be a version number or an alias name that points to a specific version. If not specified, Amazon Bedrock uses the default version of the agent runtime.

runtimeSessionId

The identifier of the runtime session.

Length Constraints: Minimum length of 33. Maximum length of 256.

runtimeUserId

The identifier of the runtime user.

Length Constraints: Minimum length of 1. Maximum length of 1024.

traceId

The trace identifier for request tracking.

Length Constraints: Minimum length of 0. Maximum length of 128.

traceParent

The parent trace information for distributed tracing.

Length Constraints: Minimum length of 0. Maximum length of 128.

traceState

The trace state information for distributed tracing.

Length Constraints: Minimum length of 0. Maximum length of 512.

Request Body

The request accepts the following binary data.

payload

The input data to send to the agent runtime. The format of this data depends on the specific agent configuration and must match the specified content type. For most agents, this is a JSON object containing the user's request.

Length Constraints: Minimum length of 0. Maximum length of 100000000.

Required: Yes

Response Syntax


HTTP/1.1 statusCode
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: runtimeSessionId
Mcp-Session-Id: mcpSessionId
Mcp-Protocol-Version: mcpProtocolVersion
X-Amzn-Trace-Id: traceId
traceparent: traceParent
tracestate: traceState
baggage: baggage
Content-Type: contentType

response

Response Elements

If the action is successful, the service sends back the following HTTP response.

statusCode: The HTTP status code of the response. A status code of 200 indicates a successful operation. Other status codes indicate various error conditions.

The response returns the following HTTP headers.

baggage

Additional context information for distributed tracing.

contentType

The MIME type of the response data. This indicates how to interpret the response data. Common values include application/json for JSON data.

mcpProtocolVersion

The version of the MCP protocol being used.

mcpSessionId

The identifier of the MCP session.

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: [a-zA-Z0-9][a-zA-Z0-9-_]*

runtimeSessionId

The identifier of the runtime session.

Length Constraints: Minimum length of 1. Maximum length of 100.

Pattern: [a-zA-Z0-9][a-zA-Z0-9-_]*

traceId

The trace identifier for request tracking.

traceParent

The parent trace information for distributed tracing.

traceState

The trace state information for distributed tracing.

The response returns the following as the HTTP body.

response: The response data from the agent runtime. The format of this data depends on the specific agent configuration and the requested accept type. For most agents, this is a JSON object containing the agent's response to the user's request.

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException

The exception that occurs when you do not have sufficient permissions to perform an action. Verify that your IAM policy includes the necessary permissions for the operation you are trying to perform.

HTTP Status Code: 403

InternalServerException

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.

HTTP Status Code: 500

ResourceNotFoundException

The exception that occurs when the specified resource does not exist. This can happen when using an invalid identifier or when trying to access a resource that has been deleted.

HTTP Status Code: 404

RuntimeClientError

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.

HTTP Status Code: 424

ServiceQuotaExceededException

The exception that occurs when the request would cause a service quota to be exceeded. Review your service quotas and either reduce your request rate or request a quota increase.

HTTP Status Code: 402

ThrottlingException

The exception that occurs when the request was denied due to request throttling. This happens when you exceed the allowed request rate for an operation. Reduce the frequency of requests or implement exponential backoff retry logic in your application.

HTTP Status Code: 429

ValidationException

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.

HTTP Status Code: 400