# AI 助理

### 建立新 AI 助理 <a href="#ai" id="ai"></a>

POST `/api/chatbots/`

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 是  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.post("https://api.maiagent.ai/api/chatbots/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/chatbots/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 建立新 AI 助理 <a href="#ai" id="ai"></a>

POST `/api/v1/chatbots/`

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 是  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.post("https://api.maiagent.ai/api/v1/chatbots/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/chatbots/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 列出 Embedding Model <a href="#embedding-model" id="embedding-model"></a>

GET `/api/embedding-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/embedding-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/embedding-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/embedding-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/embedding-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "isMultimodal": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]
```

***

### 列出 Embedding Model <a href="#embedding-model" id="embedding-model"></a>

GET `/api/v1/embedding-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/embedding-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/embedding-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/embedding-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/embedding-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "isMultimodal": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]
```

***

### 列出 Reranker Model <a href="#reranker-model" id="reranker-model"></a>

GET `/api/reranker-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/reranker-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/reranker-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/reranker-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/reranker-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]
```

***

### 列出 Reranker Model <a href="#reranker-model" id="reranker-model"></a>

GET `/api/v1/reranker-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/reranker-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/reranker-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/reranker-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/reranker-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "isDefault"?: boolean // 非必填
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "isDefault": false,
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    }
  }
]
```

***

### 列出大型語言模型 <a href="#undefined" id="undefined"></a>

GET `/api/large-language-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/large-language-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/large-language-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/large-language-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/large-language-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "contextWindow"?: integer // 此數僅使用在 OpenAILike, 或是 Ollama 的模型上，其餘模型不會使用此數值 (非必填)
    "isDefault"?: boolean // 非必填
    "provider": string
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
    "isMultiModalSupport"?: boolean // 非必填
    "isFunctionalCallingAvailable"?: boolean // 非必填
    "isToolCallingAvailable"?: boolean // 非必填
    "isTemplateAvailable": boolean
    "isOutputFormatAvailable": boolean
    "isThinkingAvailable"?: boolean // 非必填
    "thinkingConfigSchema": object
    "replyMode": [
      string
    ]
    "outputMode": [
      string
    ]
    "agentMode": [
      string
    ]
    "maxTokens"?: integer // 非必填
    "minTokens": integer
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "contextWindow": 456,
    "isDefault": false,
    "provider": "回應字串",
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    },
    "isMultiModalSupport": false,
    "isFunctionalCallingAvailable": false,
    "isToolCallingAvailable": false,
    "isTemplateAvailable": false,
    "isOutputFormatAvailable": false,
    "isThinkingAvailable": false,
    "thinkingConfigSchema": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    },
    "replyMode": [
      "回應字串"
    ],
    "outputMode": [
      "回應字串"
    ],
    "agentMode": [
      "回應字串"
    ],
    "maxTokens": 456,
    "minTokens": 456
  }
]
```

***

### 列出大型語言模型 <a href="#undefined" id="undefined"></a>

GET `/api/v1/large-language-models/`

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/large-language-models/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/large-language-models/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/large-language-models/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/large-language-models/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
[
  {
    "id": string (uuid)
    "name": string
    "contextWindow"?: integer // 此數僅使用在 OpenAILike, 或是 Ollama 的模型上，其餘模型不會使用此數值 (非必填)
    "isDefault"?: boolean // 非必填
    "provider": string
    "icon": 
    {
      "id": string (uuid)
      "name": string
      "image": string (uri)
    }
    "isMultiModalSupport"?: boolean // 非必填
    "isFunctionalCallingAvailable"?: boolean // 非必填
    "isToolCallingAvailable"?: boolean // 非必填
    "isTemplateAvailable": boolean
    "isOutputFormatAvailable": boolean
    "isThinkingAvailable"?: boolean // 非必填
    "thinkingConfigSchema": object
    "replyMode": [
      string
    ]
    "outputMode": [
      string
    ]
    "agentMode": [
      string
    ]
    "maxTokens"?: integer // 非必填
    "minTokens": integer
  }
]
```

**回應範例值**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "回應字串",
    "contextWindow": 456,
    "isDefault": false,
    "provider": "回應字串",
    "icon": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "image": "https://example.com/file.jpg"
    },
    "isMultiModalSupport": false,
    "isFunctionalCallingAvailable": false,
    "isToolCallingAvailable": false,
    "isTemplateAvailable": false,
    "isOutputFormatAvailable": false,
    "isThinkingAvailable": false,
    "thinkingConfigSchema": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應範例名稱",
      "description": "回應範例描述"
    },
    "replyMode": [
      "回應字串"
    ],
    "outputMode": [
      "回應字串"
    ],
    "agentMode": [
      "回應字串"
    ],
    "maxTokens": 456,
    "minTokens": 456
  }
]
```

***

### 取得 AI 助理列表 <a href="#ai" id="ai"></a>

GET `/api/chatbots/`

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                             |
| -------------------- | -- | ------- | ---------------------------------------------- |
| `largeLanguageModel` | ❌  | string  |                                                |
| `page`               | ❌  | integer | A page number within the paginated result set. |
| `pageSize`           | ❌  | integer | Number of results to return per page.          |
| `pagination`         | ❌  | string  | 是否分頁 (true/false)                              |
| `query`              | ❌  | string  |                                                |
| `replyMode`          | ❌  | string  |                                                |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rag": { // RAG 的基礎序列化器
      {
        "id": string (uuid)
        "name": string
      }
      }
      "largeLanguageModel": { // LLM 的基礎序列化器，只包含基本字段
      {
        "id": string (uuid)
        "name": string
      }
      }
      "embeddingModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "rerankerModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "knowledgeBases": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "tools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "skills": [
        {
          "id": string (uuid)
          "name": string
          "description": string
        }
      ]
      "agentMode"?:  // 代理模式，有畫布模式和一般模式，畫布模式是使用畫布來生成回答，一般模式是使用一般模式來生成回答

