How to Troubleshoot Your In-App AI Support SDK: A Debugging Guide
You've integrated ResolveKit into your iOS or Android app. The SDK is installed, the agent is initialized, and your users are starting to use it. Then something breaks — the agent gives wrong answers, the approval flow doesn't trigger, or sessions vanish from the operator dashboard.
This guide walks through the debugging toolkit ResolveKit provides and the systematic approach to diagnosing issues in production.
Start with the Trace Log
Every session your AI agent handles generates a trace log. This is your primary source of truth for understanding what happened inside a conversation.
In the ResolveKit operator dashboard, each session shows:
- User message — what the user typed
- Agent reasoning — the model's internal chain-of-thought (what it decided to do)
- Tool calls — which functions the agent invoked, with what parameters, and what results came back
- Response — what the agent sent back to the user
- Approval events — when the agent requested operator input and what the operator decided
If a session looks wrong, the trace log tells you exactly where the chain broke. Did the agent call the right tool? Did the tool return what you expected? Did the agent reason correctly from the result?
Common SDK Integration Issues
Agent doesn't respond to user input
Check three things:
1. Session initialization — Is `ResolveKit.startSession()` called when the user opens the support interface? If the session never starts, messages have nowhere to go.
2. Network reachability — The SDK communicates with your ResolveKit backend over HTTPS. If the device is offline or behind a restrictive proxy, requests will time out silently. Add a network status indicator before showing the support UI.
3. LLM provider quota — If you're using your own OpenAI or Anthropic API key, check whether you've hit a rate limit. The ResolveKit backend logs LLM errors with the error code returned by the provider.
Approval flow not triggering
The approval flow fires when the agent encounters a tool annotated with `approvalRequired: true`. If approvals aren't triggering:
1. Check the tool annotation — In your Swift or Kotlin tool definition, confirm `approvalRequired` is set to `true` for the relevant functions. Tools default to autonomous execution if not annotated.
2. Verify the policy mode — In your ResolveKit dashboard, the agent-level policy must be set to `approval_required` or the tool-specific override must be enabled. If the global mode is `autonomous`, no approvals will be requested regardless of tool annotations.
3. Operator availability — If no operator is online and the approval timeout has elapsed, the agent falls back to the configured fallback behavior. Check the operator presence indicator in the dashboard before testing approval flows.
Session not appearing in operator dashboard
Sessions appear in the dashboard when the SDK successfully establishes a session with the backend. If a session is missing:
1. Session ID mismatch — Each session has a unique ID generated on the client. If you're initializing sessions without persisting the session ID, you won't be able to look up past conversations. Store the session ID in UserDefaults or your own backend.
2. Backend URL misconfiguration — The SDK points to your ResolveKit backend URL. A trailing slash, a typo in the domain, or a missing port will cause all API calls to fail silently. Double-check `backendURL` in your SDK configuration.
3. Authentication token expired — If your backend requires authentication, ensure the token passed to `ResolveKit.configure()` is still valid. Expired tokens return 401 errors that the SDK logs but doesn't surface to users.
Reading Tool Call Errors
When a tool fails, the error appears in the trace log under the tool call entry. Common error codes:
| Error Code | Cause | Fix |
|---|---|---|
| `TOOL_NOT_FOUND` | Agent called a function name that doesn't exist in your registry | Check your Swift/Kotlin tool registry matches what the prompt expects |
| `PARAM_TYPE_MISMATCH` | Tool received wrong argument types | Verify the parameter names and types in your tool definition |
| `TOOL_EXECUTION_FAILED` | Function threw an exception | Check your backend logs for the stack trace |
| `APPROVAL_TIMEOUT` | Operator didn't respond within the timeout window | Increase timeout or ensure operator coverage |
Testing in the Simulator
When debugging locally, use the ResolveKit mock backend to test without hitting your production API. The mock backend simulates agent responses, tool calls, and approval flows with deterministic outputs.
For iOS, inject the mock configuration before running in the simulator:
ResolveKit.configure(
backendURL: "https://mock.resolvekit.local",
sessionToken: "test-token",
mockMode: true
)For Android:
ResolveKit.configure(
backendUrl = "https://mock.resolvekit.local",
sessionToken = "test-token",
mockMode = true
)The mock mode logs all tool calls and agent reasoning to the console, so you can verify the agent is calling the right functions with the right parameters before touching production.
Logging and Monitoring in Production
For production issues that are hard to reproduce, add custom logging to your tool implementations. Wrap tool functions with try-catch and emit events to your own logging backend:
func executeTool(name: String, params: [String: Any]) -> Any? {
let start = Date()
do {
let result = try performAction(name: name, params: params)
logEvent("tool_success", [
"tool": name,
"duration_ms": Date().timeIntervalSince(start) * 1000
])
return result
} catch {
logEvent("tool_error", [
"tool": name,
"error": error.localizedDescription
])
throw error
}
}This gives you structured data to correlate tool failures with user-reported issues.
The Debugging Mindset
In-app AI support is different from regular app debugging because the agent makes probabilistic decisions. It might work correctly 99 times and fail on the 100th for a reason that has nothing to do with your code — the model's reasoning drifted.
When something goes wrong:
1. Always check the trace log first — the answer is almost always there
2. Reproduce with the mock backend — if it works in mock mode but not production, it's an infrastructure issue
3. Isolate the tool — test individual tools in isolation to find which one is causing the failure
4. Check the policy layer — approval policies and agent mode settings are easy to misconfigure
ResolveKit's operator-first design means you have full visibility into every decision the agent makes. Use it.
---
Ready to ship faster? Get started with the ResolveKit SDK for iOS or Android in an afternoon, and start resolving issues in-app before they become tickets.