### Install Rancher AI Agent Chart

Source: https://github.com/rancher/rancher-ai-agent/blob/main/README.md

Installs the Rancher AI Agent chart into a specified namespace using a custom values.yaml file. It includes options for creating the namespace and enabling pre-release versions.

```bash
helm install rancher-ai-agent rancher-ai/agent \
  --namespace cattle-ai-agent-system \
  --create-namespace \
  --devel \
  -f values.yaml
```

--------------------------------

### Helm Installation of Rancher AI Agent

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Provides instructions for deploying the Rancher AI Agent using Helm charts. It covers adding the Helm repository, creating a `values.yaml` file for configuration, and installing the chart into a specified namespace.

```bash
# Add the Helm repository
helm repo add rancher-ai https://rancher.github.io/rancher-ai-agent
helm repo update

# Create values file
cat <<EOF > values.yaml
activeLlm: openai
openaiApiKey: "sk-your-api-key"
openaiLlmModel: "gpt-4o"

storage:
  enabled: true
  connectionString: "postgresql://aiagent:password@postgres:5432/aiagent"

# Optional: Enable RAG with embedded documentation
rag:
  enabled: false

# Probe configuration
probes:
  startup:
    initialDelaySeconds: 5
    periodSeconds: 2
    failureThreshold: 10
  liveness:
    periodSeconds: 15
  readiness:
    periodSeconds: 10
EOF

# Install the chart
helm install rancher-ai-agent rancher-ai/agent \
  --namespace cattle-ai-agent-system \
  --create-namespace \
  --devel \
  -f values.yaml


```

--------------------------------

### Helm Installation

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Instructions for deploying the Rancher AI Agent using Helm charts.

```APIDOC
## Helm Installation

### Description
Deploy the Rancher AI Agent using Helm charts. This includes adding the Helm repository, creating a `values.yaml` file for configuration, and installing the chart.

### Steps

1.  **Add the Helm repository:**
    ```bash
    helm repo add rancher-ai https://rancher.github.io/rancher-ai-agent
    helm repo update
    ```

2.  **Create a `values.yaml` file:**
    Define your desired configuration, including LLM provider, API keys, storage settings, and probes.

    ```yaml
    # Example values.yaml
    activeLlm: openai
    openaiApiKey: "sk-your-api-key"
    openaiLlmModel: "gpt-4o"

    storage:
      enabled: true
      connectionString: "postgresql://aiagent:password@postgres:5432/aiagent"

    # Optional: Enable RAG with embedded documentation
    rag:
      enabled: false

    # Probe configuration
    probes:
      startup:
        initialDelaySeconds: 5
        periodSeconds: 2
        failureThreshold: 10
      liveness:
        periodSeconds: 15
      readiness:
        periodSeconds: 10
    ```

3.  **Install the chart:**
    Use the `helm install` command, specifying the namespace and your custom `values.yaml` file.

    ```bash
    helm install rancher-ai-agent rancher-ai/agent \
      --namespace cattle-ai-agent-system \
      --create-namespace \
      --devel \
      -f values.yaml
    ```

### Parameters
- **release-name**: `rancher-ai-agent` (default)
- **chart**: `rancher-ai/agent`
- **namespace**: `cattle-ai-agent-system` (created if it doesn't exist)
- **f values.yaml**: Path to your custom values file.
```

--------------------------------

### Verify Rancher AI Agent Installation

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

These commands verify the installation of the Rancher AI Agent by checking the status of its pods and custom resource definitions (CRDs) within the `cattle-ai-agent-system` namespace.

```shell
kubectl get pods -n cattle-ai-agent-system
kubectl get aiagentconfigs -n cattle-ai-agent-system
```

--------------------------------

### Example AIAgentConfig Kubernetes CRD

Source: https://github.com/rancher/rancher-ai-agent/blob/main/crd-generation/README.md

This snippet shows an example of the AIAgentConfig Custom Resource Definition (CRD) for Kubernetes. It defines the structure for configuring AI agents, including agent details, system prompts, and authentication methods. This CRD is essential for deploying and managing AI agents within the Rancher ecosystem.

```yaml
apiVersion: ai.cattle.io/v1alpha1
kind: AIAgentConfig
metadata:
  name: rancher-core-agent
  namespace: cattle-ai-agent-system
spec:
  agent: "Rancher Core Agent"
  description: "AI agent for Rancher management"
  systemPrompt: "You are a helpful assistant for Rancher."
  mcpURL: "http://mcp-server:8080"
  authenticationType: RANCHER
  humanValidationTools:
    - name: "patch_resource"
      type: UPDATE
```

--------------------------------

