Navigation Tracking

Critical rule: session screen must match actual user screen.

Screen Context Emission

Emit on every real transition:

// Option 1: Direct step hint
AI.setKycStep("pan_entry")

// Option 2: Full screen state
AI.reportScreenState(
  screen = "pan_entry",
  screenId = "pan_input_screen",
  metadata = mapOf("step_index" to "2")
)

Screen ID Alignment

Keep stable screen IDs between app and backend:

// App uses same ID as registered schema
AI.registerScreenSchema(
  ScreenSchema(screenId = "pan_entry", ...)
)

// Navigation uses matching ID
AI.setKycStep("pan_entry")

Preventing Stale Context

Problem: Agent knows wrong screen after navigation.

Cause: Screen transition event not emitted.

Solution:

class PANEntryActivity : AppCompatActivity() {
  override fun onResume() {
    super.onResume()
    // Always emit on entry
    AI.setKycStep("pan_entry")
  }
}

Lazy Schema Push

When to use:

Schemas registered before init
kycis_lazy_schema_push_default = true

Behavior:

SDK sends screen_schema on setKycStep if schema registered
Sends screen_schema_lazy if no schema

NavHost(navController, startDestination = "phone_entry") {
  composable("phone_entry") {
    LaunchedEffect(Unit) { AI.setKycStep("phone_entry") }
    PhoneEntryScreen()
  }
  composable("otp_verify") {
    LaunchedEffect(Unit) { AI.setKycStep("otp_verify") }
    OtpVerifyScreen()
  }
}

Activities

class PhoneEntryActivity : AppCompatActivity() {
  override fun onResume() {
    super.onResume()
    AI.setKycStep("phone_entry")
  }
}

Fragments

class PhoneEntryFragment : Fragment() {
  override fun onResume() {
    super.onResume()
    AI.setKycStep("phone_entry")
  }
}

Backend KB Aliases

If screen ID doesn't match canonical keys:

Add alias in backend/app/kyc_knowledge.py:

SCREEN_KB_ALIASES = {
  "my_custom_pan_id": "pan_entry",  # Maps to SCREEN_KB["pan_entry"]
}

Verification

Check /api/activity:

event type matches navigation
screen field reflects current screen
No stale screen data after transitions

Common Issues

Issue	Cause	Fix
Agent on wrong screen	Missing `setKycStep`	Add to onResume
Stale context	Navigation without emission	Add screen tracking to all routes
Schema not found	ID mismatch	Align screen IDs