> ## 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 the Omnissa agent tool in Ravenna rules to look up Workspace ONE UEM devices by device ID, serial number, name, platform, or user email.

Omnissa provides an AI agent tool for looking up devices managed in Workspace ONE UEM. Reference it 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 so your agent can identify a requester's devices and check their compliance without escalating to IT.

***

## Look up devices

<AccordionGroup>
  <Accordion title="Find devices" defaultOpen>
    Finds devices in Workspace ONE UEM. All input fields are optional. The tool always includes the requester's email as a fallback, so calling it with no inputs returns the requester's devices. It can return more than one device. A `deviceId` or `serialNumber` lookup is direct and is not limited to the requester's devices, so it can return any device in your tenant.

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

    **Input fields:**

    * `deviceId` - the Omnissa device ID. Use it for a precise lookup when more than one device matches.
    * `serialNumber` - the device serial number.
    * `deviceName` - the device friendly name. Matches the full name, ignoring case.
    * `platform` - the device platform, for example `Apple`, `Android`, or `WinRT`.

    When you pass `deviceId` or `serialNumber`, Ravenna looks up that device directly. Otherwise, Ravenna searches the requester's devices by email and applies the `platform` and `deviceName` filters.

    **Output data:**

    * `devices` - matched devices, each with `id`, `uuid`, `serialNumber`, `deviceName`, `userName`, `userEmail`, `platform`, `model`, `osVersion`, `ownership`, `complianceStatus`, `enrollmentStatus`, `lastSeen`, and `isSupervised`.

    **Common use cases:**

    * Look up a requester's devices when troubleshooting a hardware or software issue
    * Verify compliance and enrollment status before approving an access request
    * Find a device's serial number, model, or OS version for IT support
    * Check when a device last checked in with Workspace ONE UEM

    **Example rule:**

    <Prompt description="When a user reports a device issue, use @Find Devices to look up their devices in Omnissa. If multiple devices come back, ask which one they mean. If the device is not compliant, tell the user before troubleshooting.">
      When a user reports a device issue, use @Find Devices to look up
      their devices in Omnissa. If multiple devices come back, ask
      which one they mean. If the device is not compliant, tell the
      user before troubleshooting.
    </Prompt>
  </Accordion>
</AccordionGroup>

<Callout icon="shield" color="#6B7280">
  `@Find Devices` is a read-only tool. Use <Tooltip headline="Tool execution policies" tip="Per-tool setting for whether a tool runs automatically, needs confirmation, or needs approval" cta="Learn about execution policies" href="/documentation/automate/agents/configure#tool-execution-policies">tool execution policies</Tooltip> to control how tools run in each rule.
</Callout>

***

## Setup

<Steps>
  <Step title="Install Omnissa integration">
    Follow the [Omnissa setup guide](/integrations/omnissa/setup) to connect your Workspace ONE UEM tenant to Ravenna.
  </Step>

  <Step title="Configure agent">
    Open your agent's settings and add the Omnissa tool under **Tools**. An admin has to attach each tool before an agent or rule can call it.
  </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 Omnissa tool using @ mentions.
  </Step>

  <Step title="Test tools">
    Test your rules on a real request to verify the tool works as expected.
  </Step>
</Steps>

***

## Best practices

* **Start with the requester's email.** Call `@Find Devices` without inputs first. Add `serialNumber` or `deviceId` only when the user has more than one device.
* **Ask before assuming.** When several devices match, have the agent list them and ask the requester to pick one.
* **Use compliance as a gate.** Check `complianceStatus` in access-request rules before approving.

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


## Related topics

- [Agent tools](/integrations/fleet/agent-tools.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.