invoke_agent_runtime¶
Operation¶
async
¶
invoke_agent_runtime(input: InvokeAgentRuntimeInput, plugins: list[Plugin] | None = None) -> 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 |
|---|---|---|---|
input
|
InvokeAgentRuntimeInput
|
An instance of |
required |
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
|
Returns:
| Type | Description |
|---|---|
InvokeAgentRuntimeOutput
|
An instance of |
Input¶
dataclass
¶
Dataclass for InvokeAgentRuntimeInput structure.
Attributes¶
class-attribute
instance-attribute
¶
accept: str | None = 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.
class-attribute
instance-attribute
¶
account_id: str | None = 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.
class-attribute
instance-attribute
¶
agent_runtime_arn: str | None = 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.
class-attribute
instance-attribute
¶
baggage: str | None = None
Additional context information for distributed tracing.
class-attribute
instance-attribute
¶
content_type: str | None = 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.
class-attribute
instance-attribute
¶
mcp_method: str | None = None
The MCP method being invoked. For example, tools/call,
resources/read, or prompts/get.
class-attribute
instance-attribute
¶
mcp_name: str | None = 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.
class-attribute
instance-attribute
¶
mcp_protocol_version: str | None = None
The version of the MCP protocol being used.
class-attribute
instance-attribute
¶
mcp_session_id: str | None = None
The identifier of the MCP session.
class-attribute
instance-attribute
¶
payload: bytes | None = field(repr=False, default=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.
class-attribute
instance-attribute
¶
qualifier: str | None = 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.
class-attribute
instance-attribute
¶
runtime_session_id: str | None = None
The identifier of the runtime session.
class-attribute
instance-attribute
¶
runtime_user_id: str | None = None
The identifier of the runtime user.
class-attribute
instance-attribute
¶
trace_id: str | None = None
The trace identifier for request tracking.
class-attribute
instance-attribute
¶
trace_parent: str | None = None
The parent trace information for distributed tracing.
class-attribute
instance-attribute
¶
trace_state: str | None = None
The trace state information for distributed tracing.
Output¶
dataclass
¶
Dataclass for InvokeAgentRuntimeOutput structure.
Attributes¶
class-attribute
instance-attribute
¶
baggage: str | None = None
Additional context information for distributed tracing.
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.
class-attribute
instance-attribute
¶
mcp_protocol_version: str | None = None
The version of the MCP protocol being used.
class-attribute
instance-attribute
¶
mcp_session_id: str | None = None
The identifier of the MCP session.
class-attribute
instance-attribute
¶
response: StreamingBlob = field(repr=False, default=b'')
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.
class-attribute
instance-attribute
¶
runtime_session_id: str | None = None
The identifier of the runtime session.
class-attribute
instance-attribute
¶
status_code: int | None = None
The HTTP status code of the response. A status code of 200 indicates a successful operation. Other status codes indicate various error conditions.
class-attribute
instance-attribute
¶
trace_id: str | None = None
The trace identifier for request tracking.
class-attribute
instance-attribute
¶
trace_parent: str | None = None
The parent trace information for distributed tracing.
class-attribute
instance-attribute
¶
trace_state: str | None = None
The trace state information for distributed tracing.