Updated descriptions of agent APIs (#3407)

### What problem does this PR solve?


### Type of change


- [x] Documentation Update

docs/references/http_api_reference.md

@@ -77,7 +77,9 @@ curl --request POST \
   The name of the embedding model to use. For example: `"BAAI/bge-zh-v1.5"`
 
 - `"permission"`: (*Body parameter*), `string`  
-  Specifies who can access the dataset to create. You can set it only to `"me"` for now.
+  Specifies who can access the dataset to create. Available options:  
+  - `"me"`: (Default) Only you can manage the dataset.
+  - `"team"`: All team members can manage the dataset.
 
 - `"chunk_method"`: (*Body parameter*), `enum<string>`  
   The chunking method of the dataset to create. Available options:  
@@ -1704,11 +1706,11 @@ Failure:
 }
 ```
 
-## Create session
+## Create session with chat assistant
 
 **POST** `/api/v1/chats/{chat_id}/sessions`
 
-Creates a chat session.
+Creates a session with a chat assistant.
 
 ### Request
 
@@ -1780,7 +1782,7 @@ Failure:
 
 **PUT** `/api/v1/chats/{chat_id}/sessions/{session_id}`
 
-Updates a chat session.
+Updates a session of a specified chat assistant.
 
 ### Request
 
@@ -1917,7 +1919,7 @@ Failure:
 
 **DELETE** `/api/v1/chats/{chat_id}/sessions`
 
-Deletes sessions by ID.
+Deletes sessions of a chat assistant by ID.
 
 ### Request
 
@@ -1971,11 +1973,26 @@ Failure:
 
 ---
 
-## Converse
+## Converse with chat assistant
 
 **POST** `/api/v1/chats/{chat_id}/completions`
 
-Asks a question to start an AI-powered conversation.
+Asks a specified chat assistant a question to start an AI-powered conversation.
+
+:::tip NOTE
+
+- In streaming mode, not all responses include a reference, as this depends on the system's judgement.
+- In streaming mode, the last message is an empty message:
+
+  ```text
+  data:
+  {
+    "code": 0,
+    "data": true
+  }
+  ```
+
+:::
 
 ### Request
 
@@ -2007,7 +2024,7 @@ curl --request POST \
 
 - `chat_id`: (*Path parameter*)  
   The ID of the associated chat assistant.
-- `"question"`: (*Body Parameter*), `string` *Required*  
+- `"question"`: (*Body Parameter*), `string`, *Required*  
   The question to start an AI-powered conversation.
 - `"stream"`: (*Body Parameter*), `boolean`  
   Indicates whether to output responses in a streaming way:
@@ -2020,7 +2037,7 @@ curl --request POST \
 
 Success:
 
-```text
+```json
 data:{
     "code": 0,
     "data": {
@@ -2101,11 +2118,13 @@ Failure:
 }
 ```
 
-## Create agent session
+---
+
+## Create session with an agent
 
 **POST** `/api/v1/agents/{agent_id}/sessions`
 
-Creates an agent session.
+Creates a session with an agent.
 
 ### Request
 
@@ -2129,7 +2148,7 @@ curl --request POST \
 
 #### Request parameters
 
-- `agent_id`: (*Path parameter*)
+- `agent_id`: (*Path parameter*)  
   The ID of the associated agent assistant.
 
 ### Response
@@ -2144,7 +2163,7 @@ Success:
         "id": "7869e9e49c1711ef92840242ac120006",
         "message": [
             {
-                "content": "Hello! I am the HR responsible for recruitment at Infineon. I learned that you are an expert in this field, and I took the liberty of reaching out to you. There is an opportunity I would like to share with you. RAGFlow is currently looking for a senior engineer for your position. I was wondering if you might be interested?",
+                "content": "Hello! I am a recruiter at InfiniFlow. I learned that you are an expert in the field, and took the liberty of reaching out to you. There is an opportunity I would like to share with you. RAGFlow is currently looking for a senior engineer for your position. I was wondering if you might be interested?",
                 "role": "assistant"
             }
         ],
@@ -2163,13 +2182,28 @@ Failure:
 }
 ```
 
+---
 
-
-## Converse through agent
+## Converse with agent
 
 **POST** `/api/v1/agents/{agent_id}/completions`  
-#######  
-Asks a question to start an AI-powered conversation.
+
+Asks a specified agent a question to start an AI-powered conversation.
+
+:::tip NOTE
+
+- In streaming mode, not all responses include a reference, as this depends on the system's judgement.
+- In streaming mode, the last message is an empty message:
+
+  ```text
+  data:
+  {
+    "code": 0,
+    "data": true
+  }
+  ```
+
+:::
 
 ### Request
 
@@ -2199,16 +2233,16 @@ curl --request POST \
 
 #### Request Parameters
 
-- `agent_id`: (*Path parameter*)  
+- `agent_id`: (*Path parameter*), `string`  
   The ID of the associated agent assistant.
-- `"question"`: (*Body Parameter*), `string` *Required*  
+- `"question"`: (*Body Parameter*), `string`, *Required*  
   The question to start an AI-powered conversation.
 - `"stream"`: (*Body Parameter*), `boolean`  
-  Indicates whether to output responses in a streaming way:
+  Indicates whether to output responses in a streaming way:  
   - `true`: Enable streaming.
   - `false`: Disable streaming (default).
 - `"session_id"`: (*Body Parameter*)  
-  The ID of session. If it is not provided, a new session will be generated.
+  The ID of the session. If it is not provided, a new session will be generated.
 
 ### Response
 
@@ -2227,7 +2261,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello",
         "reference": [],
@@ -2237,7 +2270,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello!",
         "reference": [],
@@ -2247,7 +2279,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How",
         "reference": [],
@@ -2257,7 +2288,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can",
         "reference": [],
@@ -2267,7 +2297,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I",
         "reference": [],
@@ -2277,7 +2306,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I assist",
         "reference": [],
@@ -2287,7 +2315,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I assist you",
         "reference": [],
@@ -2297,7 +2324,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I assist you today",
         "reference": [],
@@ -2307,7 +2333,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I assist you today?",
         "reference": [],
@@ -2317,7 +2342,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": {
         "answer": "Hello! How can I assist you today?",
         "reference": [],
@@ -2327,7 +2351,6 @@ data:{
 }
 data:{
     "code": 0,
-    "message": "",
     "data": true
 }
 ```
