Skip to main content
Fleet provides AI agent tools for device lookup, health monitoring, diagnostic query execution, and admin password retrieval. Reference these tools in using @ mentions so your agent can investigate device issues and recover admin access without escalating to IT.

​
Look up devices

Look up device

Returns basic information about the Fleet-managed device for the current user, including hostname, platform, OS version, and online status. Use it to confirm which device to target before running diagnostics or recovering a password.Tool name: @Host InfoInput fields:
  • serial_number (optional) - the device serial number; only provide it when the host cannot be found by the user’s email or when multiple devices match.
Output data:
  • hostname - the device hostname.
  • platform - the operating system platform, for example darwin or windows.
  • osVersion - the operating system version string.
  • fleetStatus - the current Fleet status, for example online or offline.
  • displayName - the device’s display name in Fleet.
  • cpuType - the CPU model.
  • lastSeenAt - the timestamp Fleet last observed the device.
  • fleetHostId - the internal Fleet host ID.
Common use cases:
  • Confirm the device before running a diagnostic query
  • Check whether a device is online before attempting further operations
  • Retrieve the Fleet host ID used by other Fleet tools
  • Verify the device platform before requesting a macOS-specific action
Example rule:

When a user reports a device issue, use @Host Info to retrieve their device details. If the device is offline, inform the user and create a ticket for IT. If it is online, proceed with diagnostics.

Returns health data for the Fleet-managed device associated with the current user, including battery status, disk encryption state, MDM enrollment, OS update status, and uptime. Use it to verify security compliance or diagnose health-related issues.Tool name: @Host HealthInput fields:
  • serial_number (optional) - the device serial number; only provide it when the host cannot be found by the user’s email or when multiple devices match.
Output data:
  • hostHealth - the full health payload returned by Fleet for the device. The structure depends on the device platform and what Fleet reports.
Common use cases:
  • Verify that disk encryption is enabled before approving a software access request
  • Check MDM enrollment status during device onboarding
  • Diagnose battery or uptime issues a user has reported
  • Confirm OS update compliance before granting elevated access
Example rule:

When a user submits an access request, use @Host Health to check that their device has disk encryption enabled and MDM enrollment active. If either check fails, ask the user to resolve the issue before approving the request.

​
Run diagnostics

Returns the saved osquery queries configured in your Fleet instance, along with their IDs, descriptions, and authors. Use it to discover which queries are available before running one with @Run Saved Query.Tool name: @List Saved QueriesInput fields:
  • query_keywords (optional) - text to filter queries by name or description.
Output data:
  • queries - each query’s id, name, description, and author.
  • total - number of queries returned.
Common use cases:
  • Find the query ID to pass to @Run Saved Query
  • Show a user which diagnostic options are available
  • Confirm that a specific query exists before referencing it in a rule
Example rule:

When a user asks what diagnostic queries are available for their device, use @List Saved Queries to retrieve the full list and summarize the query names and descriptions.

Runs a saved Fleet query on the device associated with the current user and returns the results. Use @List Saved Queries first to find the query ID to pass.Tool name: @Run Saved QueryInput fields:
  • query_id (required) - the ID of the saved query to run; use @List Saved Queries to find it.
  • serial_number (optional) - the device serial number; only provide it when the host cannot be found by the user’s email or when multiple devices match.
Output data:
  • result - the raw query results returned by the device.
  • hostname - the hostname of the device the query ran on.
  • hostId - the Fleet host ID.
  • queryId - the ID of the query that was run.
Common use cases:
  • Run a disk-space query to diagnose storage complaints
  • Check running processes when a device is behaving unexpectedly
  • Pull OS version data as part of a troubleshooting workflow
  • Execute a security query during an incident investigation
Example rule:

When a user reports their device is slow, use @Host Info to confirm the device is online, use @List Saved Queries to find a relevant diagnostic query, then use @Run Saved Query to execute it. Summarize the results and suggest troubleshooting steps.

​
Recover admin access

Returns the managed local administrator password for a macOS device from Fleet.
The host must have its managed account password status set to Verified in Fleet before the password can be returned. If Fleet has not verified the password, the tool returns an error.
Tool name: @Get Managed Account PasswordInput fields:
  • serial_number (optional) - the device serial number; only provide it when the host cannot be found by the user’s email or when multiple devices match.
Output data:
  • password - the managed local administrator password.
  • updatedAt - the timestamp when the password was last rotated in Fleet.
  • hostname - the device hostname.
  • fleetHostId - the Fleet host ID.
Common use cases:
  • Help a macOS user regain local administrator access when they forget their password
  • Support a disk recovery scenario that requires a local admin login
  • Deliver a rotated admin password during endpoint troubleshooting
Example rule:

When a macOS user reports they are locked out of their local administrator account, use @Host Info to confirm the device, then use @Get Managed Account Password to retrieve the current admin password and share it with the user over a secure channel. If Fleet has not verified the password, create a ticket for IT to investigate.

A tool with no execution policy set runs without asking. When Copilot drafts a rule, it suggests Requires confirmation for write tools and Requires approval for delete tools, and you can change either per rule. See tool execution policies.

​
Setup

1

Install Fleet integration

Follow the Fleet setup guide to connect your Fleet instance to Ravenna.
2

Configure agent

Open your agent’s settings and add the Fleet tools you want it to use under Tools. An admin has to attach each tool before an agent or rule can call it.
3

Create rules

Write that reference Fleet tools using @ mentions.
4

Test tools

Test your rules on a real request to verify the tools work as expected.

​
Best practices

  • Look up the device first. Run @Host Info before @Run Saved Query or @Get Managed Account Password to confirm the device and retrieve the Fleet host ID.
  • Discover queries before running them. Use @List Saved Queries with a keyword filter to find the right query ID rather than hardcoding it in a rule.
  • Use health checks as compliance gates. Put @Host Health in access-request rules to verify disk encryption and MDM enrollment before approving.
  • Deliver passwords over a private channel. When a rule retrieves a managed account password with @Get Managed Account Password, have it send the result through a private Slack DM, not the ticket thread.
Learn more about configuring agents and writing effective rules
Last modified on September 29, 2026