> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent tools

> Use Microsoft Intune agent tools in Ravenna rules to look up managed devices and installed applications scoped to the ticket requester's email.

Microsoft Intune provides AI agent tools for looking up managed device information and installed applications. Reference these tools in <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">agent rules</Tooltip> using @ mentions to enable automated device lookups during ticket handling.

***

## Available tools

<AccordionGroup>
  <Accordion title="Find devices" defaultOpen>
    Searches for managed devices in Microsoft Intune for the ticket requester. Supports filtering by serial number, device name, model, or operating system. Results are always scoped to the current requester's email address.

    **Tool name:** `@Find Devices`

    **Input fields:**

    * Serial number
    * Device name
    * Model (e.g., "Surface Pro", "iPhone 15", "ThinkPad X1")
    * Operating system (e.g., "Windows", "iOS", "Android", "macOS")

    **Output data:**

    * Device name, operating system, OS version
    * Model, manufacturer, serial number
    * Compliance state, last sync time
    * Device ID, enrollment date, management state
    * Primary user (UPN)

    **Common use cases:**

    * Look up requester devices when troubleshooting hardware or software issues
    * Verify device compliance before approving access requests
    * Identify device details for IT support workflows
    * Check when a device last synced with Intune

    **Example rule:**

    <Prompt description="Intune device lookup rule">
      When a user reports a device issue, use @Find Devices to look up their managed devices.
      If the device is non-compliant, inform the user of the compliance issue before troubleshooting.
    </Prompt>
  </Accordion>

  <Accordion title="Get device apps">
    Retrieves detected applications installed on a specific Intune managed device. Requires a device ID obtained from the Find Devices tool. Supports optional filtering by app name, platform, or publisher.

    **Tool name:** `@Get Device Apps`

    **Input fields:**

    * Intune managed device ID (from Find Devices results)
    * App name filter (optional, substring match)
    * Platform filter (optional, e.g., "windows", "ios", "macOS")
    * Publisher filter (optional, substring match)

    **Output data:**

    * Application name, version, publisher
    * Platform
    * App ID

    **Common use cases:**

    * Verify whether a specific application is installed on a user's device
    * Audit installed software for compliance or licensing checks
    * Troubleshoot application issues by checking installed versions
    * Identify outdated software that needs updating

    **Example rule:**

    <Prompt description="Intune device apps lookup rule">
      When a user reports a software issue, use @Find Devices and @Get Device Apps to check which applications and versions are on their device.
      Inform the user if the application is missing or outdated.
    </Prompt>
  </Accordion>

  <Accordion title="Autopilot reset">
    Triggers an Autopilot reset on a managed Windows device, wiping it and re-provisioning it through Windows Autopilot. The device is resolved from the ticket requester's context.

    <Warning>
      An Autopilot reset wipes all data from the device and re-provisions it from scratch. Confirm with the user before triggering this action.
    </Warning>

    **Tool name:** `@Autopilot Reset`

    **Input fields:**

    * Device (resolved from ticket context)

    **Common use cases:**

    * Reset a user's device when troubleshooting reveals a system-level issue
    * Reprovision devices as part of automated IT support workflows
    * Prepare a device for a new user assignment

    **Example rule:**

    <Prompt description="Intune Autopilot reset rule">
      If the user needs their Windows device fully reset, use @Find Devices to locate the device, then use @Autopilot Reset to wipe and reprovision it.
      Confirm with the user that the reset has been queued.
    </Prompt>
  </Accordion>

  <Accordion title="Retire device">
    Retires an Intune-managed device, removing company data and management profiles while leaving personal data intact.

    **Tool name:** `@Retire Device`

    **Input fields:**

    * Device (resolved from ticket context)

    **Common use cases:**

    * Remove corporate data from a BYOD device during offboarding
    * Retire devices that should no longer be managed
    * Automate device retirement in offboarding workflows

    **Example rule:**

    <Prompt description="Intune retire device rule">
      When processing an offboarding request for a BYOD user, use @Find Devices to locate their personal device, then use @Retire Device to remove corporate data.
      Notify the user that company data has been removed from their device.
    </Prompt>
  </Accordion>

  <Accordion title="Sync device">
    Forces a device to check in with Intune and pull pending policies, configuration profiles, and compliance updates immediately.

    **Tool name:** `@Sync Device`

    **Input fields:**

    * Device (resolved from ticket context)

    **Common use cases:**

    * Push urgent policy updates when a user reports missing configurations
    * Verify a device picks up new compliance requirements
    * Troubleshoot devices that appear out of sync

    **Example rule:**

    <Prompt description="Intune sync device rule">
      When a user reports they are missing an expected policy or configuration, use @Find Devices to locate their device, then use @Sync Device to force a check-in.
      Let the user know their device is syncing and to check again in a few minutes.
    </Prompt>
  </Accordion>

  <Accordion title="Rotate BitLocker key">
    Rotates the BitLocker recovery key on the specified Windows device. The new key is stored in Intune for administrator access.

    **Tool name:** `@Rotate BitLocker Key`

    **Input fields:**

    * Device (resolved from ticket context)

    **Common use cases:**

    * Rotate recovery keys after they have been shared during support
    * Implement security compliance key rotation
    * Respond to incidents by rotating encryption keys

    **Example rule:**

    <Prompt description="Intune BitLocker key rotation rule">
      After helping a user with a BitLocker recovery, use @Find Devices to locate their device, then use @Rotate BitLocker Key to generate a new recovery key.
      Inform the user that their recovery key has been rotated for security.
    </Prompt>
  </Accordion>

  <Accordion title="Wipe device">
    Performs a full wipe of an Intune-managed device, removing all data and restoring factory settings. For macOS devices, returns a 6-digit unlock code.

    <Warning>
      A full wipe is destructive and removes all data from the device. Make sure the user has backed up any necessary data before triggering this action.
    </Warning>

    **Tool name:** `@Wipe Device`

    **Input fields:**

    * Device (resolved from ticket context)

    **Output data:**

    * macOS unlock code (only for macOS devices)

    **Common use cases:**

    * Wipe lost or stolen devices to protect corporate data
    * Prepare devices for decommissioning
    * Respond to security incidents requiring immediate data removal

    **Example rule:**

    <Prompt description="Intune wipe device rule">
      If a user reports a lost or stolen device, use @Find Devices to locate it, then use @Wipe Device to remotely erase all data.
      If the device is macOS, provide the unlock code to the user's manager via a private note.
    </Prompt>
  </Accordion>

  <Accordion title="Assign script">
    Assigns an Intune management script to a group so it runs on all devices belonging to group members.

    **Tool name:** `@Assign Script`

    **Input fields:**

    * Script ID
    * Entra group
    * Organization

    **Common use cases:**

    * Deploy remediation scripts to affected teams
    * Assign configuration scripts during onboarding
    * Automate script deployment based on ticket context

    **Example rule:**

    <Prompt description="Intune assign script rule">
      When a user needs a specific configuration applied to their device, use @Assign Script to deploy the relevant remediation script to their group.
      Confirm to the user that the script has been assigned and will run on their next device check-in.
    </Prompt>
  </Accordion>