### Get Chat by ID API

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves a specific chat session using its unique identifier.

```APIDOC
## Get Chat by ID

### Description
Retrieves a specific chat session by its unique identifier. This is useful for fetching the details of a particular conversation.

### Method

```
GET
```

### Endpoint

```
/v1/api/chats/{chatId}
```

### Parameters

#### Path Parameters

- **chatId** (string) - Required - The unique identifier of the chat session to retrieve.

### Request Example

```bash
curl -X GET "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>"
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier for the chat session.
- **userId** (string) - The identifier of the user who created the chat.
- **name** (string) - The name or title of the chat session.
- **createdAt** (integer) - The Unix timestamp indicating when the chat session was created.

#### Response Example

```json
{
  "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
  "userId": "user-abc123",
  "name": "List all pods in cattle-system",
  "createdAt": 1767638974
}
```

#### Error Responses

- **401**: Unauthorized - `{"detail": "Unauthorized"}`
- **404**: Not Found - `{"detail": "Chat not found"}`
```

--------------------------------

### Get Chat Messages API

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves all messages associated with a specific chat session, ordered chronologically.

```APIDOC
## Get Chat Messages

### Description
Retrieves all messages for a specific chat session, grouped by request ID and sorted chronologically. This endpoint allows fetching the complete history of a conversation.

### Method

```
GET
```

### Endpoint

```
/v1/api/chats/{chatId}/messages
```

### Parameters

#### Path Parameters

- **chatId** (string) - Required - The unique identifier of the chat session whose messages are to be retrieved.

### Request Example

```bash
curl -X GET "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6/messages" \
  -H "Cookie: R_SESS=<session_token>"
```

### Response

#### Success Response (200)

- **chatId** (string) - The ID of the chat session this message belongs to.
- **role** (string) - The role of the sender (e.g., "user", "assistant").
- **agent** (string or null) - The agent that handled the message, if applicable.

#### Response Example

```json
[
  {
    "chatId": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
    "role": "user",
    "agent": null,
    "content": "List all pods in the cattle-system namespace"
  },
  {
    "chatId": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
    "role": "assistant",
    "agent": "rancher",
    "content": "Here are the pods in the cattle-system namespace:\n- pod-1\n- pod-2"
  }
]
```
```

--------------------------------

### Get Chat by ID API Endpoint

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves details of a specific chat session using its unique identifier. Handles successful retrieval and returns error responses for unauthorized access (401) or if the chat is not found (404). Requires a valid session token.

```bash
curl -X GET "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>"

# Response:
# {
#   "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
#   "userId": "user-abc123",
#   "name": "List all pods in cattle-system",
#   "createdAt": 1767638974
# }

# Error responses:
# 401: {"detail": "Unauthorized"}
# 404: {"detail": "Chat not found"}

```

--------------------------------

### Get Chat Messages API Endpoint

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves all messages associated with a specific chat session, identified by its unique ID. Messages are grouped by request ID and sorted chronologically. Requires a valid session token for authentication.

```bash
curl -X GET "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6/messages" \
  -H "Cookie: R_SESS=<session_token>"

# Response:
# [
#   {
#     "chatId": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
#     "role": "user",
#     "agent": null,

```

--------------------------------

### AIAgentConfig CRD Definition and Usage

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Defines the AIAgentConfig Custom Resource Definition for dynamically configuring AI agents in Kubernetes. It specifies system prompts, MCP server connections, and tool configurations. The example also shows how to check agent status using kubectl.

```yaml
# Example AIAgentConfig CRD
apiVersion: ai.cattle.io/v1alpha1
kind: AIAgentConfig
metadata:
  name: rancher-core-agent
  namespace: cattle-ai-agent-system
spec:
  displayName: "Rancher Core"
  description: "Manages Rancher resources and operations"
  systemPrompt: |
    You are a helpful AI assistant integrated into the Rancher UI.
    Your primary goal is to assist users in managing Kubernetes clusters.
  mcpURL: "rancher-mcp-server.cattle-ai-agent-system.svc"
  authenticationType: RANCHER  # RANCHER | NONE | BASIC
  authenticationSecret: ""  # Required for BASIC auth
  builtIn: true
  enabled: true
  toolSet: "rancher"  # Filter MCP tools by toolset
  humanValidationTools:
    - name: "createKubernetesResource"
      type: CREATE
    - name: "patchKubernetesResource"
      type: UPDATE
---
# Check agent status
kubectl get aiagentconfigs -n cattle-ai-agent-system

# NAME      DISPLAY NAME    PHASE   AGE
# rancher   Rancher Core    Ready   5m
# fleet     Fleet           Ready   5m

