# Kai Resolution Agent

Kai is Kaana's AI-powered resolution agent that analyzes System Feed signals and helps fix issues directly in your connected billing and CRM systems.

### Overview

When you encounter a signal in the System Feed, Kai can analyze the underlying problem, identify root causes, and propose specific actions to resolve it. For automated actions, Kai can execute fixes directly in your connected systems.

### How Kai Thinks About Problems

Kai uses intelligent anomaly detection to focus on issues that truly matter to your business. Rather than flagging every small error, Kai identifies patterns that indicate systemic, abnormal, or high-risk behavior.

#### What Kai Looks For (Anomalies)

| Anomaly Type               | Example                                       |
| -------------------------- | --------------------------------------------- |
| **Failure rate spikes**    | Payment failures jump from 2% to 20%          |
| **Volume changes**         | Invoice generation drops 50% overnight        |
| **Multi-entity patterns**  | Same error affecting multiple customers       |
| **System inconsistencies** | Usage recorded but no charges created         |
| **Post-change failures**   | Billing errors starting after a config update |

#### What Kai Ignores (Not Anomalies)

* A single customer's card decline due to insufficient funds
* Isolated expired card errors
* One-off data entry mistakes

This approach ensures Kai helps you address root causes rather than chasing individual symptoms.

### Understanding Root Causes

Kai understands how billing systems work and fixes problems at the right level. Billing operations flow through a sequence:

```
Usage → Rating → Billing → Invoices → Payments
```

If a billing run fails, Kai knows that no invoices were created yet, so it will recommend retrying the billing run - not individual invoices. This prevents wasted effort on symptoms while the root cause remains.

For example:

* If **usage processing** fails, invoices can't be generated - Kai fixes the usage first
* If **credentials are invalid**, payments will fail - Kai recommends refreshing credentials before retrying payments
* If a **billing run** fails, affected invoices don't exist yet - Kai retries the billing run, not invoices

### Starting a Resolution Session

1. Navigate to the **System Feed**
2. Open any signal that requires action
3. Click **Resolve with Kai** to start an agent session
4. Kai will analyze the signal and present its findings

### The Resolution Process

#### Step 1: Analysis

Kai analyzes the signal and provides:

* **Root Cause** - What's actually causing the problem
* **Impact Assessment** - How this affects your business
* **Affected Systems** - Which integrations and entities are involved
* **Confidence Level** - How certain Kai is about the diagnosis

#### Step 2: Proposed Actions

Based on the analysis, Kai proposes specific actions to resolve the issue. Each action includes:

* **Description** - What the action does
* **Type** - Automated (Kai executes) or Manual (you execute)
* **Target System** - Which integration will be affected
* **Risk Level** - Low, Medium, or High
* **Expected Outcome** - What should happen after execution
* **Detailed Steps** - Specific operations that will be performed

#### Step 3: Confirmation

Review each proposed action before execution. You control what Kai does:

* Select which actions to approve
* Skip actions you want to handle manually
* Cancel the session if you prefer to address it differently

#### Step 4: Execution

For approved automated actions, Kai:

1. Connects to your integration
2. Executes the specific API calls
3. Records the system response
4. Reports success or failure with details

#### Step 5: Results

After execution, you see detailed results:

**Successful Actions:**

* Green checkmark with "Action Completed"
* System response data (invoice numbers, IDs, status, amounts)
* Confirmation of what changed

**Failed Actions:**

* Red X with "Action Failed"
* Error message explaining what went wrong
* Full API response for troubleshooting

### Understanding the Action Timeline

Kai presents actions in a visual timeline format:

| Stage               | Color  | Description                          |
| ------------------- | ------ | ------------------------------------ |
| **Issue**           | Red    | The problem being addressed          |
| **Action**          | Amber  | The resolution action to take        |
| **Steps**           | Blue   | Detailed steps involved              |
| **API Call**        | Purple | The specific system API being called |
| **Expected Result** | Green  | What should happen after execution   |

### Action Types

Actions are categorized by execution method:

#### Automated Actions

Kai can execute these directly in your connected systems:

* No manual intervention required
* Real-time execution with immediate feedback
* Full audit trail of changes made

#### Manual Actions

Some situations require your intervention:

* Actions that need human judgment
* Steps that must be performed in the external system's UI
* Escalations to support teams or customers

For manual actions, Kai provides detailed instructions on what to do.

### Available Resolution Actions

Kai can perform a variety of actions across your connected billing systems:

