# Kai Resolution Agent

Kai resolution agent session management and action execution

## Start agent session

> Initiates a new Kai resolution agent session for a signal. \
> The agent will analyze the signal and prepare to propose resolution actions.\
> Requires create\_agent\_remediation permission and agentAI plan feature.<br>

```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}}}},"paths":{"/concierge/alerts/{id}/agent-session":{"post":{"tags":["Kai Resolution Agent"],"summary":"Start agent session","description":"Initiates a new Kai resolution agent session for a signal. \nThe agent will analyze the signal and prepare to propose resolution actions.\nRequires create_agent_remediation permission and agentAI plan feature.\n","operationId":"startAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Signal ID to create session for","schema":{"type":"integer"}}],"responses":{"201":{"description":"Agent session created","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"$ref":"#/components/schemas/AgentSession"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or plan feature not available"},"404":{"description":"Signal not found"},"500":{"description":"Server error"}}}}}}
```

## Get agent session status

> Returns the current status and details of an agent session. Requires view\_agent\_remediation permission.

```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentSessionDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSession"},{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}},"executionResults":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ExecutionResult"}},"error":{"type":"string","nullable":true,"description":"Error message if session failed"},"updatedAt":{"type":"string","format":"date-time"}}}]},"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}},"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}},"ExecutionResult":{"type":"object","required":["actionId","success"],"properties":{"actionId":{"type":"string","description":"ID of the executed action"},"success":{"type":"boolean","description":"Whether the action executed successfully"},"response":{"type":"object","nullable":true,"description":"API response from the target system"},"error":{"type":"string","nullable":true,"description":"Error message if execution failed"},"executedAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Execution duration in milliseconds"}}}}},"paths":{"/concierge/agent-sessions/{id}":{"get":{"tags":["Kai Resolution Agent"],"summary":"Get agent session status","description":"Returns the current status and details of an agent session. Requires view_agent_remediation permission.","operationId":"getAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Agent session details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSessionDetail"}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```

## Generate action proposals

> Triggers Kai to analyze the signal and generate proposed resolution actions.\
> The agent performs root cause analysis and identifies systemic issues rather than isolated failures.\
> Actions are categorized as automated (Kai can execute) or manual (requires user intervention).\
> Requires create\_agent\_remediation permission and agentAI plan feature.<br>

```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}}}},"paths":{"/concierge/agent-sessions/{id}/propose":{"post":{"tags":["Kai Resolution Agent"],"summary":"Generate action proposals","description":"Triggers Kai to analyze the signal and generate proposed resolution actions.\nThe agent performs root cause analysis and identifies systemic issues rather than isolated failures.\nActions are categorized as automated (Kai can execute) or manual (requires user intervention).\nRequires create_agent_remediation permission and agentAI plan feature.\n","operationId":"proposeActions","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Actions proposed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"session":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string","enum":["awaiting_confirmation"]},"alertId":{"type":"integer"},"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}}}}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```

## Execute approved actions

> Executes the specified resolution actions that the user has approved.\
> The agent will make API calls to the relevant billing/payment systems and report results.\
> Requires execute\_agent\_remediation permission and agentAI plan feature.<br>