```

--------------------------------

### Set up AI Agents with Intelligent Routing (Python)

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

This Python code snippet demonstrates how the AI Agent factory creates appropriate agent types based on configuration. It utilizes `LLMManager` and `create_agent` to load configurations, create parent agents if necessary, and return the agent and its metadata, including status.

```python
# Agent factory creates appropriate agent type based on configuration
from app.services.agent.factory import create_agent
from app.services.llm import LLMManager

async def setup_agents(websocket):
    llm = LLMManager.get_instance()

    # Factory automatically:
    # 1. Loads AIAgentConfig CRDs from cluster
    # 2. Creates parent agent if multiple configs exist
    # 3. Creates single agent if only one config
    agent, metadata = await create_agent(llm=llm, websocket=websocket)

    # metadata contains agent status:
    # [
    #   {"name": "rancher", "status": "active"},
    #   {"name": "fleet", "status": "active"}
    # ]

    return agent

# Parent agent routes to specialized child agents based on user intent
# Example routing:
# - "List all pods" -> routes to "rancher" agent
# - "Show GitRepos" -> routes to "fleet" agent
# - Manual override via request: {"agent": "fleet", "prompt": "..."}

```

--------------------------------

### Programmatic LLM Configuration

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Demonstrates how to programmatically configure the language model using environment variables in Python. It shows setting the active LLM, API keys, and model names, utilizing the LLMManager singleton for consistent access.

```python
# Programmatic LLM selection (internal service usage)
import os

# Set environment variables
os.environ["ACTIVE_LLM"] = "openai"
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o"

# Or use generic MODEL for any provider
os.environ["MODEL"] = "gpt-4o"

# The LLMManager singleton ensures consistent model usage
from app.services.llm import LLMManager
llm = LLMManager.get_instance()

```

--------------------------------

### LLM Configuration Options

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Details various methods for configuring language model providers, including Helm values and environment variables. Supports OpenAI, Ollama, Gemini, and AWS Bedrock, with options for storage and observability via Langfuse.

```yaml
# Helm values.yaml configuration
activeLlm: "openai"  # ollama | gemini | openai | bedrock

# OpenAI configuration
openaiApiKey: "sk-..."
openaiLlmModel: "gpt-4o"
openaiUrl: ""  # Optional: custom endpoint for Azure OpenAI

# Ollama configuration (local/self-hosted)
ollamaUrl: "http://ollama.default.svc:11434"
ollamaLlmModel: "llama3.1"

# Google Gemini configuration
googleApiKey: "AIza..."
geminiLlmModel: "gemini-1.5-pro"

# AWS Bedrock configuration
awsBedrock:
  region: "us-west-2"
  accessKeyId: "AKIA..."
  secretAccessKey: "..."
bedrockLlmModel: "anthropic.claude-3-sonnet-20240229-v1:0"

# Storage configuration (PostgreSQL for persistent chat history)
storage:
  enabled: true
  connectionString: "postgresql://user:pass@postgres:5432/aiagent"

# Observability with Langfuse
langfuseSecretKey: "sk-..."
langfusePublicKey: "pk-..."
langfuseHost: "https://cloud.langfuse.com"

```

--------------------------------

### Add Rancher AI Agent Helm Repository

Source: https://github.com/rancher/rancher-ai-agent/blob/main/README.md

Adds the Rancher AI Agent Helm repository to your local Helm configuration. This command fetches the repository's chart information.

```bash
helm repo add rancher-ai https://rancher.github.io/rancher-ai-agent
```

--------------------------------

### LLM Configuration

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Details on configuring the language model provider, including environment variables, Helm values, and programmatic options.

```APIDOC
## LLM Configuration

### Description
Configure the language model provider via environment variables or Helm values. Supports multiple providers like OpenAI, Ollama, Gemini, and Bedrock.

### Helm Values Configuration
Modify the `values.yaml` file for your Helm deployment.

#### General Settings
- **activeLlm** (string) - Required - Specifies the active LLM provider (e.g., `ollama`, `gemini`, `openai`, `bedrock`).

