Power off a device

Tool Name: airdroid_business_power_off_device

Risk Level: 🔴 High Risk

Execution Mode: ⏳ Asynchronous

Category: Remote Commands

Quick Start (Copy & Use)

One-liner: Remotely power off a specified device

What you need: DeviceId (device ID), Confirm (must be set to true), Reason (shutdown reason)

Success criteria: StatusCode = 200 and ErrorMessage is an empty string; returns Pid for tracking

What to do next: Use Get an Activity Log with the Pid to poll execution status

Minimal request example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Scheduled maintenance shutdown"
}

Minimal response example:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Scheduled maintenance shutdown

Scenario: Power off devices during a scheduled maintenance window to conserve energy or perform hardware servicing

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Scheduled maintenance shutdown for hardware servicing"
}

Recipe 2: End-of-day power saving

Scenario: Power off kiosk or display devices at the end of business hours to save energy

{
  "DeviceId": "abc123def456",
  "Confirm": true,
  "Reason": "End-of-day shutdown for energy conservation"
}

Recipe 3: Track shutdown status with Pid

Scenario: After issuing a power off command, confirm whether the device has been shut down

1. Call Power off a Device to get the Pid
2. Use the Get an Activity Log tool to query status:

{
  "Pid": "1770854462319857000"
}

Polling logic:

• Progress = "Executing" → continue polling (interval 5-10 seconds)
• Progress = "Success" → shutdown succeeded
• Progress = "Failure" → check the FailReason field

1. Overview

1.1 Description

Remotely power off a device managed by AirDroid Business. After execution, the device will be completely powered off and cannot be remotely powered on. Physical intervention is required to restart the device.

1.2 When to Use

• Scheduled maintenance: Power off devices during planned maintenance windows for hardware servicing
• Energy conservation: Shut down kiosk or display devices during off-hours
• Security response: Power off a compromised device to prevent further damage
• Device decommission: Shut down a device before physically retrieving it

1.3 Execution Mode & Response

This operation is asynchronous — after the command is sent, the device may take seconds to minutes to respond.

• Return value: Pid (activity log ID)
• Tracking method: Use the Get an Activity Log tool with the Pid to query execution status
• Prerequisite: The device must be online to receive the command
• Critical: Once powered off, the device cannot be remotely powered back on. Physical access is required to restart.

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Comparison with Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier, specifying the target device to power off.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Devices tool; use the device_id field from the response
  2. Obtained via the Get a Device by Name tool for exact name lookup
• How to fill in a GI node:
  • Constant: Enter the device ID string directly, e.g. fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Map from the Get All Devices node's Devices[0].device_id field
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

`Confirm`

Safety confirmation parameter. This is a guardrail parameter for high-risk operations, preventing accidental execution of destructive actions.

• Type: bool
• Default: false (will not execute)
• Must be set to true to execute: If false, the operation will be rejected with an error
• How to fill in a GI node:
  • Constant: Only set to true after receiving explicit user consent
• Example:

  true

⚠️ Important: The agent must ask the user for confirmation before calling this tool. Only set this parameter to true after receiving explicit user approval.

`Reason`

Reason for shutting down the device.

• Type: string
• Format: Non-empty string; a clear description is recommended
• Why required: Logged for auditing purposes to support tracking and compliance
• How to fill in a GI node:
  • Constant: e.g. "Scheduled maintenance shutdown"
  • Upstream reference: Obtain from user input or a ticketing system
• Example:

  "Scheduled maintenance shutdown"

⚠️ Important: The Reason parameter must be provided by the user. The agent should not fabricate reasons.

2.3 Parameter Combination Logic

• All three parameters are required
• Confirm must be true and Reason must be non-empty for the operation to execute
• If Confirm = false, returns StatusCode = 200 with an ErrorMessage indicating confirmation is required

3. Outputs

3.1 Response Examples

Success response:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Confirmation not passed:

{
  "Pid": "",
  "StatusCode": 200,
  "ErrorMessage": "Confirm must be set to true to execute this destructive operation."
}

Parameter error response:

{
  "Pid": "",
  "StatusCode": -1,
  "ErrorMessage": "Invalid device_id. Obtain via 'Get All Devices' or 'Get a Device by Name' tool."
}

