Update the component of the agent API with parameters. (#4131)

### What problem does this PR solve? Update the component of the agent API with parameters. ### Type of change - [x] Bug Fix (non-breaking change which fixes an issue) - [x] New Feature (non-breaking change which adds functionality) - [x] Refactoring --------- Co-authored-by: liuhua <10215101452@stu.ecun.edu.cn> Co-authored-by: Kevin Hu <kevinhu.sh@gmail.com> Co-authored-by: writinwaters <93570324+writinwaters@users.noreply.github.com>
2025-12-08 20:42:30 +08:00 · 2024-12-20 17:34:16 +08:00
parent a0dc9e1bdf
commit 35580af875
8 changed files with 152 additions and 185 deletions
--- a/docs/references/http_api_reference.md
+++ b/docs/references/http_api_reference.md
@ -1346,7 +1346,7 @@ Creates a chat assistant.
 curl --request POST \
     --url http://{address}/api/v1/chats \
     --header 'Content-Type: application/json' \
-     --header 'Authorization: Bearer <YOUR_API_KEY>'
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --data '{
    "dataset_ids": ["0b2cbc8c877f11ef89070242ac120005"],
    "name":"new_chat_1"
@ -2160,9 +2160,11 @@ Creates a session with an agent.
  - `'content-Type: application/json'`
  - `'Authorization: Bearer <YOUR_API_KEY>'`
 - Body:
+  - the required parameters:`str`
+  - the optional parameters:`str`

 ##### Request example
-
+If `begin` component in the agent doesn't have required parameters:
 ```bash
 curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/sessions \
@ -2171,6 +2173,17 @@ curl --request POST \
     --data '{
     }'
 ```
+If `begin` component in the agent has required parameters:
+```bash
+curl --request POST \
+     --url http://{address}/api/v1/agents/{agent_id}/sessions \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{
+            "lang":"Japanese",
+            "file":"Who are you"
+     }'
+```

 ##### Request parameters

@ -2326,8 +2339,8 @@ Asks a specified agent a question to start an AI-powered conversation.
  - `"session_id"`: `string`
  - other parameters: `string`
 ##### Request example
-
-```bash
+If the `begin` component doesn't have parameters, the following code will create a session.
+```bash 
 curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
     --header 'Content-Type: application/json' \
@ -2336,6 +2349,19 @@ curl --request POST \
     {
     }'
 ```
+If the `begin` component have parameters, the following code will create a session.
+```bash
+curl --request POST \
+     --url http://{address}/api/v1/agents/{agent_id}/completions \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data-binary '
+     {
+          "lang":"English",
+          "file":"How is the weather tomorrow?"
+     }'
+```
+The following code will execute the completion process
 ```bash
 curl --request POST \
     --url http://{address}/api/v1/agents/{agent_id}/completions \
@ -2348,17 +2374,6 @@ curl --request POST \
          "session_id": "cb2f385cb86211efa36e0242ac120005"
     }'
 ```
-```bash
-curl --request POST \
-     --url http://{address}/api/v1/agents/{agent_id}/completions \
-     --header 'Content-Type: application/json' \
-     --header 'Authorization: Bearer <YOUR_API_KEY>' \
-     --data-binary '
-     {
-          "lang":"English"
-          "file":"How is the weather tomorrow?"
-     }'
-```


 ##### Request Parameters
@ -2394,113 +2409,41 @@ data:{
    "data": true
 }
 ```
-Success with `session_id` provided and with no parameters in the `begin` component:
+Success without `session_id` provided and with parameters in the `begin` component:

 ```json
 data:{
    "code": 0,
    "message": "",
    "data": {
+        "session_id": "eacb36a0bdff11ef97120242ac120006",
        "answer": "",
        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
+        "param": [
+            {
+                "key": "lang",
+                "name": "Target Language",
+                "optional": false,
+                "type": "line",
+                "value": "English"
+            },
+            {
+                "key": "file",
+                "name": "Files",
+                "optional": false,
+                "type": "file",
+                "value": "How is the weather tomorrow?"
+            },
+            {
+                "key": "hhyt",
+                "name": "hhty",
+                "optional": true,
+                "type": "line"
+            }
+        ]
    }
 }
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello!",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I assist",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I assist you",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I assist you today",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I assist you today?",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": {
-        "answer": "Hello! How can I assist you today?",
-        "reference": [],
-        "id": "7ed5c2e4-aa28-4397-bbed-59664a332aa0",
-        "session_id": "ce1b4fa89c1811ef85720242ac120006"
-    }
-}
-data:{
-    "code": 0,
-    "data": true
-}
+data:
 ```
 Success with parameters in the `begin` component:
 ```json
--- a/docs/references/python_api_reference.md
+++ b/docs/references/python_api_reference.md
@ -1,4 +1,4 @@
---
+from scipy.special import kwargs---
 sidebar_position: 2
 slug: /python_api_reference
 ---
@ -1312,7 +1312,7 @@ assistant.delete_sessions(ids=["id_1","id_2"])
 ### Converse with chat assistant

 ```python
-Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]]
+Session.ask(question: str = "", stream: bool = False, **kwargs) -> Optional[Message, iter[Message]]
 ```

 Asks a specified chat assistant a question to start an AI-powered conversation.
@ -1325,7 +1325,7 @@ In streaming mode, not all responses include a reference, as this depends on the

 ##### question: `str`, *Required*

-The question to start an AI-powered conversation.
+The question to start an AI-powered conversation. Defalut to `""`

 ##### stream: `bool`

@ -1334,6 +1334,10 @@ Indicates whether to output responses in a streaming way:
 - `True`: Enable streaming (default).
 - `False`: Disable streaming.

+##### **kwargs
+
+The parameters in prompt(system).
+
 #### Returns

 - A `Message` object containing the response to the question if `stream` is set to `False`.
@ -1402,11 +1406,25 @@ while True:
 ### Create session with agent

 ```python
-Agent.create_session(id,rag) -> Session
+Agent.create_session(id,rag, **kwargs) -> Session
 ```

 Creates a session with the current agent.

+#### Parameters
+
+##### id: `str`, *Required*
+
+The id of agent
+
+##### rag:`RAGFlow object`
+
+The RAGFlow object
+
+##### **kwargs
+
+The parameters in `begin` component.
+
 #### Returns

 - Success: A `Session` object containing the following attributes:
@ -1430,7 +1448,7 @@ session = create_session(AGENT_ID,rag_object)
 ### Converse with agent

 ```python
-Session.ask(question: str, stream: bool = False) -> Optional[Message, iter[Message]]
+Session.ask(question: str="", stream: bool = False) -> Optional[Message, iter[Message]]
 ```

 Asks a specified agent a question to start an AI-powered conversation.
@ -1441,9 +1459,9 @@ In streaming mode, not all responses include a reference, as this depends on the

 #### Parameters

-##### question: `str`, *Required*
+##### question: `str`

-The question to start an AI-powered conversation.
+The question to start an AI-powered conversation. If the `begin` component takes parameters, a question is not required.

 ##### stream: `bool`