#### Provider-Specific Settings
- **openaiApiKey** (string) - API key for OpenAI.
- **openaiLlmModel** (string) - The specific OpenAI model to use (e.g., `gpt-4o`).
- **openaiUrl** (string) - Optional: Custom endpoint for Azure OpenAI.
- **ollamaUrl** (string) - URL for a local/self-hosted Ollama instance (e.g., `http://ollama.default.svc:11434`).
- **ollamaLlmModel** (string) - The specific Ollama model to use (e.g., `llama3.1`).
- **googleApiKey** (string) - API key for Google Gemini.
- **geminiLlmModel** (string) - The specific Gemini model to use (e.g., `gemini-1.5-pro`).
- **awsBedrock.region** (string) - AWS region for Bedrock.
- **awsBedrock.accessKeyId** (string) - AWS access key ID for Bedrock.
- **awsBedrock.secretAccessKey** (string) - AWS secret access key for Bedrock.
- **bedrockLlmModel** (string) - The specific Bedrock model to use (e.g., `anthropic.claude-3-sonnet-20240229-v1:0`).

#### Storage Configuration
- **storage.enabled** (boolean) - Enable persistent storage for chat history.
- **storage.connectionString** (string) - Database connection string (e.g., PostgreSQL).

#### Observability
- **langfuseSecretKey** (string) - Langfuse secret key.
- **langfusePublicKey** (string) - Langfuse public key.
- **langfuseHost** (string) - Langfuse host URL.

### Example Helm Values (`values.yaml`)
```yaml
activeLlm: "openai"  # ollama | gemini | openai | bedrock

# OpenAI configuration
openaiApiKey: "sk-..."
openaiLlmModel: "gpt-4o"
openaiUrl: ""  # Optional: custom endpoint for Azure OpenAI

# Ollama configuration (local/self-hosted)
ollamaUrl: "http://ollama.default.svc:11434"
ollamaLlmModel: "llama3.1"

# Google Gemini configuration
googleApiKey: "AIza..."
geminiLlmModel: "gemini-1.5-pro"

# AWS Bedrock configuration
awsBedrock:
  region: "us-west-2"
  accessKeyId: "AKIA..."
  secretAccessKey: "..."
bedrockLlmModel: "anthropic.claude-3-sonnet-20240229-v1:0"

# Storage configuration (PostgreSQL for persistent chat history)
storage:
  enabled: true
  connectionString: "postgresql://user:pass@postgres:5432/aiagent"

# Observability with Langfuse
langfuseSecretKey: "sk-..."
langfusePublicKey: "pk-..."
langfuseHost: "https://cloud.langfuse.com"
```

### Programmatic LLM Selection (Python)
Use environment variables to configure the LLM at runtime.

### Example Python Code
```python
import os

# Set environment variables
os.environ["ACTIVE_LLM"] = "openai"
os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_MODEL"] = "gpt-4o"

# Or use generic MODEL for any provider
os.environ["MODEL"] = "gpt-4o"

# The LLMManager singleton ensures consistent model usage
from app.services.llm import LLMManager
llm = LLMManager.get_instance()
```
```

--------------------------------

### Update Helm Repositories

Source: https://github.com/rancher/rancher-ai-agent/blob/main/README.md

Fetches the latest list of charts from all configured Helm repositories, ensuring you have access to the newest versions.

```bash
helm repo update
```

--------------------------------

### Apply RBAC Configuration and Bind User (Shell)

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

These shell commands are used to apply the RBAC configuration defined in a YAML file and then bind that role to a user, either through the Rancher UI or API. This grants the user the necessary permissions to interact with the AI Agent.

```shell
# Apply to user
kubectl apply -f globalrole.yaml

# Bind to user via Rancher UI or API
```

--------------------------------

### Establish WebSocket Connection and Handle Messages (JavaScript)

Source: https://github.com/rancher/rancher-ai-agent/blob/main/app/routers/testui.html

This snippet establishes a WebSocket connection to a local server for real-time chat. It includes event handlers for connection opening, message reception, closure, and errors. It also manages the display of messages in a chat interface and provides functionality to send user messages.

```javascript
const ws = new WebSocket("ws://localhost:8000/v1/ws/messages");

ws.onopen = function(event) {
  console.log("WebSocket connection established.");
  const li = document.createElement('li');
  li.textContent = "Connected to the server!";
  document.getElementById('messages').appendChild(li);
};

let currentMessageLi;
ws.onmessage = function(event) {
  console.log("msg received."+ event.data);
  const messages = document.getElementById('messages');
  const data = event.data;

  if (data.startsWith("<error>")) {
    alert(data.substring(7)); // Show alert without the <error> tag
    return;
  }

  if (data === "<message>") {
    currentMessageLi = document.createElement('li');
    messages.appendChild(currentMessageLi);
  } else if (data === "</message>") {
    currentMessageLi = null;
  } else if (currentMessageLi) {
    currentMessageLi.textContent += data;
  }

  messages.scrollTop = messages.scrollHeight; // Auto-scroll to the bottom
};

