Overview
Droidrun provides real-time event streaming that gives you visibility into agent execution as it happens. This allows you to build UIs, logging systems, or monitoring tools that react to agent actions in real-time. Under the hood, Droidrun uses llama-index workflows - an event-driven orchestration system that powers the agent architecture.Basic Usage
Event Types
Workflow Coordination Events
Workflow Coordination Events
Used for workflow coordination between DroidAgent and its child agents.
Manager Events (Internal)
Manager Events (Internal)
Internal to ManagerAgent, streamed to frontend/logging.
Executor Events (Internal)
Executor Events (Internal)
Internal to ExecutorAgent, streamed to frontend/logging.
CodeAct Events (Internal)
CodeAct Events (Internal)
Internal to CodeActAgent, used in direct execution mode.
Scripter Events (Internal)
Scripter Events (Internal)
Internal to ScripterAgent, for off-device script execution.
Action Recording Events
Action Recording Events
Emitted when actions are performed, used for macro recording and trajectory tracking.
Visual & Telemetry Events
Visual & Telemetry Events
Common Patterns
Building a Live UI
Tracking Token Usage
Logging and Monitoring
Notes
Event Streaming Behavior
- Events are streamed in real-time as the agent executes
- Not all events are emitted in every execution (depends on mode and actions)
- All events are Pydantic models with full type safety
- The
handlerobject is async - always useawait handlerto get the final result
Event Emission by Mode
Reasoning Mode (reasoning=True) emits:
- Coordination:
ManagerInputEvent,ManagerPlanEvent,ExecutorInputEvent,ExecutorResultEvent - Internal Manager:
ManagerContextEvent,ManagerResponseEvent,ManagerPlanDetailsEvent - Internal Executor:
ExecutorContextEvent,ExecutorResponseEvent,ExecutorActionEvent,ExecutorActionResultEvent - Actions: All action recording events (
TapActionEvent,SwipeActionEvent, etc.) - Visual:
ScreenshotEvent,RecordUIStateEvent(when enabled)
reasoning=False) emits:
- Coordination:
CodeActExecuteEvent,CodeActResultEvent - Internal CodeAct:
TaskInputEvent,TaskThinkingEvent,TaskExecutionEvent,TaskExecutionResultEvent,TaskEndEvent - Actions: All action recording events
- Visual:
ScreenshotEvent,RecordUIStateEvent(when enabled)
<script> tags) emits:
- Coordination:
ScripterExecutorInputEvent,ScripterExecutorResultEvent - Internal Scripter:
ScripterInputEvent,ScripterThinkingEvent,ScripterExecutionEvent,ScripterExecutionResultEvent,ScripterEndEvent
- Finalization:
FinalizeEvent,ResultEvent - Telemetry:
DroidAgentInitEvent,PackageVisitEvent,DroidAgentFinalizeEvent(when telemetry enabled)
Event Categories
Coordination Events - Used for workflow routing between agents (minimal data)- Located in
droidrun/agent/droid/events.py - Examples:
ManagerPlanEvent,ExecutorResultEvent,ScripterExecutorResultEvent
- Located in agent-specific event files
- Examples:
ManagerPlanDetailsEvent,ExecutorActionEvent,TaskThinkingEvent
- Located in
droidrun/agent/common/events.py - Examples:
TapActionEvent,SwipeActionEvent,InputTextActionEvent
- Located in
droidrun/telemetry/events.py - Examples:
DroidAgentInitEvent,PackageVisitEvent,DroidAgentFinalizeEvent
Learn More
- LlamaIndex Workflows - The underlying orchestration system