* `normal` - 正常
* `canvas` - 畫布 (非必填)
      {
      }
      "replyMode"?:  // 回傳模式，有一般模式、模板模式、混合模式、工作流模式、Agent模式

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
      {
      }
      "updatedAt": string (timestamp)
      "enableEvaluation"?: boolean // 非必填
      "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
      "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
      "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
      "numberOfRetrievedChunks"?: integer // 非必填
      "isMultimodalLlm": boolean // Return whether the chatbot's LLM supports multimodal.
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rag": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "embeddingModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "isMultimodal": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "rerankerModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串"
        }
      ],
      "agentMode": {},
      "replyMode": {},
      "updatedAt": "回應字串",
      "enableEvaluation": false,
      "enableInlineCitations": false,
      "enableToolSearching": false,
      "enableCodeInterpreter": false,
      "numberOfRetrievedChunks": 456,
      "isMultimodalLlm": false,
      "canUpdate": false,
      "canDelete": false
    }
  ]
}
```

***

### 取得 AI 助理列表 <a href="#ai" id="ai"></a>

GET `/api/v1/chatbots/`

#### 參數

| 參數名稱                 | 必填 | 類型      | 說明                                             |
| -------------------- | -- | ------- | ---------------------------------------------- |
| `largeLanguageModel` | ❌  | string  |                                                |
| `page`               | ❌  | integer | A page number within the paginated result set. |
| `pageSize`           | ❌  | integer | Number of results to return per page.          |
| `pagination`         | ❌  | string  | 是否分頁 (true/false)                              |
| `query`              | ❌  | string  |                                                |
| `replyMode`          | ❌  | string  |                                                |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/?largeLanguageModel=550e8400-e29b-41d4-a716-446655440000&page=1&pageSize=1&pagination=example&query=example&replyMode=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 非必填
  "previous"?: string (uri) // 非必填
  "results": [
    {
      "id": string (uuid)
      "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rag": { // RAG 的基礎序列化器
      {
        "id": string (uuid)
        "name": string
      }
      }
      "largeLanguageModel": { // LLM 的基礎序列化器，只包含基本字段
      {
        "id": string (uuid)
        "name": string
      }
      }
      "embeddingModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "isMultimodal"?: boolean // Whether this embedding model supports multimodal (text + image) embeddings (非必填)
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "rerankerModel": {
      {
        "id": string (uuid)
        "name": string
        "isDefault"?: boolean // 非必填
        "icon": 
        {
          "id": string (uuid)
          "name": string
          "image": string (uri)
        }
      }
      }
      "knowledgeBases": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "tools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "skills": [
        {
          "id": string (uuid)
          "name": string
          "description": string
        }
      ]
      "agentMode"?:  // 代理模式，有畫布模式和一般模式，畫布模式是使用畫布來生成回答，一般模式是使用一般模式來生成回答

* `normal` - 正常
* `canvas` - 畫布 (非必填)
      {
      }
      "replyMode"?:  // 回傳模式，有一般模式、模板模式、混合模式、工作流模式、Agent模式

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
      {
      }
      "updatedAt": string (timestamp)
      "enableEvaluation"?: boolean // 非必填
      "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
      "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
      "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
      "numberOfRetrievedChunks"?: integer // 非必填
      "isMultimodalLlm": boolean // Return whether the chatbot's LLM supports multimodal.
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
    }
  ]
}
```