ws.onclose = function(event) {
  console.log("WebSocket connection closed.");
  const li = document.createElement('li');
  li.textContent = "Connection closed.";
  document.getElementById('messages').appendChild(li);
};

ws.onerror = function(error) {
  console.error("WebSocket error: ", error);
};

function sendMessage(event) {
  const input = document.getElementById("messageText");
  if (input.value) {
    ws.send(input.value); // Add the sent message to our own list
    const messages = document.getElementById('messages');
    const message = document.createElement('li');
    message.textContent = `You: ${input.value}`;
    message.style.fontWeight = "bold";
    messages.appendChild(message);
    input.value = '';
  }
  event.preventDefault();
}
```

--------------------------------

### List All Chats API Endpoint

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves a list of all chat sessions associated with the authenticated user. Supports sorting the results by creation date in ascending or descending order. Requires a valid session token for authentication.

```bash
# List all chats (default: newest first)
curl -X GET "https://rancher.example.com/v1/api/chats" \
  -H "Cookie: R_SESS=<session_token>"

# List chats with ascending sort (oldest first)
curl -X GET "https://rancher.example.com/v1/api/chats?sort=createdAt:asc" \
  -H "Cookie: R_SESS=<session_token>"

# Response:
# [
#   {
#     "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
#     "userId": "user-abc123",
#     "name": "List all pods in cattle-system",
#     "createdAt": 1767638974
#   },
#   {
#     "id": "bd924baf-24d7-49a5-84ae-bba3a58218a7",
#     "userId": "user-abc123",
#     "name": "Deploy nginx to production",
#     "createdAt": 1767638500
#   }
# ]

```

--------------------------------

### List All Chats API

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Retrieves a list of all chat sessions associated with the authenticated user, sorted by creation date.

```APIDOC
## List All Chats

### Description
Retrieves all chat sessions for the authenticated user, sorted by creation date. This endpoint is useful for displaying a history of conversations.

### Method

```
GET
```

### Endpoint

```
/v1/api/chats
```

### Parameters

#### Query Parameters

- **sort** (string) - Optional - Specifies the sorting order. Default is `createdAt:desc` (newest first). Use `createdAt:asc` for oldest first.

### Request Example

```bash
curl -X GET "https://rancher.example.com/v1/api/chats" \
  -H "Cookie: R_SESS=<session_token>"

# Example with ascending sort:
curl -X GET "https://rancher.example.com/v1/api/chats?sort=createdAt:asc" \
  -H "Cookie: R_SESS=<session_token>"
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier for the chat session.
- **userId** (string) - The identifier of the user who created the chat.
- **name** (string) - The name or title of the chat session.
- **createdAt** (integer) - The Unix timestamp indicating when the chat session was created.

#### Response Example

```json
[
  {
    "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
    "userId": "user-abc123",
    "name": "List all pods in cattle-system",
    "createdAt": 1767638974
  },
  {
    "id": "bd924baf-24d7-49a5-84ae-bba3a58218a7",
    "userId": "user-abc123",
    "name": "Deploy nginx to production",
    "createdAt": 1767638500
  }
]
```
```

--------------------------------

### WebSocket Chat Endpoint for AI Agent Interaction

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Establishes a WebSocket connection to interact with the AI agent in real-time. Supports sending chat prompts with context and receiving various response types, including streaming messages and confirmation prompts for sensitive operations. Requires a valid WebSocket endpoint URL.

```javascript
// Connect to WebSocket endpoint (with optional thread_id for conversation continuity)
const ws = new WebSocket('wss://rancher.example.com/v1/ws/messages');
// Or resume existing conversation:
// const ws = new WebSocket('wss://rancher.example.com/v1/ws/messages/ad924baf-24d7-49a5-84ae-bba3a58218a6');

ws.onopen = () => {
  // Send a chat message with context
  const request = {
    prompt: "List all pods in the cattle-system namespace",
    context: {
      cluster: "local",
      namespace: "cattle-system"
    },
    agent: "",  // Optional: force specific agent (e.g., "rancher", "fleet")
    tags: [],   // Optional: ["ephemeral"] to skip memory storage
    labels: {}
  };
  ws.send(JSON.stringify(request));
};

ws.onmessage = (event) => {
  const data = event.data;

  // Response types:
  // <chat-metadata>{"chatId": "uuid", "agents": [{"name": "rancher", "status": "active"}]}</chat-metadata>
  // <message>...</message> - Wraps streaming response
  // <agent-metadata>{"agentName": "rancher", "selectionMode": "auto"}</agent-metadata>
  // <confirmation-response>{"payload": {...}, "type": "patch", "resource": {...}}</confirmation-response>
  // <mcp-response>{...}</mcp-response> - Tool execution results
  // <error>{"message": "error details"}</error>

  console.log('Received:', data);
};

// Handle human validation prompts (for CREATE/UPDATE operations)
// When receiving <confirmation-response>, user must send "yes" or "no" to continue
ws.send('yes');  // Approve the operation

```

