Skip to content

invoke_agent_runtime

Operation

invoke_agent_runtime

invoke_agent_runtime(request: InvokeAgentRuntimeInput | InvokeAgentRuntimeInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[InvokeAgentRuntimeInputDict]) -> InvokeAgentRuntimeOutput

Sends a request to an agent or tool hosted in an Amazon Bedrock AgentCore Runtime and receives responses in real-time.

To invoke an agent, you can specify either the AgentCore Runtime ARN or the agent ID with an account ID, and provide a payload containing your request. When you use the agent ID instead of the full ARN, you don't need to URL-encode the identifier. You can optionally specify a qualifier to target a specific endpoint 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.

For example code, see Invoke an AgentCore Runtime agent.

If you're integrating your agent with OAuth, you can't use the Amazon Web Services SDK to call InvokeAgentRuntime. Instead, make a HTTPS request to InvokeAgentRuntime. For an example, see Authenticate and authorize with Inbound Auth and Outbound Auth.

To use this operation, you must have the bedrock-agentcore:InvokeAgentRuntime permission. If you are making a call to InvokeAgentRuntime on behalf of a user ID with the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header, You require permissions to both actions (bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:InvokeAgentRuntimeForUser).

Parameters:

Name Type Description Default
request InvokeAgentRuntimeInput | InvokeAgentRuntimeInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[InvokeAgentRuntimeInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
InvokeAgentRuntimeOutput

An instance of InvokeAgentRuntimeOutput.

invoke_agent_runtime async

invoke_agent_runtime(request: InvokeAgentRuntimeInput | InvokeAgentRuntimeInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[InvokeAgentRuntimeInputDict]) -> InvokeAgentRuntimeOutput

Sends a request to an agent or tool hosted in an Amazon Bedrock AgentCore Runtime and receives responses in real-time.

To invoke an agent, you can specify either the AgentCore Runtime ARN or the agent ID with an account ID, and provide a payload containing your request. When you use the agent ID instead of the full ARN, you don't need to URL-encode the identifier. You can optionally specify a qualifier to target a specific endpoint 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.

For example code, see Invoke an AgentCore Runtime agent.

If you're integrating your agent with OAuth, you can't use the Amazon Web Services SDK to call InvokeAgentRuntime. Instead, make a HTTPS request to InvokeAgentRuntime. For an example, see Authenticate and authorize with Inbound Auth and Outbound Auth.

To use this operation, you must have the bedrock-agentcore:InvokeAgentRuntime permission. If you are making a call to InvokeAgentRuntime on behalf of a user ID with the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header, You require permissions to both actions (bedrock-agentcore:InvokeAgentRuntime and bedrock-agentcore:InvokeAgentRuntimeForUser).

Parameters:

Name Type Description Default
request InvokeAgentRuntimeInput | InvokeAgentRuntimeInputDict | None

The input as a model or dictionary. Pass this or keyword arguments, not both.

None
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

None
**kwargs Unpack[InvokeAgentRuntimeInputDict]

The input fields as keyword arguments.

{}

Returns:

Type Description
InvokeAgentRuntimeOutput

An instance of InvokeAgentRuntimeOutput.

Input

Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.

InvokeAgentRuntimeInputDict

Bases: TypedDict

Dictionary form of InvokeAgentRuntimeInput.

Attributes

accept instance-attribute
accept: str | None

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.

account_id instance-attribute
account_id: str | None

The identifier of the Amazon Web Services account for the agent runtime resource. This parameter is required when you specify an agent ID instead of the full ARN for agentRuntimeArn.

agent_runtime_arn instance-attribute
agent_runtime_arn: Required[str]

The identifier of the agent runtime to invoke. You can specify either the full Amazon Web Services Resource Name (ARN) or the agent ID. If you use the agent ID, you must also provide the accountId query parameter.

baggage instance-attribute
baggage: str | None

Additional context information for distributed tracing.

content_type instance-attribute
content_type: str | None

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.

mcp_method instance-attribute
mcp_method: str | None

The MCP method being invoked. For example, tools/call, resources/read, or prompts/get.

mcp_name instance-attribute
mcp_name: str | None

The name of the MCP resource, tool, or prompt being accessed. The value depends on the method:

  • tools/call -- The tool name.

  • resources/read -- The resource URI.

  • prompts/get -- The prompt name.

mcp_protocol_version instance-attribute
mcp_protocol_version: str | None

The version of the MCP protocol being used.

mcp_session_id instance-attribute
mcp_session_id: str | None

The identifier of the MCP session.

payload instance-attribute
payload: Required[bytes]

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.

qualifier instance-attribute
qualifier: str | None

The qualifier to use for the agent runtime. This is an endpoint name that points to a specific version. If not specified, Amazon Bedrock AgentCore uses the default endpoint of the agent runtime.

runtime_session_id instance-attribute
runtime_session_id: str | None

The identifier of the runtime session.

This field is autopopulated if not provided.

runtime_user_id instance-attribute
runtime_user_id: str | None

The identifier of the runtime user.

trace_id instance-attribute
trace_id: str | None

The trace identifier for request tracking.

trace_parent instance-attribute
trace_parent: str | None

The parent trace information for distributed tracing.

trace_state instance-attribute
trace_state: str | None

The trace state information for distributed tracing.

InvokeAgentRuntimeInput dataclass

Bases: _SerdeShape

Dataclass for InvokeAgentRuntimeInput structure.

Attributes

accept class-attribute instance-attribute
accept: str | None = ...

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.

account_id class-attribute instance-attribute
account_id: str | None = ...

The identifier of the Amazon Web Services account for the agent runtime resource. This parameter is required when you specify an agent ID instead of the full ARN for agentRuntimeArn.

agent_runtime_arn class-attribute instance-attribute
agent_runtime_arn: str | None = ...

The identifier of the agent runtime to invoke. You can specify either the full Amazon Web Services Resource Name (ARN) or the agent ID. If you use the agent ID, you must also provide the accountId query parameter.

baggage class-attribute instance-attribute
baggage: str | None = ...

Additional context information for distributed tracing.

content_type class-attribute instance-attribute
content_type: str | None = ...

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.

mcp_method class-attribute instance-attribute
mcp_method: str | None = ...

The MCP method being invoked. For example, tools/call, resources/read, or prompts/get.

mcp_name class-attribute instance-attribute
mcp_name: str | None = ...

The name of the MCP resource, tool, or prompt being accessed. The value depends on the method:

  • tools/call -- The tool name.

  • resources/read -- The resource URI.

  • prompts/get -- The prompt name.

mcp_protocol_version class-attribute instance-attribute
mcp_protocol_version: str | None = ...

The version of the MCP protocol being used.

mcp_session_id class-attribute instance-attribute
mcp_session_id: str | None = ...

The identifier of the MCP session.

payload class-attribute instance-attribute
payload: bytes | None = ...

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.

qualifier class-attribute instance-attribute
qualifier: str | None = ...

The qualifier to use for the agent runtime. This is an endpoint name that points to a specific version. If not specified, Amazon Bedrock AgentCore uses the default endpoint of the agent runtime.

runtime_session_id class-attribute instance-attribute
runtime_session_id: str | None = ...

The identifier of the runtime session.

This field is autopopulated if not provided.

runtime_user_id class-attribute instance-attribute
runtime_user_id: str | None = ...

The identifier of the runtime user.

trace_id class-attribute instance-attribute
trace_id: str | None = ...

The trace identifier for request tracking.

trace_parent class-attribute instance-attribute
trace_parent: str | None = ...

The parent trace information for distributed tracing.

trace_state class-attribute instance-attribute
trace_state: str | None = ...

The trace state information for distributed tracing.

Output

InvokeAgentRuntimeOutput dataclass

Bases: _SerdeShape

Dataclass for InvokeAgentRuntimeOutput structure.

Attributes

baggage class-attribute instance-attribute
baggage: str | None = ...

Additional context information for distributed tracing.

content_type instance-attribute
content_type: str

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

mcp_protocol_version class-attribute instance-attribute
mcp_protocol_version: str | None = ...

The version of the MCP protocol being used.

mcp_session_id class-attribute instance-attribute
mcp_session_id: str | None = ...

The identifier of the MCP session.

response class-attribute instance-attribute
response: StreamingBlob = ...

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.

response_metadata class-attribute instance-attribute
response_metadata: ResponseMetadata = ...

Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.

runtime_session_id class-attribute instance-attribute
runtime_session_id: str | None = ...

The identifier of the runtime session.

session_endpoint_url class-attribute instance-attribute
session_endpoint_url: str | None = ...

The HTTPS endpoint that addresses this runtime session directly. This value is returned only when the agent runtime is configured with allowed ports and direct runtime access is available for the session. If this value is not present, use InvokeAgentRuntime to communicate with the session.

status_code class-attribute instance-attribute
status_code: int | None = ...

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

trace_id class-attribute instance-attribute
trace_id: str | None = ...

The trace identifier for request tracking.

trace_parent class-attribute instance-attribute
trace_parent: str | None = ...

The parent trace information for distributed tracing.

trace_state class-attribute instance-attribute
trace_state: str | None = ...

The trace state information for distributed tracing.