**回應範例值**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "rag": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "largeLanguageModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串"
      },
      "embeddingModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "isMultimodal": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "rerankerModel": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "回應字串",
        "isDefault": false,
        "icon": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "image": "https://example.com/file.jpg"
        }
      },
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串",
          "displayName": "回應字串",
          "toolType": "回應字串"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "回應字串",
          "description": "回應字串"
        }
      ],
      "agentMode": {},
      "replyMode": {},
      "updatedAt": "回應字串",
      "enableEvaluation": false,
      "enableInlineCitations": false,
      "enableToolSearching": false,
      "enableCodeInterpreter": false,
      "numberOfRetrievedChunks": 456,
      "isMultimodalLlm": false,
      "canUpdate": false,
      "canDelete": false
    }
  ]
}
```

***

### 取得特定 AI 助理 <a href="#ai" id="ai"></a>

GET `/api/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 取得特定 AI 助理 <a href="#ai" id="ai"></a>

GET `/api/v1/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 更新 AI 助理 <a href="#ai" id="ai"></a>

PUT `/api/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 是  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.put("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 更新 AI 助理 <a href="#ai" id="ai"></a>

PUT `/api/v1/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 是  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 是  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.put(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 部分更新 AI 助理 <a href="#ai" id="ai"></a>

PATCH `/api/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 否  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 否  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name"?: string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人 (非必填)
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel"?: string (uuid) // 機器人使用的大型語言模型，用於生成回答 (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 部分更新 AI 助理 <a href="#ai" id="ai"></a>

PATCH `/api/v1/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位                       | 類型                   | 必填 | 說明                                                                                           |
| ------------------------ | -------------------- | -- | -------------------------------------------------------------------------------------------- |
| name                     | string               | 否  | 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人                                                  |
| rag                      | string (uuid)        | 否  | RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質                                             |
| largeLanguageModel       | string (uuid)        | 否  | 機器人使用的大型語言模型，用於生成回答                                                                          |
| embeddingModel           | string (uuid)        | 否  | 用於向量化文本的嵌入模型，非必填項目                                                                           |
| rerankerModel            | string (uuid)        | 否  | 用於重新排序的模型，非必填項目                                                                              |
| instructions             | string               | 否  | 機器人的角色指令，用於描述機器人的角色和行為                                                                       |
| knowledgeBases           | array\[IdName]       | 否  | 機器人可存取的知識庫列表                                                                                 |
| databases                | array\[IdName]       | 否  | 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能）                                                         |
| organization             | string (uuid)        | 否  | 機器人所屬的組織，如果為空則為個人機器人                                                                         |
| builtInWorkflow          | string (uuid)        | 否  | 內建工作流程，用於預定義的處理流程                                                                            |
| replyMode                | object               | 否  | 回覆模式：一般回覆或串流回覆 `normal`: 正常 ; `template`: 模板 ; `hybrid`: 混合 ; `workflow`: 工作流 ; `agent`: 代理; |
| template                 | string               | 否  | 模板模式、混合模式所使用的模板                                                                              |
| unanswerableTemplate     | string               | 否  | 模板模式、混合模式無法回答時的模板                                                                            |
| totalWordsCount          | integer (int64)      | 否  | 累積的使用總字數                                                                                     |
| outputMode               | object               | 否  | 輸出模式：文字、表格或自定義格式 `text`: 文字 ; `json_schema`: JSON Schema;                                    |
| rawOutputFormat          | object               | 否  | 自定義輸出格式的JSON結構定義                                                                             |
| groups                   | array\[IdName]       | 否  | 機器人可存取的群組列表                                                                                  |
| tools                    | array\[ToolSummary]  | 否  | 機器人可使用的工具列表                                                                                  |
| skills                   | array\[SkillSummary] | 否  | 機器人關聯的技能列表                                                                                   |
| agentMode                | object               | 否  | 代理模式：一般、SQL或工作流程模式 `normal`: 正常 ; `canvas`: 畫布;                                              |
| numberOfRetrievedChunks  | integer              | 否  | 提取的參考資料數量，預設為 12，最小值為 1                                                                      |
| enableEvaluation         | boolean              | 否  |                                                                                              |
| enableInlineCitations    | boolean              | 否  | 啟用內嵌引用功能，會在回應中插入 \[1]\[2] 格式的引用標記                                                            |
| enableCodeInterpreter    | boolean              | 否  | 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼                                                      |
| customMaxLlmOutputTokens | integer              | 否  | 自訂最大 LLM 輸出 token 數，最小值為 512                                                                 |
| voiceAgentType           | string (uuid)        | 否  | 語音代理模式類型                                                                                     |
| sttProvider              | string (uuid)        | 否  | Speech-to-Text 服務提供商                                                                         |
| sttConfig                | object               | 否  | STT 的實際配置參數（JSON 格式）                                                                         |
| ttsProvider              | string (uuid)        | 否  | Text-to-Speech 服務提供商                                                                         |
| ttsConfig                | object               | 否  | TTS 的實際配置參數（JSON 格式）                                                                         |
| realtimeProvider         | string (uuid)        | 否  | Realtime 端到端語音模型提供商                                                                          |
| realtimeConfig           | object               | 否  | Realtime 的實際配置參數（JSON 格式）                                                                    |
| thinkingConfig           | object               | 否  | Thinking effort 設定（JSON 格式）                                                                  |
| enableToolSearching      | boolean              | 否  | 啟用動態工具搜尋功能，允許 agent 透過 tool\_searching\_tool 動態發現和加載工具                                       |

**請求結構範例**

```typescript
{
  "name"?: string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人 (非必填)
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel"?: string (uuid) // 機器人使用的大型語言模型，用於生成回答 (非必填)
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
    }
  ]
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
}
```

**請求範例值**

```json
{
  "name": "範例名稱",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "範例字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "範例字串",
  "unanswerableTemplate": "範例字串",
  "totalWordsCount": 123,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 123,
  "enableEvaluation": true,
  "enableInlineCitations": true,
  "enableCodeInterpreter": true,
  "customMaxLlmOutputTokens": 123,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱",
    "rag": "550e8400-e29b-41d4-a716-446655440000",
    "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
    "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
    "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
    "instructions": "範例字串",
    "knowledgeBases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "databases": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "organization": "550e8400-e29b-41d4-a716-446655440000",
    "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
    "replyMode": {},
    "template": "範例字串",
    "unanswerableTemplate": "範例字串",
    "totalWordsCount": 123,
    "outputMode": {},
    "rawOutputFormat": null,
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "tools": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "skills": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "agentMode": {},
    "numberOfRetrievedChunks": 123,
    "enableEvaluation": true,
    "enableInlineCitations": true,
    "enableCodeInterpreter": true,
    "customMaxLlmOutputTokens": 123,
    "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
    "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
    "sttConfig": null,
    "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
    "ttsConfig": null,
    "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
    "realtimeConfig": null,
    "thinkingConfig": null,
    "enableToolSearching": true
  };

