# Alfred Assitants

## Introduction

An **Assistant** is an advanced AI-based entity capable of performing specific tasks autonomously based on the rules and instructions provided during its configuration. Assistants in CONTROL allow you to define and customize behavior, capabilities, and data interpretation logic, including unique identity, functionalities, and structured response formats.

**OpenAI Integration:** Alfred assistants that use an OpenAI model are synchronized with OpenAI Assistants, automatically creating and updating each instance when required.

---

## Assistant Configuration Fields

[![Captura desde 2024-12-02 21-25-05.png](https://docs.zequenze.com/uploads/images/gallery/2026-02/lQJ4I2BAiriZ7r0Q-tmpzlcd2m-f.png)](https://docs.zequenze.com/uploads/images/gallery/2024-12/odqYSJzsxLS9YQrz-captura-desde-2024-12-02-21-25-05.png)

### 1. Name
The display name of the assistant, representing its purpose or functionality.

- **Example:** `Device Detection`

### 2. Short Name / Code
A concise identifier or code for the assistant, used for easy reference in systems and API calls.

- **Example:** `device-detection`

### 3. Model Configuration Service
Defines the AI model or engine the assistant utilizes for processing tasks. These are configured as Alfred services.

- **Example:** `OpenAI GPT-4`

### 4. Organization
Specifies the organization or team responsible for the assistant.

- **Example:** `Root`

### 5. External Identification
A unique identifier assigned to the assistant for external integration or tracking purposes.

- **Example:** `asst_altBr2RoWO77jxT5h0kihDB1` (OpenAI Assistant ID)

### 6. Prompt
Instructions provided to the assistant that define its core behavior and task scope. This ensures the assistant interprets and processes data accurately according to your requirements.

- **Example:**
  ```
  You are an intelligent assistant that provides answers about Sports in JSON format
  ```

### 7. Response Schema
Defines the structure and format of the assistant's output to ensure responses conform to valid JSON or other required formats.

- **Example:**
  ```json
  {
    "type": "object",
    "title": "DeviceInformationList",
    "properties": {
      "hostname": {
        "type": "string"
      },
      "mac_address": {
        "type": "string"
      },
      "dhcp_vendor_class": {
        "type": "string"
      },
      "is_random_macaddr": {
        "type": "boolean"
      }
    }
  }
  ```

---

## Integration Guide: `ask_to_assistant` Function

The `ask_to_assistant` function enables communication with AI-powered assistants, allowing developers to query assistants and receive intelligent responses programmatically.

### Function Signature

```python
def ask_to_assistant(
    question: str,
    id: int = None,
    short_name: str = None,
    organization_id: int = None,
    related_object = None,
    related_object_name = None,
    related_object_id = None,
    check_answers = False
)
```

### Parameters

#### Required Parameter

- **`question`** (`str`)  
  The query or prompt to send to the assistant.

#### Optional Parameters

- **`id`** (`int`)  
  The unique ID of the assistant to query.

- **`short_name`** (`str`)  
  The short name/code of the assistant to query.

- **`organization_id`** (`int`)  
  The ID of the organization to which the assistant belongs.

- **`related_object`** (`Any`)  
  An optional object associated with the query (e.g., related to a specific feature or module).

- **`related_object_name`** (`str`)  
  The name of the related object.

- **`related_object_id`** (`int`)  
  The ID of the related object.

- **`check_answers`** (`bool`)  
  If `True`, checks for previously stored answers to avoid duplicate queries and improve performance.

### Return Value

- **`str`** or **`None`**  
  Returns the assistant's response based on the given query. Returns `None` if no assistant is found.

### How It Works

1. **Retrieve the Assistant**  
   The function uses `Assistant.objects.get_default_assistant` to fetch the desired assistant based on the provided `id`, `short_name`, or `organization_id`.

2. **Check for Previous Answers** (Optional)  
   If `check_answers` is set to `True`, the function checks if there is a previously saved answer for the same question. If found, it returns that cached answer.

3. **Log the Request**  
   A log entry is created using `upsert_log` to track the request details and status.

4. **Call the Appropriate Model Service**  
   Based on the assistant's configuration:
   - **OpenAI models** (`openai-model-config`): Calls `ask_to_openai_assistant` with the assistant's `external_id` and API key.
   - **Groq models** (`groq-model-config`): Calls `ask_to_groq_assistant` with the assistant's model settings and API key.

5. **Update the Log**  
   The log is updated with the assistant's response, tokens used, and execution delay.

6. **Return the Response**  
   The final answer is returned to the caller.

### Example Usage

#### Querying an Assistant by Short Name

```python
response = ask_to_assistant(
    question="What is the weather forecast today?",
    short_name="forecast-assistant"
)
```

#### Querying with Related Object Context

```python
response = ask_to_assistant(
    question="Analyze this device configuration",
    short_name="device-detection",
    related_object_name="NetworkDevice",
    related_object_id=12345,
    check_answers=True
)
```

---

## Alfred Assistant Logs

Each question performed to a specific assistant generates detailed execution logs. These logs allow you to monitor assistant performance, track token usage, and troubleshoot issues.

[![Captura desde 2024-12-02 21-47-45.png](https://docs.zequenze.com/uploads/images/gallery/2026-02/Khrwe8XEydA0Jt3g-tmp8nnt-ui.png)](https://docs.zequenze.com/uploads/images/gallery/2024-12/H9rd0JVVvak19Y7U-captura-desde-2024-12-02-21-47-45.png)

[![Captura desde 2024-12-02 21-48-05.png](https://docs.zequenze.com/uploads/images/gallery/2026-02/zvCKUDsGp6VWmc6y-tmpxfr34rqf.png)](https://docs.zequenze.com/uploads/images/gallery/2024-12/NI3tcxbcuCCLcYTy-captura-desde-2024-12-02-21-48-05.png)

### Log Information

Assistant logs provide visibility into:

- **Request details**: Question asked, assistant used, and timestamp
- **Response data**: Answer provided by the assistant
- **Performance metrics**: Token usage and execution time
- **Related objects**: Associated entities or context for the query
- **Status**: Success or error information