--------------------------------

### Health Check Endpoints

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Provides endpoints for liveness and readiness probes to monitor the Rancher AI Agent's status. The liveness probe checks if the HTTP service is running, while the readiness probe verifies agent initialization. Responses indicate 'healthy' or 'Agent is ready', with error codes for failures.

```bash
# Liveness probe - verifies HTTP service is running
curl -X GET "https://rancher.example.com/v1/api/health"

# Response:
# {"status": "healthy"}

# Readiness probe - verifies agent is fully initialized
curl -X GET "https://rancher.example.com/v1/api/readiness"

# Response (ready):
# {"detail": "Agent is ready"}

# Response (not ready):
# {"detail": "Memory manager not initialized"}  # 503
# {"detail": "Application startup not complete"}  # 503
```

--------------------------------

### Health Check Endpoints

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Provides endpoints for Kubernetes liveness and readiness probes to monitor the agent's status.

```APIDOC
## GET /v1/api/health

### Description
Verifies if the HTTP service is running.

### Method
GET

### Endpoint
`/v1/api/health`

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status, e.g., "healthy".

### Response Example
```json
{
  "status": "healthy"
}
```

## GET /v1/api/readiness

### Description
Verifies if the agent is fully initialized and ready to serve requests.

### Method
GET

### Endpoint
`/v1/api/readiness`

### Response
#### Success Response (200)
- **detail** (string) - Indicates readiness, e.g., "Agent is ready".

#### Error Response (503)
- **detail** (string) - Indicates a reason for not being ready, e.g., "Memory manager not initialized" or "Application startup not complete".

### Response Example (Ready)
```json
{
  "detail": "Agent is ready"
}
```

### Response Example (Not Ready)
```json
{
  "detail": "Memory manager not initialized"
}
```
```

--------------------------------

### WebSocket Chat Endpoint

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Establishes a persistent WebSocket connection for real-time chat interactions with the AI agent, enabling streaming responses and command execution.

```APIDOC
## WebSocket Chat Endpoint

### Description
Establishes a persistent WebSocket connection for real-time chat interactions with the AI agent. This endpoint allows for streaming responses from the LLM and executing actions through the Model Context Protocol (MCP) Server.

### Method

```
GET
```

### Endpoint

```
/v1/ws/messages
```

### Parameters

#### Query Parameters

- **thread_id** (string) - Optional - The ID of an existing chat thread to resume the conversation.

### Request Body (on `ws.send`)

- **prompt** (string) - Required - The natural language query or command to send to the AI agent.
- **context** (object) - Optional - Provides context for the query, such as the target cluster and namespace.
  - **cluster** (string) - Required if context is provided - The name of the Kubernetes cluster.
  - **namespace** (string) - Required if context is provided - The namespace within the cluster.
- **agent** (string) - Optional - Forces the request to be handled by a specific agent (e.g., "rancher", "fleet").
- **tags** (array of strings) - Optional - Tags for the message, e.g., `["ephemeral"]` to skip memory storage.
- **labels** (object) - Optional - Custom labels for the message.

### Response (on `ws.onmessage`)

The WebSocket connection can receive several types of messages, indicated by prefixes or specific JSON structures:

- **`<chat-metadata>`**: Contains chat session metadata, including `chatId` and available `agents`.
- **`<message>`**: Wraps streaming response content from the LLM.
- **`<agent-metadata>`**: Provides information about agent selection, such as `agentName` and `selectionMode`.
- **`<confirmation-response>`**: A prompt requiring human validation for sensitive operations (e.g., CREATE/UPDATE). The user must respond with "yes" or "no".
- **`<mcp-response>`**: The result of tool execution, typically containing a `payload` and details about the `resource`.
- **`<error>`**: Indicates an error occurred during processing, with a `message` field detailing the error.

### Request Example

```javascript
const ws = new WebSocket('wss://rancher.example.com/v1/ws/messages');

ws.onopen = () => {
  const request = {
    prompt: "List all pods in the cattle-system namespace",
    context: {
      cluster: "local",
      namespace: "cattle-system"
    },
    agent: "",
    tags: [],
    labels: {}
  };
  ws.send(JSON.stringify(request));
};

ws.onmessage = (event) => {
  console.log('Received:', event.data);
  // Handle different response types here
};