axios.patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱",
      "rag": "550e8400-e29b-41d4-a716-446655440000",
      "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
      "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
      "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
      "instructions": "範例字串",
      "knowledgeBases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "databases": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "organization": "550e8400-e29b-41d4-a716-446655440000",
      "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
      "replyMode": {},
      "template": "範例字串",
      "unanswerableTemplate": "範例字串",
      "totalWordsCount": 123,
      "outputMode": {},
      "rawOutputFormat": null,
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "tools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "skills": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "agentMode": {},
      "numberOfRetrievedChunks": 123,
      "enableEvaluation": true,
      "enableInlineCitations": true,
      "enableCodeInterpreter": true,
      "customMaxLlmOutputTokens": 123,
      "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
      "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
      "sttConfig": null,
      "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
      "ttsConfig": null,
      "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
      "realtimeConfig": null,
      "thinkingConfig": null,
      "enableToolSearching": true
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱",
            "rag": "550e8400-e29b-41d4-a716-446655440000",
            "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
            "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
            "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
            "instructions": "範例字串",
            "knowledgeBases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "databases": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "organization": "550e8400-e29b-41d4-a716-446655440000",
            "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
            "replyMode": {},
            "template": "範例字串",
            "unanswerableTemplate": "範例字串",
            "totalWordsCount": 123,
            "outputMode": {},
            "rawOutputFormat": null,
            "groups": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "tools": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "skills": [
                {
                    "id": "550e8400-e29b-41d4-a716-446655440000"
                }
            ],
            "agentMode": {},
            "numberOfRetrievedChunks": 123,
            "enableEvaluation": true,
            "enableInlineCitations": true,
            "enableCodeInterpreter": true,
            "customMaxLlmOutputTokens": 123,
            "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
            "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
            "sttConfig": null,
            "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
            "ttsConfig": null,
            "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
            "realtimeConfig": null,
            "thinkingConfig": null,
            "enableToolSearching": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 刪除 AI 助理 <a href="#ai" id="ai"></a>

