# 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
}
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/api/api-reference/ai-zhu-li.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.