:doc:`BedrockAgentCore <../../bedrock-agentcore>` / Client / invoke_agent_runtime

********************
invoke_agent_runtime
********************



.. py:method:: BedrockAgentCore.Client.invoke_agent_runtime(**kwargs)

  

  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 must specify the AgentCore Runtime ARN and provide a payload containing your request. You can optionally specify a qualifier to target a specific version or 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 <https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-invoke-agent.html>`__.

   

  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 <https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-oauth.html>`__.

   

  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``).

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/bedrock-agentcore-2024-02-28/InvokeAgentRuntime>`_  


  **Request Syntax**
  ::

    response = client.invoke_agent_runtime(
        contentType='string',
        accept='string',
        mcpSessionId='string',
        runtimeSessionId='string',
        mcpProtocolVersion='string',
        runtimeUserId='string',
        traceId='string',
        traceParent='string',
        traceState='string',
        baggage='string',
        agentRuntimeArn='string',
        qualifier='string',
        accountId='string',
        payload=b'bytes'|file
    )
    
  :type contentType: string
  :param 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.

    

  
  :type accept: string
  :param 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.

    

  
  :type mcpSessionId: string
  :param mcpSessionId: 

    The identifier of the MCP session.

    

  
  :type runtimeSessionId: string
  :param runtimeSessionId: 

    The identifier of the runtime session.

    This field is autopopulated if not provided.

  
  :type mcpProtocolVersion: string
  :param mcpProtocolVersion: 

    The version of the MCP protocol being used.

    

  
  :type runtimeUserId: string
  :param runtimeUserId: 

    The identifier of the runtime user.

    

  
  :type traceId: string
  :param traceId: 

    The trace identifier for request tracking.

    

  
  :type traceParent: string
  :param traceParent: 

    The parent trace information for distributed tracing.

    

  
  :type traceState: string
  :param traceState: 

    The trace state information for distributed tracing.

    

  
  :type baggage: string
  :param baggage: 

    Additional context information for distributed tracing.

    

  
  :type agentRuntimeArn: string
  :param agentRuntimeArn: **[REQUIRED]** 

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

    

  
  :type qualifier: string
  :param qualifier: 

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

    

  
  :type accountId: string
  :param accountId: 

    The identifier of the Amazon Web Services account for the agent runtime resource.

    

  
  :type payload: bytes or seekable file-like object
  :param payload: **[REQUIRED]** 

    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.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'runtimeSessionId': 'string',
          'mcpSessionId': 'string',
          'mcpProtocolVersion': 'string',
          'traceId': 'string',
          'traceParent': 'string',
          'traceState': 'string',
          'baggage': 'string',
          'contentType': 'string',
          'response': StreamingBody(),
          'statusCode': 123
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **runtimeSessionId** *(string) --* 

        The identifier of the runtime session.

        
      

      - **mcpSessionId** *(string) --* 

        The identifier of the MCP session.

        
      

      - **mcpProtocolVersion** *(string) --* 

        The version of the MCP protocol being used.

        
      

      - **traceId** *(string) --* 

        The trace identifier for request tracking.

        
      

      - **traceParent** *(string) --* 

        The parent trace information for distributed tracing.

        
      

      - **traceState** *(string) --* 

        The trace state information for distributed tracing.

        
      

      - **baggage** *(string) --* 

        Additional context information for distributed tracing.

        
      

      - **contentType** *(string) --* 

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

        
      

      - **response** (:class:`.StreamingBody`) -- 

        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.

        
      

      - **statusCode** *(integer) --* 

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

        
  
  **Exceptions**
  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ServiceQuotaExceededException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ValidationException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.RuntimeClientError`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ThrottlingException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`BedrockAgentCore.Client.exceptions.InternalServerException`

  