Overview
App cards are markdown documents that contain:- Navigation tips: How to navigate through the app’s UI
- Common actions: Step-by-step guides for frequent tasks
- UI patterns: App-specific interaction patterns and conventions
- Known gotchas: Quirks, issues, or important notes about the app
- Search syntax: Special search operators or filters (for apps like Gmail, file managers, etc.)
How App Cards Work
Automatic Detection and Loading
- Package Detection: Droidrun monitors the current foreground app package name (e.g., “com.google.android.gm” for Gmail)
- Async Loading: When the package or instruction changes, Droidrun starts loading the app card in the background
- Caching: All providers use in-memory caching with
(package_name, instruction)
as cache keys - Prompt Injection: The app card content is injected into the Manager’s system prompt within
<app_card>
tags - Context-Aware Actions: The agent uses the app-specific guidance to perform actions more effectively
- App cards are loaded asynchronously to avoid blocking agent execution
- Loading starts when package/instruction changes are detected
- The Manager waits briefly (0.1s) for the background task to complete
- If loading isn’t ready, the Manager proceeds without the app card
- Subsequent requests will use the cached result
When App Cards Are Used
App cards are used by the Manager Agent in reasoning mode (--reasoning
flag or reasoning=True
in config). The Manager uses app cards to:
- Plan multi-step workflows that align with the app’s UI structure
- Make informed decisions about navigation and action sequences
- Understand app-specific features and capabilities
- Avoid common pitfalls and known issues
<app_card>
tags.
Built-in App Cards
Droidrun ships with app cards for popular apps. Currently included:App | Package Name | Features Covered |
---|---|---|
Gmail | com.google.android.gm | Navigation, search filters, composing emails, organizing messages, folder management |
droidrun/config/app_cards/
in the package directory for the latest list.
App Card Format
App cards are stored as markdown files and mapped to package names viaapp_cards.json
.
Directory Structure
Mapping File (app_cards.json)
Theapp_cards.json
file maps Android package names to markdown files:
Markdown File Structure
App card markdown files should follow this structure:Example: Gmail App Card
Here’s the complete Gmail app card (gmail.md
):
Creating Custom App Cards
Step 1: Find the Package Name
To create an app card, you first need the app’s package name. Using ADB:- Gmail:
com.google.android.gm
- Chrome:
com.android.chrome
- WhatsApp:
com.whatsapp
- Instagram:
com.instagram.android
- Facebook:
com.facebook.katana
- YouTube:
com.google.android.youtube
- Google Maps:
com.google.android.apps.maps
Step 2: Create the Markdown File
Create a markdown file in your app cards directory:Step 3: Update app_cards.json
Add an entry toapp_cards.json
:
Step 4: Test the App Card
Run Droidrun with the app and verify the app card is loaded:Configuration
App cards are configured inconfig.yaml
under the agent.app_cards
section:
enabled: false
. For server/composite modes, add server_url
configuration.
Providers
LocalProvider (default): Loads from local filesystem. Setmode: local
.
ServerProvider: Fetches from remote HTTP via POST {server_url}/app-cards
. Set mode: server
.
CompositeProvider: Tries server first, falls back to local. Set mode: composite
.
Related Documentation
- CLI Usage - Droidrun CLI command reference
- Configuration - Configuration system details
- Agent Architecture - How agents use app cards
- Manager Agent - Agent that uses app cards
Improve your agent’s performance with well-crafted app cards!