#### Integration Actions

| Action                  | Description                            |
| ----------------------- | -------------------------------------- |
| **Refresh Credentials** | Update API tokens or OAuth connections |
| **Verify Integration**  | Test that the connection is working    |

#### Usage & Rating Actions

| Action                    | Description                     |
| ------------------------- | ------------------------------- |
| **Reprocess Usage Batch** | Resubmit failed usage records   |
| **Replay Usage Events**   | Resend usage events for rating  |
| **Recalculate Charges**   | Recalculate pricing for charges |

#### Billing Run Actions

| Action                 | Description                     |
| ---------------------- | ------------------------------- |
| **Retry Billing Run**  | Re-execute a failed billing run |
| **Cancel Billing Run** | Cancel a stuck billing run      |

#### Invoice Actions

| Action                | Description                 |
| --------------------- | --------------------------- |
| **Retry Invoice**     | Regenerate a failed invoice |
| **Backfill Invoices** | Create missing invoices     |
| **Void Invoice**      | Cancel an erroneous invoice |

#### Payment Actions

| Action                  | Description                         |
| ----------------------- | ----------------------------------- |
| **Retry Payment**       | Attempt payment collection again    |
| **Retry Payment Batch** | Re-run a failed payment batch       |
| **Pause Payment Runs**  | Temporarily stop payment collection |

#### Subscription Actions

| Action                      | Description                           |
| --------------------------- | ------------------------------------- |
| **Sync Subscription State** | Align subscription status with source |
| **Repair Entitlements**     | Fix entitlement mismatches            |

#### Configuration Actions

| Action                     | Description                         |
| -------------------------- | ----------------------------------- |
| **Review Configuration**   | Manual review of system settings    |
| **Rollback Configuration** | Revert recent configuration changes |

#### Escalation Actions

| Action                  | Description                     |
| ----------------------- | ------------------------------- |
| **Escalate to Support** | Create a support ticket         |
| **Contact Customer**    | Reach out to affected customers |

Kai prioritizes actions based on root cause analysis. For example, if there's an authentication issue, Kai will recommend fixing credentials before trying to retry payments.

### Activity Tracking

All resolution activity is recorded in the signal's Activity section:

| Entry                       | Icon        | Meaning                                     |
| --------------------------- | ----------- | ------------------------------------------- |
| **AI Resolution Completed** | Green robot | All actions succeeded                       |
| **AI Resolution Failed**    | Red robot   | One or more actions failed                  |
| **Marked as In Progress**   | Play icon   | Agent session started                       |
| **Resolved**                | Checkmark   | Signal automatically resolved after success |

When all automated actions complete successfully, Kai automatically marks the signal as "Resolved."

### Permissions

Access to Kai Resolution requires specific permissions:

| Permission                     | What It Allows                                |
| ------------------------------ | --------------------------------------------- |
| **view\_agent\_remediation**   | View resolution sessions and proposed actions |
| **update\_agent\_remediation** | Start sessions and approve/execute actions    |

Administrators can configure these permissions through role management.

### Plan Requirements

* **Advanced Plan** - AI resolution requires the Advanced plan or higher
* The **agentAI** plan feature must be enabled

### Integration Requirements

For Kai to execute actions:

* **Active Integration** - The connected system must be active and healthy
* **Valid Credentials** - API credentials must be current and have write permissions
* **Sufficient Permissions** - The integration's API key must have permission for the specific operations

### Best Practices

#### Before Starting a Session

* Review the signal details and affected entities
* Ensure your integration credentials are valid
* Understand the potential business impact

#### During Confirmation

* Read each proposed action carefully
* Consider the risk level for high-impact actions
* Start with low-risk actions if you're uncertain

#### After Execution

* Review the results for each action
* Check the affected records in your source system
* Add comments to the signal documenting what was done

### Troubleshooting

#### "Session failed to start"

* Check that your integration is active
* Verify API credentials are still valid
* Ensure you have the required permissions

#### "Action execution failed"

* Review the error message for specific details
* Check if the entity still exists in the source system
* Verify the integration has write permissions
* Try the action manually in the source system

#### "No actions proposed"

* Kai may not have enough data to propose actions
* The issue may require manual investigation
* Check if the signal has sufficient context

### Data Privacy & Security

* Kai only accesses data necessary for analysis and execution
* All actions are logged in the audit trail
* Execution results are stored securely within your tenant
* Kai respects your integration's permission boundaries