:doc:`Inspector <../../inspector>` / Client / preview_agents

**************
preview_agents
**************



.. py:method:: Inspector.Client.preview_agents(**kwargs)

  

  Previews the agents installed on the EC2 instances that are part of the specified assessment target.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/inspector-2016-02-16/PreviewAgents>`_  


  **Request Syntax**
  ::

    response = client.preview_agents(
        previewAgentsArn='string',
        nextToken='string',
        maxResults=123
    )
    
  :type previewAgentsArn: string
  :param previewAgentsArn: **[REQUIRED]** 

    The ARN of the assessment target whose agents you want to preview.

    

  
  :type nextToken: string
  :param nextToken: 

    You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the **PreviewAgents** action. Subsequent calls to the action fill **nextToken** in the request with the value of **NextToken** from the previous response to continue listing data.

    

  
  :type maxResults: integer
  :param maxResults: 

    You can use this parameter to indicate the maximum number of items you want in the response. The default value is 10. The maximum value is 500.

    

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

    
    ::

      {
          'agentPreviews': [
              {
                  'hostname': 'string',
                  'agentId': 'string',
                  'autoScalingGroup': 'string',
                  'agentHealth': 'HEALTHY'|'UNHEALTHY'|'UNKNOWN',
                  'agentVersion': 'string',
                  'operatingSystem': 'string',
                  'kernelVersion': 'string',
                  'ipv4Address': 'string'
              },
          ],
          'nextToken': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **agentPreviews** *(list) --* 

        The resulting list of agents.

        
        

        - *(dict) --* 

          Used as a response element in the  PreviewAgents action.

          
          

          - **hostname** *(string) --* 

            The hostname of the EC2 instance on which the Amazon Inspector Agent is installed.

            
          

          - **agentId** *(string) --* 

            The ID of the EC2 instance where the agent is installed.

            
          

          - **autoScalingGroup** *(string) --* 

            The Auto Scaling group for the EC2 instance where the agent is installed.

            
          

          - **agentHealth** *(string) --* 

            The health status of the Amazon Inspector Agent.

            
          

          - **agentVersion** *(string) --* 

            The version of the Amazon Inspector Agent.

            
          

          - **operatingSystem** *(string) --* 

            The operating system running on the EC2 instance on which the Amazon Inspector Agent is installed.

            
          

          - **kernelVersion** *(string) --* 

            The kernel version of the operating system running on the EC2 instance on which the Amazon Inspector Agent is installed.

            
          

          - **ipv4Address** *(string) --* 

            The IP address of the EC2 instance on which the Amazon Inspector Agent is installed.

            
      
    
      

      - **nextToken** *(string) --* 

        When a response is generated, if there is more data to be listed, this parameter is present in the response and contains the value to use for the **nextToken** parameter in a subsequent pagination request. If there is no more data to be listed, this parameter is set to null.

        
  
  **Exceptions**
  
  *   :py:class:`Inspector.Client.exceptions.InternalException`

  
  *   :py:class:`Inspector.Client.exceptions.InvalidInputException`

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

  
  *   :py:class:`Inspector.Client.exceptions.NoSuchEntityException`

  
  *   :py:class:`Inspector.Client.exceptions.InvalidCrossAccountRoleException`

  

  **Examples**

  Previews the agents installed on the EC2 instances that are part of the specified assessment target.
  ::

    response = client.preview_agents(
        maxResults=123,
        previewAgentsArn='arn:aws:inspector:us-west-2:123456789012:target/0-0kFIPusq',
    )
    
    print(response)

  
  Expected Output:
  ::

    {
        'agentPreviews': [
            {
                'agentId': 'i-49113b93',
            },
        ],
        'nextToken': '1',
        'ResponseMetadata': {
            '...': '...',
        },
    }

  