Skip to content

best-practices.md

Latest commit

 

History

History
82 lines (66 loc) · 3.18 KB

best-practices.md

File metadata and controls

82 lines (66 loc) · 3.18 KB
Raw

Best Practices & Troubleshooting

Tips for building robust and reliable web agents using the Agentic WebView SDK.

1. Page Lifecycle States

Understanding the PageLifecycleState is key to knowing when it's safe to interact with the page.

State Description
IDLE Initial state before any navigation has started.
LOADING Page is currently loading.
INTERACTIVE DOM is ready, but sub-resources (images, scripts) might still be loading.
COMPLETE Page is fully settled and stable. Capture state now.
ERROR A navigation error occurred (e.g., 404, DNS).
CRASHED The WebView renderer process crashed. 
controller.state.collect { state ->
    if (state?.pageState == PageLifecycleState.COMPLETE) {
        // Safe to capture state or execute actions
    }
}

2. Comprehensive Error Handling

The SDK uses AgentResult to provide detailed feedback on why an operation failed.

Error Type Description
ElementNotFound The requested agentId does not exist in the current DOM.
ElementOccluded The element is covered by a modal, overlay, or another element.
NavigationFailed Page failed to load. Includes the httpCode if available.
JsEvaluationFailed The internal JS engine failed (check logs for details).
JsEvaluationTimeout JavaScript execution exceeded the configured jsEvaluationTimeoutMs.
ScreenshotFailed Screenshot capture failed (e.g., PixelCopy error).
PageNotReady The page is not in a valid state for the operation. Includes currentState.
FileUploaderDetected Clicking a file input is blocked (requires native file picker).
NoNavigationHistory GoBack or GoForward called when there's no history.
Timeout The operation (navigation or stability) exceeded the config timeout.
WebViewCrashed The renderer process died.

Example:

when (val result = controller.executeAction(action)) {
    is AgentResult.Success -> { /* Proceed */ }
    is AgentResult.Error -> {
        val error = result.error
        if (error is AgentError.ElementOccluded) {
            println("Element ${error.agentId} is hidden by ${error.occludedBy}")
        }
    }
}

3. Debugging

Enable SDK Logging

Set enableDebugLogging to true in your config to see detailed logs in Logcat. Logs appear under the AgenticSDK:<component> tag pattern (e.g., AgenticSDK:Controller, AgenticSDK:WebView, AgenticSDK:Bridge).

val config = AgenticWebViewConfig.Builder()
    .setEnableDebugLogging(true)
    .build()

Chrome Remote Debugging

Since the SDK uses a standard WebView, you can inspect the page (including the injected scripts) using Chrome DevTools.

In your Activity/Application:

if (BuildConfig.DEBUG) {
    WebView.setWebContentsDebuggingEnabled(true)
}

Then open chrome://inspect in your desktop browser.

4. Performance Tips

  • Limit DOM Nodes: Use maxDomElements to keep the accessibility tree small and save LLM tokens.
  • Viewport Expansion: Avoid setting viewportExpansion = -1 (full page) unless absolutely necessary, as it can significantly slow down state capture on long pages.