// Example of sending confirmation for a sensitive operation:
// ws.send('yes');
```

### Response Example (Illustrative)

```json
// Example of a streaming message response:
// <message>Here are the pods in the cattle-system namespace:
// ... pod list ...
// </message>

// Example of a confirmation response:
// <confirmation-response>{"payload": {...}, "type": "patch", "resource": {...}}</confirmation-response>

// Example of an error response:
// <error>{"message": "Failed to list pods: permission denied"}</error>
```
```

--------------------------------

### RBAC GlobalRole for AI Agent Access

Source: https://github.com/rancher/rancher-ai-agent/blob/main/README.md

Defines a GlobalRole in Kubernetes RBAC to grant necessary permissions for using the AI agent. This includes access to 'llm-config' secrets and proxy services.

```yaml
apiVersion: management.cattle.io/v3
displayName: ai
kind: GlobalRole
metadata:
  name: ai-agent
namespacedRules:
  cattle-ai-agent-system:
    - apiGroups:
        - ""
      resourceNames:
        - http:rancher-ai-agent:80
      resources:
        - services/proxy
      verbs:
        - get
    - apiGroups:
        - ""
      resourceNames:
        - llm-config
      resources:
        - secrets
      verbs:
        - get
```

--------------------------------

### Configure RBAC for AI Agent Access (YAML)

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

This YAML defines a Rancher GlobalRole named 'ai-agent' to grant users permission to access the AI Agent. It specifies rules for accessing the AI agent service proxy and reading LLM configurations.

```yaml
apiVersion: management.cattle.io/v3
kind: GlobalRole
metadata:
  name: ai-agent
displayName: AI Agent User
namespacedRules:
  cattle-ai-agent-system:
    # Allow access to AI agent service proxy
    - apiGroups:
        - ''
      resourceNames:
        - http:rancher-ai-agent:80
      resources:
        - services/proxy
      verbs:
        - get
    # Allow reading LLM configuration
    - apiGroups:
        - ''
      resourceNames:
        - llm-config
      resources:
        - secrets
      verbs:
        - get
```

--------------------------------

### AIAgentConfig CRD

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Defines the structure for AI Agent Configuration Custom Resource Definitions in Kubernetes.

```APIDOC
## AIAgentConfig Custom Resource Definition

### Description
Kubernetes CRD for configuring AI agents dynamically. Each AIAgentConfig defines a specialized agent with its own system prompt, MCP server connection, and tool configuration.

### Kind
AIAgentConfig

### API Version
ai.cattle.io/v1alpha1

### Metadata
- **name** (string) - Required - The name of the AIAgentConfig resource.
- **namespace** (string) - Required - The namespace where the AIAgentConfig is created.

### Spec
- **displayName** (string) - Optional - A user-friendly name for the agent.
- **description** (string) - Optional - A brief description of the agent's purpose.
- **systemPrompt** (string) - Required - The system prompt that guides the AI agent's behavior.
- **mcpURL** (string) - Required - The URL of the MCP server the agent should connect to.
- **authenticationType** (string) - Required - The authentication method (e.g., RANCHER, NONE, BASIC).
- **authenticationSecret** (string) - Optional - The Kubernetes secret name for BASIC authentication.
- **builtIn** (boolean) - Optional - Indicates if the agent is a built-in agent.
- **enabled** (boolean) - Optional - Whether the agent is enabled.
- **toolSet** (string) - Optional - Filters MCP tools by a specific toolset.
- **humanValidationTools** (array) - Optional - A list of tools requiring human validation.
  - **name** (string) - The name of the tool.
  - **type** (string) - The type of the tool (e.g., CREATE, UPDATE).

### Example AIAgentConfig CRD
```yaml
apiVersion: ai.cattle.io/v1alpha1
kind: AIAgentConfig
metadata:
  name: rancher-core-agent
  namespace: cattle-ai-agent-system
spec:
  displayName: "Rancher Core"
  description: "Manages Rancher resources and operations"
  systemPrompt: |
    You are a helpful AI assistant integrated into the Rancher UI.
    Your primary goal is to assist users in managing Kubernetes clusters.
  mcpURL: "rancher-mcp-server.cattle-ai-agent-system.svc"
  authenticationType: RANCHER  # RANCHER | NONE | BASIC
  authenticationSecret: ""  # Required for BASIC auth
  builtIn: true
  enabled: true
  toolSet: "rancher"  # Filter MCP tools by toolset
  humanValidationTools:
    - name: "createKubernetesResource"
      type: CREATE
    - name: "patchKubernetesResource"
      type: UPDATE