```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}},"schemas":{"ExecutionResult":{"type":"object","required":["actionId","success"],"properties":{"actionId":{"type":"string","description":"ID of the executed action"},"success":{"type":"boolean","description":"Whether the action executed successfully"},"response":{"type":"object","nullable":true,"description":"API response from the target system"},"error":{"type":"string","nullable":true,"description":"Error message if execution failed"},"executedAt":{"type":"string","format":"date-time"},"duration":{"type":"integer","description":"Execution duration in milliseconds"}}},"AgentSessionDetail":{"allOf":[{"$ref":"#/components/schemas/AgentSession"},{"type":"object","properties":{"analysis":{"$ref":"#/components/schemas/AgentAnalysis"},"proposedActions":{"type":"array","items":{"$ref":"#/components/schemas/ProposedAction"}},"executionResults":{"type":"array","nullable":true,"items":{"$ref":"#/components/schemas/ExecutionResult"}},"error":{"type":"string","nullable":true,"description":"Error message if session failed"},"updatedAt":{"type":"string","format":"date-time"}}}]},"AgentSession":{"type":"object","required":["id","alertId","status","createdAt"],"properties":{"id":{"type":"integer","description":"Unique session identifier"},"alertId":{"type":"integer","description":"Associated signal ID"},"status":{"type":"string","enum":["started","analyzing","awaiting_confirmation","executing","completed","failed","cancelled"],"description":"Current session status"},"createdAt":{"type":"string","format":"date-time"}}},"AgentAnalysis":{"type":"object","description":"Kai's root cause analysis of the anomaly","properties":{"rootCause":{"type":"string","description":"Identified root cause of the issue"},"impact":{"type":"string","description":"Business impact assessment"},"affectedSystems":{"type":"array","items":{"type":"string"},"description":"List of affected systems/services"},"entityLifecycleContext":{"type":"string","description":"Context about billing entity lifecycle (Usage → Rating → Billing → Invoice → Payment)"},"isAnomalyPattern":{"type":"boolean","description":"Whether this represents a systemic pattern vs isolated failure"},"patternDescription":{"type":"string","nullable":true,"description":"Description of the detected pattern if applicable"},"confidence":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"Confidence level of the analysis"}}},"ProposedAction":{"type":"object","required":["id","actionType","description","isAutomated"],"properties":{"id":{"type":"string","description":"Unique action identifier"},"actionType":{"type":"string","enum":["reprocess_usage_batch","replay_usage_events","recalculate_charges","retry_billing_run","backfill_invoices","retry_payment_batch","pause_payment_runs","sync_subscription_state","repair_entitlements","rollback_configuration","manual_review","contact_support"],"description":"Type of resolution action"},"description":{"type":"string","description":"Human-readable description of what this action does"},"isAutomated":{"type":"boolean","description":"Whether Kai can execute this automatically (true) or requires manual intervention (false)"},"targetSystem":{"type":"string","description":"Target billing/payment system"},"targetEntities":{"type":"array","items":{"type":"string"},"description":"Entity IDs this action will affect"},"expectedOutcome":{"type":"string","description":"Expected result of executing this action"},"risk":{"type":"string","enum":["low","medium","high"],"description":"Risk level of this action"},"steps":{"type":"array","items":{"type":"object","properties":{"order":{"type":"integer"},"description":{"type":"string"},"apiCall":{"type":"string","nullable":true}}},"description":"Detailed steps for this action"}}}}},"paths":{"/concierge/agent-sessions/{id}/execute":{"post":{"tags":["Kai Resolution Agent"],"summary":"Execute approved actions","description":"Executes the specified resolution actions that the user has approved.\nThe agent will make API calls to the relevant billing/payment systems and report results.\nRequires execute_agent_remediation permission and agentAI plan feature.\n","operationId":"executeActions","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actionIds"],"properties":{"actionIds":{"type":"array","items":{"type":"string"},"description":"IDs of approved actions to execute"}}}}}},"responses":{"200":{"description":"Actions executed","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ExecutionResult"}},"session":{"$ref":"#/components/schemas/AgentSessionDetail"}}}}}},"400":{"description":"actionIds array required"},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```

## Cancel agent session

> Cancels an active agent session. Requires create\_agent\_remediation permission.

```json
{"openapi":"3.0.3","info":{"title":"Kaana Kai Resolution Agent API","version":"1.0.0"},"tags":[{"name":"Kai Resolution Agent","description":"Kai resolution agent session management and action execution"}],"servers":[{"url":"/api","description":"API base path"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"apiKey","in":"cookie","name":"connect.sid","description":"Session-based authentication via HTTP-only cookie"}}},"paths":{"/concierge/agent-sessions/{id}/cancel":{"post":{"tags":["Kai Resolution Agent"],"summary":"Cancel agent session","description":"Cancels an active agent session. Requires create_agent_remediation permission.","operationId":"cancelAgentSession","parameters":[{"name":"id","in":"path","required":true,"description":"Agent session ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Session cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Not authenticated"},"403":{"description":"Permission denied or access denied"},"404":{"description":"Session not found"},"500":{"description":"Server error"}}}}}}
```