Network error response:

{
  "Pid": "",
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

3.2 Field Descriptions

3.3 Pid Tracking

Use the returned Pid with the Get an Activity Log tool to track execution status:

4. Examples

4.1 Basic Example: Scheduled maintenance shutdown

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "Scheduled maintenance shutdown"
}

Response:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Track status after shutdown

Step 1: Call the power off endpoint

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": "End-of-day energy conservation shutdown"
}

Step 2: Use the returned Pid to query the activity log

{
  "Pid": "1770854462319857000"
}

Step 3: Determine completion based on Progress

• Executing → wait 10 seconds and query again
• Success → shutdown complete
• Failure → check FailReason for root cause

4.3 Error Example: Confirmation not provided

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": false,
  "Reason": "Test shutdown"
}

Response:

{
  "Pid": "",
  "StatusCode": 200,
  "ErrorMessage": "Confirm must be set to true to execute this destructive operation."
}

4.4 Error Example: Missing reason

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d",
  "Confirm": true,
  "Reason": ""
}

Response:

{
  "Pid": "",
  "StatusCode": 200,
  "ErrorMessage": "Reason is required for audit trail."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The agent should decide how to handle based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Tips

• Confirm device is online: Check device status before powering off to avoid sending commands to offline devices
• Batch operation intervals: When batch powering off, add a 2-3 second delay between each call to reduce server load

6.2 Security Considerations

⚠️ High-Risk Operation Warning: This operation will power off the device and it cannot be remotely powered back on. Physical intervention is required to restart.

Pre-execution checklist:

1. ☐ Confirm the device is online
2. ☐ Confirm the correct target device (avoid powering off the wrong device)
3. ☐ Notify the device holder (if applicable)
4. ☐ Confirm no critical operations are running on the device
5. ☐ Understand the irreversibility — the device cannot be remotely powered back on
6. ☐ Ensure physical access is available if the device needs to be restarted

6.3 Idempotency

Idempotency: Non-idempotent. Each call triggers a new shutdown command.

• If the device is already in the shutdown process, a new shutdown command may be ignored or overridden
• Avoid blind retries on timeout — instead use Get an Activity Log with the Pid to check status

6.4 Async Operation Tracking

Use the returned Pid with Get an Activity Log to track execution status:

Polling recommendations:

• Interval: 5-10 seconds
• Max polling attempts: 12 (approx. 1-2 minutes)
• On timeout: Prompt the user to manually check device status

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Scheduled Maintenance Shutdown Pattern

Scenario: Power off devices in a specific group during a maintenance window

Tool chain:

Get All Devices → Power off a Device → Get an Activity Log (poll)

Steps:

1. Call Get All Devices with Keyword={"group_name":"maintenance-group"} and SelectedColumns=["device_id","device_name","online"] to get the target device list
2. Ask the user for confirmation before proceeding
3. Iterate through online devices and call Power off a Device for each (recommended 2-3 second interval)
4. Collect all Pid values and use Get an Activity Log to batch-track status

8.2 Security Incident Response Pattern

Scenario: Power off a compromised device to prevent further damage

Tool chain:

Get a Device by Name → Power off a Device → Get an Activity Log (poll)

Steps:

1. Call Get a Device by Name to find the compromised device's device_id
2. Ask the user for confirmation, explaining the device cannot be remotely restarted
3. Call Power off a Device with a clear reason (e.g., "Security incident: suspected unauthorized access")
4. Use Get an Activity Log with the Pid to confirm the shutdown was successful

8.3 End-of-Day Batch Shutdown Pattern

Scenario: Power off all kiosk devices at the end of business hours

Tool chain:

Get All Devices (filter by group + online) → [Loop] Power off a Device → Get an Activity Log

Steps:

1. Call Get All Devices with Keyword={"online":"Online"} to get all online devices
2. Filter devices by group name in the response if needed
3. Ask the user for confirmation for the entire batch
4. Iterate and call Power off a Device for each device (2-3 second interval)
5. Collect all Pid values and batch-track using Get an Activity Log

Appendix Reference:

• Field Reference: https://www.goinsight.ai/tools/field-reference/
• Error Code Quick Reference: https://www.goinsight.ai/tools/error-codes/