```

### Usage
To check the status of agent configurations:
```bash
kubectl get aiagentconfigs -n cattle-ai-agent-system
```

### Example Output
```
NAME      DISPLAY NAME    PHASE   AGE
# rancher   Rancher Core    Ready   5m
# fleet     Fleet           Ready   5m
```
```

--------------------------------

### Chat History API

Source: https://github.com/rancher/rancher-ai-agent/blob/main/README.md

Endpoints for managing chat sessions and messages.

```APIDOC
## GET /api/chats

### Description
Lists all available chat sessions.

### Method
GET

### Endpoint
/api/chats

### Parameters
#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **chats** (array) - A list of chat session objects.

#### Response Example
```json
{
  "chats": [
    {
      "id": "chat-123",
      "title": "My First Chat",
      "createdAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```

## GET /api/chats/{id}/messages

### Description
Retrieves all messages for a specific chat session.

### Method
GET

### Endpoint
/api/chats/{id}/messages

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the chat session.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **messages** (array) - A list of message objects within the chat session.

#### Response Example
```json
{
  "messages": [
    {
      "id": "msg-abc",
      "sender": "user",
      "content": "Hello, how are you?",
      "timestamp": "2023-10-27T10:01:00Z"
    },
    {
      "id": "msg-def",
      "sender": "ai",
      "content": "I am doing well, thank you!",
      "timestamp": "2023-10-27T10:02:00Z"
    }
  ]
}
```

## DELETE /api/chats/{id}

### Description
Deletes a specific chat session.

### Method
DELETE

### Endpoint
/api/chats/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the chat session to delete.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the chat session was deleted.

#### Response Example
```json
{
  "message": "Chat session deleted successfully."
}
```
```

--------------------------------

### Update Chat API Endpoint

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Updates the metadata of an existing chat session, such as renaming it. Requires the chat's unique identifier, a valid session token, and a JSON payload containing the fields to update. Returns the updated chat object upon success.

```bash
curl -X PUT "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Pod Investigation" }'

# Response:
# {
#   "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
#   "userId": "user-abc123",
#   "name": "Production Pod Investigation",
#   "createdAt": 1767638974
# }

```

--------------------------------

### Update Chat API

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Updates the metadata of an existing chat session, such as renaming the conversation.

```APIDOC
## Update Chat

### Description
Updates a chat's metadata, such as renaming a conversation. This allows users to organize and label their chat sessions.

### Method

```
PUT
```

### Endpoint

```
/v1/api/chats/{chatId}
```

### Parameters

#### Path Parameters

- **chatId** (string) - Required - The unique identifier of the chat session to update.

#### Request Body

- **name** (string) - Required - The new name for the chat session.

### Request Example

```bash
curl -X PUT "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Pod Investigation" }'
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier for the chat session.
- **userId** (string) - The identifier of the user who created the chat.
- **name** (string) - The updated name of the chat session.
- **createdAt** (integer) - The Unix timestamp indicating when the chat session was created.

#### Response Example

```json
{
  "id": "ad924baf-24d7-49a5-84ae-bba3a58218a6",
  "userId": "user-abc123",
  "name": "Production Pod Investigation",
  "createdAt": 1767638974
}
```
```

--------------------------------

### Delete Chat API

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

This API allows for the deletion of specific chat sessions or all chats associated with a user.

```APIDOC
## DELETE /v1/api/chats/{chatId}

### Description
Deletes a specific chat session and all associated messages.

### Method
DELETE

### Endpoint
`/v1/api/chats/{chatId}`

### Parameters
#### Path Parameters
- **chatId** (string) - Required - The unique identifier of the chat session to delete.

### Request Example
```bash
curl -X DELETE "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>"
```

### Response
#### Success Response (204)
No Content is returned upon successful deletion.

## DELETE /v1/api/chats

### Description
Deletes all chat sessions for the authenticated user.

### Method
DELETE

### Endpoint
`/v1/api/chats`

### Response
#### Success Response (204)
No Content is returned upon successful deletion.
```

--------------------------------

### Delete Chat Session

Source: https://context7.com/rancher/rancher-ai-agent/llms.txt

Deletes a specific chat session or all chats for a user using the Rancher API. Requires a session token for authentication. Returns a 204 No Content on success.

```bash
# Delete a specific chat
curl -X DELETE "https://rancher.example.com/v1/api/chats/ad924baf-24d7-49a5-84ae-bba3a58218a6" \
  -H "Cookie: R_SESS=<session_token>"

# Response: 204 No Content

# Delete ALL chats for the user
curl -X DELETE "https://rancher.example.com/v1/api/chats" \
  -H "Cookie: R_SESS=<session_token>"

# Response: 204 No Content
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.