@@ -2339,4 +2362,6 @@ Failure:
     "code": 102,
     "message": "`question` is required."
 }
-```
+```
+
+---

docs/references/python_api_reference.md

@@ -63,7 +63,10 @@ The language setting of the dataset to create. Available options:
 
 #### permission
 
-Specifies who can access the dataset to create. You can set it only to `"me"` for now.
+Specifies who can access the dataset to create. Available options:  
+
+- `"me"`: (Default) Only you can manage the dataset.
+- `"team"`: All team members can manage the dataset.
 
 #### chunk_method, `str`
 
@@ -819,7 +822,7 @@ Retrieves chunks from specified datasets.
 
 ### Parameters
 
-#### question: `str` *Required*
+#### question: `str`, *Required*
 
 The user query or query keywords. Defaults to `""`.
 
@@ -1141,13 +1144,13 @@ Chat Session APIs
 
 ---
 
-## Create session
+## Create session with chat assistant
 
 ```python
 Chat.create_session(name: str = "New session") -> Session
 ```
 
-Creates a chat session.
+Creates a session with the current chat assistant.
 
 ### Parameters
 
@@ -1177,13 +1180,13 @@ session = assistant.create_session()
 
 ---
 
-## Update session
+## Update chat assistant's session
 
 ```python
 Session.update(update_message: dict)
 ```
 
-Updates the current session.
+Updates the current session of the current chat assistant.
 
 ### Parameters
 
@@ -1212,7 +1215,7 @@ session.update({"name": "updated_name"})
 
 ---
 
-## List sessions
+## List chat assistant's sessions
 
 ```python
 Chat.list_sessions(
@@ -1275,13 +1278,13 @@ for session in assistant.list_sessions():
 
 ---
 
-## Delete sessions
+## Delete chat assistant's sessions
 
 ```python
 Chat.delete_sessions(ids:list[str] = None)
 ```
 
-Deletes sessions by ID.
+Deletes sessions of the current chat assistant by ID.
 
 ### Parameters
 
@@ -1307,17 +1310,21 @@ assistant.delete_sessions(ids=["id_1","id_2"])
 
 ---
 
-## Converse
+## Converse with chat assistant
 
 ```python
 Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]]
 ```
 
-Asks a question to start an AI-powered conversation.
+Asks a specified chat assistant a question to start an AI-powered conversation.
+
+:::tip NOTE
+In streaming mode, not all responses include a reference, as this depends on the system's judgement.
+:::
 
 ### Parameters
 
-#### question: `str` *Required*
+#### question: `str`, *Required*
 
 The question to start an AI-powered conversation.
 
@@ -1390,22 +1397,23 @@ while True:
         print(ans.content[len(cont):], end='', flush=True)
         cont = ans.content
 ```
+
 ---
 
-## Create agent session
+## Create session with agent
 
 ```python
 Agent.create_session(id,rag) -> Session
 ```
 
-Creates a agemt session.
+Creates a  session with the current agent.
 
 ### Returns
 
 - Success: A `Session` object containing the following attributes:
   - `id`: `str` The auto-generated unique identifier of the created session.
   - `message`: `list[Message]` The messages of the created session assistant. Default: `[{"role": "assistant", "content": "Hi! I am your assistant，can I help you?"}]`
-  - `agnet_id`: `str` The ID of the associated agent assistant.
+  - `agent_id`: `str` The ID of the associated agent assistant.
 - Failure: `Exception`
 
 ### Examples
@@ -1417,19 +1425,24 @@ rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:
 AGENT_ID = "AGENT_ID"
 session = create_session(AGENT_ID,rag_object)
 ```
+
 ---
 
-## Converse through agent
+## Converse with agent
 
 ```python
 Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]]
 ```
 
-Asks a question to start an AI-powered conversation.
+Asks a specified agent a question to start an AI-powered conversation.
+
+:::tip NOTE
+In streaming mode, not all responses include a reference, as this depends on the system's judgement.
+:::
 
 ### Parameters
 
-#### question: `str` *Required*
+#### question: `str`, *Required*
 
 The question to start an AI-powered conversation.
 
@@ -1489,12 +1502,12 @@ rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:
 AGENT_id = "AGENT_ID"
 session = Agent.create_session(AGENT_id,rag_object)    
 
-print("\n==================== Miss R =====================\n")
+print("\n===== Miss R ====\n")
 print("Hello. What can I do for you?")
 
 while True:
-    question = input("\n==================== User =====================\n> ")
-    print("\n==================== Miss R =====================\n")
+    question = input("\n===== User ====\n> ")
+    print("\n==== Miss R ====\n")
     
     cont = ""
     for ans in session.ask(question, stream=True):