DELETE `/api/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 刪除 AI 助理 <a href="#ai" id="ai"></a>

DELETE `/api/v1/chatbots/{id}/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// 請求內容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

| 狀態碼 | 說明               |
| --- | ---------------- |
| 204 | No response body |

***

### 複製 AI 助理 <a href="#ai" id="ai"></a>

POST `/api/chatbots/{id}/duplicate/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱"
  };

axios.post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 複製 AI 助理 <a href="#ai" id="ai"></a>

POST `/api/v1/chatbots/{id}/duplicate/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位   | 類型     | 必填 | 說明 |
| ---- | ------ | -- | -- |
| name | string | 是  |    |

**請求結構範例**

```typescript
{
  "name": string
}
```

**請求範例值**

```json
{
  "name": "範例名稱"
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "範例名稱"
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "name": "範例名稱"
  };

axios.post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "name": "範例名稱"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/duplicate/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "name": "範例名稱"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 201**

**回應結構範例**

```typescript
{
  "id": string (uuid)
  "name": string // 機器人的名稱，在 Agent 模式下，有語義意義，其他模式下，只是用來區分不同的機器人
  "rag"?: string (uuid) // RAG (Retrieval-Augmented Generation) 設定，用於增強回答品質 (非必填)
  "largeLanguageModel": string (uuid) // 機器人使用的大型語言模型，用於生成回答
  "embeddingModel"?: string (uuid) // 用於向量化文本的嵌入模型，非必填項目 (非必填)
  "rerankerModel"?: string (uuid) // 用於重新排序的模型，非必填項目 (非必填)
  "instructions"?: string // 機器人的角色指令，用於描述機器人的角色和行為 (非必填)
  "knowledgeBases"?: [ // 機器人可存取的知識庫列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "databases"?: [ // 機器人可存取的 SQL 資料庫列表（用於 Text-to-SQL 功能） (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "updatedAt": string (timestamp)
  "organization"?: string (uuid) // 機器人所屬的組織，如果為空則為個人機器人 (非必填)
  "builtInWorkflow"?: string (uuid) // 內建工作流程，用於預定義的處理流程 (非必填)
  "replyMode"?:  // 回覆模式：一般回覆或串流回覆

* `normal` - 正常
* `template` - 模板
* `hybrid` - 混合
* `workflow` - 工作流
* `agent` - 代理 (非必填)
  {
  }
  "template"?: string // 模板模式、混合模式所使用的模板 (非必填)
  "unanswerableTemplate"?: string // 模板模式、混合模式無法回答時的模板 (非必填)
  "totalWordsCount"?: integer (int64) // 累積的使用總字數 (非必填)
  "outputMode"?:  // 輸出模式：文字、表格或自定義格式

* `text` - 文字
* `json_schema` - JSON Schema (非必填)
  {
  }
  "rawOutputFormat"?: object // 自定義輸出格式的JSON結構定義 (非必填)
  "groups"?: [ // 機器人可存取的群組列表 (非必填)
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "tools"?: [ // 機器人可使用的工具列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "skills"?: [ // 機器人關聯的技能列表 (非必填)
    {
      "id": string (uuid)
      "name": string
      "description": string
    }
  ]
  "agentMode"?:  // 代理模式：一般、SQL或工作流程模式

* `normal` - 正常
* `canvas` - 畫布 (非必填)
  {
  }
  "numberOfRetrievedChunks"?: integer // 提取的參考資料數量，預設為 12，最小值為 1 (非必填)
  "enableEvaluation"?: boolean // 非必填
  "enableInlineCitations"?: boolean // 啟用內嵌引用功能，會在回應中插入 [1][2] 格式的引用標記 (非必填)
  "enableCodeInterpreter"?: boolean // 啟用後，提供 Code Interpreter 工具，可在隔離容器中執行程式碼 (非必填)
  "customMaxLlmOutputTokens"?: integer // 自訂最大 LLM 輸出 token 數，最小值為 512 (非必填)
  "voiceAgentType"?: string (uuid) // 語音代理模式類型 (非必填)
  "sttProvider"?: string (uuid) // Speech-to-Text 服務提供商 (非必填)
  "sttConfig"?: object // STT 的實際配置參數（JSON 格式） (非必填)
  "ttsProvider"?: string (uuid) // Text-to-Speech 服務提供商 (非必填)
  "ttsConfig"?: object // TTS 的實際配置參數（JSON 格式） (非必填)
  "realtimeProvider"?: string (uuid) // Realtime 端到端語音模型提供商 (非必填)
  "realtimeConfig"?: object // Realtime 的實際配置參數（JSON 格式） (非必填)
  "thinkingConfig"?: object // Thinking effort 設定（JSON 格式） (非必填)
  "enableToolSearching"?: boolean // 啟用動態工具搜尋功能，允許 agent 透過 tool_searching_tool 動態發現和加載工具 (非必填)
  "isMultimodalLlm": boolean // Whether the chatbot LLM supports multimodal (read-only)
}
```

**回應範例值**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "回應字串",
  "rag": "550e8400-e29b-41d4-a716-446655440000",
  "largeLanguageModel": "550e8400-e29b-41d4-a716-446655440000",
  "embeddingModel": "550e8400-e29b-41d4-a716-446655440000",
  "rerankerModel": "550e8400-e29b-41d4-a716-446655440000",
  "instructions": "回應字串",
  "knowledgeBases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "databases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "updatedAt": "回應字串",
  "organization": "550e8400-e29b-41d4-a716-446655440000",
  "builtInWorkflow": "550e8400-e29b-41d4-a716-446655440000",
  "replyMode": {},
  "template": "回應字串",
  "unanswerableTemplate": "回應字串",
  "totalWordsCount": 456,
  "outputMode": {},
  "rawOutputFormat": null,
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串"
    }
  ],
  "tools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串",
      "displayName": "回應字串",
      "toolType": "回應字串"
    }
  ],
  "skills": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "回應字串",
      "description": "回應字串"
    }
  ],
  "agentMode": {},
  "numberOfRetrievedChunks": 456,
  "enableEvaluation": false,
  "enableInlineCitations": false,
  "enableCodeInterpreter": false,
  "customMaxLlmOutputTokens": 456,
  "voiceAgentType": "550e8400-e29b-41d4-a716-446655440000",
  "sttProvider": "550e8400-e29b-41d4-a716-446655440000",
  "sttConfig": null,
  "ttsProvider": "550e8400-e29b-41d4-a716-446655440000",
  "ttsConfig": null,
  "realtimeProvider": "550e8400-e29b-41d4-a716-446655440000",
  "realtimeConfig": null,
  "thinkingConfig": null,
  "enableToolSearching": false,
  "isMultimodalLlm": false
}
```

***

### 啟用或停用評估功能 <a href="#undefined" id="undefined"></a>

PATCH `/api/chatbots/{id}/enable-evaluation/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明 |
| ---------------- | ------- | -- | -- |
| enableEvaluation | boolean | 否  |    |

**請求結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**請求範例值**

```json
{
  "enableEvaluation": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEvaluation": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "enableEvaluation": true
  };

axios.patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "enableEvaluation": true
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "enableEvaluation": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**回應範例值**

```json
{
  "enableEvaluation": false
}
```

***

### 啟用或停用評估功能 <a href="#undefined" id="undefined"></a>

PATCH `/api/v1/chatbots/{id}/enable-evaluation/`

#### 參數

| 參數名稱 | 必填 | 類型     | 說明                                      |
| ---- | -- | ------ | --------------------------------------- |
| `id` | ✅  | string | A UUID string identifying this Chatbot. |

#### 請求內容

**請求參數**

| 欄位               | 類型      | 必填 | 說明 |
| ---------------- | ------- | -- | -- |
| enableEvaluation | boolean | 否  |    |

**請求結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**請求範例值**

```json
{
  "enableEvaluation": true
}
```

#### 程式碼範例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# 呼叫 API 示例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEvaluation": true
  }'

# 請確認在執行前替換 YOUR_API_KEY 並核對請求資料。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// 設定請求標頭
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// 請求內容 (payload)
const data = {
    "enableEvaluation": true
  };

axios.patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", data, config)
  .then(response => {
    console.log('成功取得回應:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('請求發生錯誤:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# 請求內容 (payload)
data = {
      "enableEvaluation": true
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("成功取得回應:")
    print(response.json())
except Exception as e:
    print("請求發生錯誤:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "enableEvaluation": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "成功取得回應:\n";
    print_r($data);
} catch (Exception $e) {
    echo '請求發生錯誤: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### 回應內容

**狀態碼: 200**

**回應結構範例**

```typescript
{
  "enableEvaluation"?: boolean // 非必填
}
```

**回應範例值**

```json
{
  "enableEvaluation": false
}
```

***