Macro Handler

Macro Handler

Android Automation Platform

Object MethodTouch and Actions

Agent.run(blockId)

Runs the approved routine or plan of an enabled Agent block saved in this macro. Uses the same macro-start consent, stop rules and failure behavior as the block, returning a structured result.

Documented for app version 1.0.50Updated:

Detailed Explanation

This section explains when to use the API, how to call it, and which structures it works best with in production flow.

How To Call It

Agent is a global table: call its functions with a dot (Agent.<method>(...)), not a colon. Requires Macro Handler 1.0.51 or later.

When To Use It

Use this to combine a saved Agent/Routine step with code-editor conditions and loops. This call does not teach or approve a new routine.

Parameters and Return

Agent.run(blockId): pass the literal string id of an enabled Agent block saved in this macro. Launch admission resolves that id; computed ids or function aliases do not create grants. Returns ok, outcome, taps, detail, kind (routine/plan/none). Settings come from the saved block and approved plan; extra arguments do not override them.

Best Combined With

Check outcome as well as ok: completed_unverified and completed_with_skips can also return ok=true. Stop on failure raises AGENT_MACRO_STOP; Continue returns the result table. A user stop also stops the macro. Previews and observed tests do not start Agent actions.

Example Usage

The snippet below is a starter pattern that can be applied directly in runtime flow.

lua
Try in Editor →
-- Use a literal id from an enabled Agent block saved in this macro.
-- Its routine/plan must be approved; launch consent is still required.
local result = Agent.run("saved_agent_block_id")
if result.ok then
  print(result.outcome, result.taps)
else
  print(result.outcome, result.detail, result.kind)
end

Copyable Progressive Examples

From foundation to combined usage, each level is provided as a separate code block so you can copy the level you need and adapt it directly.

Foundation

Shows the shortest direct way to call the API.

Foundation
lua
Try in Editor →
-- Use a literal id from an enabled Agent block saved in this macro.
-- Its routine/plan must be approved; launch consent is still required.
local result = Agent.run("saved_agent_block_id")
if result.ok then
  print(result.outcome, result.taps)
else
  print(result.outcome, result.detail, result.kind)
end

Simple

Wraps the base call with minimal flow control.

Simple
lua
Try in Editor →
local stepOk = true
-- Use a literal id from an enabled Agent block saved in this macro.
-- Its routine/plan must be approved; launch consent is still required.
local result = Agent.run("saved_agent_block_id")
if result.ok then
  print(result.outcome, result.taps)
else
  print(result.outcome, result.detail, result.kind)
end
if stepOk then
  wait(200)
end

Practical Flow

A practical pattern for real macros with pcall, logging, and guards.

Practical Flow
lua
Try in Editor →
local ok, err = pcall(function()
  -- Use a literal id from an enabled Agent block saved in this macro.
  -- Its routine/plan must be approved; launch consent is still required.
  local result = Agent.run("saved_agent_block_id")
  if result.ok then
    print(result.outcome, result.taps)
  else
    print(result.outcome, result.detail, result.kind)
  end
end)

if not ok then
  print("API step failed: Agent.run: " .. tostring(err))
  requestStop()
end

Detailed

This level packages the API into a reusable helper with error reporting.

Detailed
lua
Try in Editor →
-- The saved plan, launch consent and run-bound grant are shared with the no-code Agent block.
local function run_run_step()
  -- Use a literal id from an enabled Agent block saved in this macro.
  -- Its routine/plan must be approved; launch consent is still required.
  local result = Agent.run("saved_agent_block_id")
  if result.ok then
    print(result.outcome, result.taps)
  else
    print(result.outcome, result.detail, result.kind)
  end
end

local ok, err = pcall(run_run_step)
if not ok then
  toast("Step failed")
  print(err)
end

Combined

Combines the API with related structures to form a more realistic workflow.

Combined
lua
Try in Editor →
-- Use a literal id from an enabled Agent block saved in this macro.
-- Its routine/plan must be approved; launch consent is still required.
local result = Agent.run("saved_agent_block_id")
if result.ok then
  print(result.outcome, result.taps)
else
  print(result.outcome, result.detail, result.kind)
end