</AccordionGroup>

***

## Setup

<Steps>
  <Step title="Install Intune integration">
    Follow the [Microsoft Intune setup guide](/integrations/intune/setup) to connect your Intune tenant to Ravenna.
  </Step>

  <Step title="Configure agent">
    Navigate to your agent's settings and ensure the Intune tool appears in the Tools section under Capabilities.
  </Step>

  <Step title="Create rules">
    Write <Tooltip headline="Agent rules" tip="Natural language instructions defining agent behavior" cta="Learn about agent rules" href="/documentation/automate/agents/configure#rules">rules</Tooltip> that reference the Intune tool using @ mentions.
  </Step>

  <Step title="Test the tool">
    Test your rules in a controlled environment to verify the tool returns expected device data.
  </Step>
</Steps>

***

## Best practices

* Device results are automatically scoped to the ticket requester's email, so no additional user filtering is needed
* Combine device lookup with compliance checks in access request workflows
* Use serial number for precise device identification when the requester has multiple devices
* Chain Find Devices with Get Device Apps for complete device audits: look up the device first, then check its installed applications
* Use the app name, platform, and publisher filters in Get Device Apps to narrow results when a device has many installed applications

<Callout icon="link" color="#6B7280">
  Learn more about [configuring agents](/documentation/automate/agents/configure) and writing effective rules
</Callout>