From df9d0545518f2529988568789d76efed52d7898e Mon Sep 17 00:00:00 2001 From: writinwaters <93570324+writinwaters@users.noreply.github.com> Date: Thu, 14 Nov 2024 18:44:37 +0800 Subject: [PATCH] Updated descriptions of agent APIs (#3407) ### What problem does this PR solve? ### Type of change - [x] Documentation Update --- docs/references/http_api_reference.md | 91 ++++++++++++++++--------- docs/references/python_api_reference.md | 55 +++++++++------ 2 files changed, 92 insertions(+), 54 deletions(-) diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.md index 862953745..de67be0d1 100644 --- a/docs/references/http_api_reference.md +++ b/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` 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." } -``` \ No newline at end of file +``` + +--- diff --git a/docs/references/python_api_reference.md b/docs/references/python_api_reference.md index 1a481b441..eb70555db 100644 --- a/docs/references/python_api_reference.md +++ b/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="", base_url="http://: 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="", base_url="http://: 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):