Skip to content
Xgodo Docs← Back to app

Automation API

Android device automation

agent.utils

Interface

Utility functions, job management, and file operations

Access these utilities through agent.utils. Includes random gesture helpers, event callbacks, job task management, server connectivity, and comprehensive file operations.

AgentUtils Interface Overview
TypeScript
interface AgentUtils {
  // Gesture helpers
  randomClick(x1: number, y1: number, x2: number, y2: number): void;
  randomSwipe(x1: number, y1: number, x2: number, y2: number, direction: Direction): void;


  // Server connectivity
  isServerReachable(): Promise<{ reachable: true } | { reachable: false; error: string }>;


  // Event callbacks (for notifications, see agent.notifications)
  setNetworkCallback(callback: NetworkCallback | null): void;
  toastCallback: ToastCallback | null;


  // Step tracking & debugging
  outOfSteps: {
    storeScreen(screen: AndroidNode, stage: string, screenState: string, remainingSteps: number, screenshotRecord: ScreenshotRecord): Promise<void>;
    submit(type: "outOfSteps" | "timeout" | "debug"): Promise<SubmitResult>;
  };


  // Job task management
  job: {
    submitTask(status: AutomationStatus, data: Record<string, any>, finish: boolean, files: File[]): Promise<TaskResult>;
    useAnotherTask(): Promise<TaskInfo | null>;
    getCurrentTask(): Promise<CurrentTaskResult>;
  };


  // Bucket storage (device+job scoped)
  bucket: {
    get(): Promise<BucketResult>;
    set(data: Partial<Bucket>): Promise<BucketResult>;
  };


  // Device bucket storage (device-only scoped)
  deviceBucket: {
    get(): Promise<DeviceBucketResult>;
    set(data: Record<string, any>): Promise<DeviceBucketResult>;
  };


  // File operations
  files: AgentFiles;
}

Note

For notification callbacks, see agent.notifications.

Quick Examples

Human-like Interactions
TypeScript
// Random tap within a button area (more human-like)
const button = screen.findTextOne("Submit");
if (button) {
  button.randomClick();
}
Job Task Processing
TypeScript
// Get current task and submit results
const task = await agent.utils.job.getCurrentTask();
if (task.success) {
  const proof = task.job_proof;


  // ... perform automation ...


  await agent.utils.job.submitTask(
    "success",
    { orderId: "12345", completed: true },
    true, // Final submission
    []
  );
}
File Operations
TypeScript
// Read and process files
const files = agent.utils.files.list("/sdcard/Download");
for (const file of files) {
  if (file.name.endsWith(".json")) {
    const content = agent.utils.files.readFullFile(file.path);
    const data = JSON.parse(content);
    console.log(data);
  }
}