Agent tools

Use Fleet agent tools in Ravenna rules to look up devices, check health status, and run osquery diagnostics during automated ticket handling.

Fleet provides AI agent tools for device management, health monitoring, and diagnostic workflows. Reference these tools in agent rules using @ mentions to enable automated device troubleshooting and information retrieval.

---

Available tools

Look up device

Retrieves device information for a user including hostname, serial number, platform, and online status. Use this tool to identify which device to target for further operations.

Tool name: @Look up device with Fleet

Common use cases:

• Find user’s device before running diagnostics
• Verify device ownership
• Get device identifiers for troubleshooting
• Check if device is online

Example rule:

When a user reports device issues, use @Look up device with Fleet to get their device information. If the device is offline, inform the user and create a ticket for IT support. If online, proceed with diagnostics.

CopiedCopy prompt

Check device health

Checks comprehensive device health metrics including battery status, disk encryption, MDM enrollment, OS updates, and uptime. Returns detailed health information for security and compliance validation.

Tool name: @Check device health with Fleet

Common use cases:

• Verify security compliance before access approval
• Diagnose device health issues
• Check disk encryption status
• Validate MDM enrollment

Example rule:

When approving access requests, use @Check device health with Fleet to verify the device meets security requirements. If disk encryption is disabled or OS updates are needed, inform the user they must address these issues before approval.

CopiedCopy prompt

Run query

Executes predefined diagnostic queries on user devices to gather specific system information. Supports multiple query types for troubleshooting and analysis.

Tool name: @Run query with Fleet

Available query types:

• System information
• OS version details
• Logged in users
• Running processes
• Network interfaces
• Disk space usage
• Recent items

Common use cases:

• Advanced device troubleshooting
• Custom system information gathering
• Security investigation queries
• Performance diagnostics

Example rule:

When a user reports slow device performance, use @Look up device with Fleet to get their device, then @Run query with Fleet to check running processes and disk space. Analyze the results and provide troubleshooting steps based on what you find.

CopiedCopy prompt

List saved queries

Retrieves the list of available saved queries configured in Fleet. Use this to discover which diagnostic queries are available for troubleshooting.

Tool name: @List saved queries with Fleet

Common use cases:

• Discover available diagnostic queries
• Reference query names in troubleshooting
• Guide users on diagnostic capabilities

Get managed account password

Retrieves 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.

Tool name: @Get managed account password with Fleet

Output fields:

• EndpointManagedAccountPassword - The managed local administrator password
• EndpointManagedAccountPasswordUpdatedAt - Timestamp when the password was last rotated in Fleet

Common use cases:

• Help a macOS user regain administrator access when they forget their local password
• Support disk recovery scenarios that require a local admin login
• Deliver a rotated admin password to a requester during endpoint troubleshooting

Example rule:

When a macOS user reports they are locked out of their local administrator account, use @Look up device with Fleet to confirm the device, then use @Get managed account password with Fleet 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.

CopiedCopy prompt

---

Setup

1. Install Fleet integration

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

2. Configure agent

   Navigate to your agent’s settings and ensure Fleet tools appear in the Tools section under Capabilities.

3. Create rules

   Write rules that reference Fleet tools using @ mentions.

4. Test tools

   Test your rules in a controlled environment to verify tools work as expected.

---

Best practices

• Always use @Look up device with Fleet before running queries to ensure you have the correct device
• Combine multiple tools in a single rule for comprehensive diagnostics
• Provide clear instructions to users based on tool results
• Check device online status before running queries
• Consider security compliance checks for access request workflows

Learn more about configuring agents and writing effective rules