Feat: Add http api to create, update, or delete agents. (#7515)

### What problem does this PR solve? Hello, we are using ragflow as a backend service, so we need to manage agents from our own frontend. So adding these http APIs to manage agents. The code logic is copied and modified from the `rm` and `save` methods in `api/apps/canvas_app.py`. btw, I found that the `save` method in `canvas_app.py` actually allows to modify an agent to an existing title, so I kept the behavior in the http api. I'm not sure if this is intentional. ### Type of change - [ ] Bug Fix (non-breaking change which fixes an issue) - [x] New Feature (non-breaking change which adds functionality) - [x] Documentation Update - [ ] Refactoring - [ ] Performance Improvement - [ ] Other (please describe):
2025-12-08 20:42:30 +08:00 · 2025-05-12 17:59:53 +08:00
parent baa108f5cc
commit 992398bca3
4 changed files with 452 additions and 1 deletions
--- a/docs/references/http_api_reference.md
+++ b/docs/references/http_api_reference.md
@ -3413,3 +3413,190 @@ Failure:

 ---

+### Create agent
+
+**POST** `/api/v1/agents`
+
+Create an agent.
+
+#### Request
+
+- Method: POST
+- URL: `/api/v1/agents`
+- Headers:
+  - `'Content-Type: application/json`
+  - `'Authorization: Bearer <YOUR_API_KEY>'`
+- Body:
+  - `"title"`: `string`
+  - `"description"`: `string`
+  - `"dsl"`: `object`
+
+##### Request example
+
+```bash
+curl --request POST \
+     --url http://{address}/api/v1/agents \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{
+         "title": "Test Agent",
+         "description": "A test agent",
+         "dsl": {
+           // ... Canvas DSL here ...
+         }
+     }'
+```
+
+##### Request parameters
+
+- `title`: (*Body parameter*), `string`, *Required*  
+  The title of the agent.
+- `description`: (*Body parameter*), `string`  
+  The description of the agent. Defaults to `None`.
+- `dsl`: (*Body parameter*), `object`, *Required*  
+  The canvas DSL object of the agent.
+
+#### Response
+
+Success:
+
+```json
+{
+    "code": 0,
+    "data": true,
+    "message": "success"
+}
+```
+
+Failure:
+
+```json
+{
+    "code": 102,
+    "message": "Agent with title test already exists."
+}
+```
+
+---
+
+### Update agent
+
+**PUT** `/api/v1/agents/{agent_id}`
+
+Update an agent by id.
+
+#### Request
+
+- Method: PUT
+- URL: `/api/v1/agents/{agent_id}`
+- Headers:
+  - `'Content-Type: application/json`
+  - `'Authorization: Bearer <YOUR_API_KEY>'`
+- Body:
+  - `"title"`: `string`
+  - `"description"`: `string`
+  - `"dsl"`: `object`
+
+##### Request example
+
+```bash
+curl --request PUT \
+     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{
+         "title": "Test Agent",
+         "description": "A test agent",
+         "dsl": {
+           // ... Canvas DSL here ...
+         }
+     }'
+```
+
+##### Request parameters
+
+- `agent_id`: (*Path parameter*), `string`  
+  The id of the agent to be updated.
+- `title`: (*Body parameter*), `string`  
+  The title of the agent.
+- `description`: (*Body parameter*), `string`  
+  The description of the agent.
+- `dsl`: (*Body parameter*), `object`  
+  The canvas DSL object of the agent.
+
+Only specify the parameter you want to change in the request body. If a parameter does not exist or is `None`, it won't be updated.
+
+#### Response
+
+Success:
+
+```json
+{
+    "code": 0,
+    "data": true,
+    "message": "success"
+}
+```
+
+Failure:
+
+```json
+{
+    "code": 103,
+    "message": "Only owner of canvas authorized for this operation."
+}
+```
+
+---
+
+### Delete agent
+
+**DELETE** `/api/v1/agents/{agent_id}`
+
+Delete an agent by id.
+
+#### Request
+
+- Method: DELETE
+- URL: `/api/v1/agents/{agent_id}`
+- Headers:
+  - `'Content-Type: application/json`
+  - `'Authorization: Bearer <YOUR_API_KEY>'`
+
+##### Request example
+
+```bash
+curl --request DELETE \
+     --url http://{address}/api/v1/agents/58af890a2a8911f0a71a11b922ed82d6 \
+     --header 'Content-Type: application/json' \
+     --header 'Authorization: Bearer <YOUR_API_KEY>' \
+     --data '{}'
+```
+
+##### Request parameters
+
+- `agent_id`: (*Path parameter*), `string`  
+  The id of the agent to be deleted.
+
+#### Response
+
+Success:
+
+```json
+{
+    "code": 0,
+    "data": true,
+    "message": "success"
+}
+```
+
+Failure:
+
+```json
+{
+    "code": 103,
+    "message": "Only owner of canvas authorized for this operation."
+}
+```
+
+---
--- a/docs/references/python_api_reference.md
+++ b/docs/references/python_api_reference.md
@ -1754,4 +1754,133 @@ for agent in rag_object.list_agents():

 ---

+### Create agent

+```python
+RAGFlow.create_agent(
+    title: str,
+    dsl: dict,
+    description: str | None = None
+) -> None
+```
+
+Create an agent.
+
+#### Parameters
+
+##### title: `str`
+
+Specifies the title of the agent.
+
+##### dsl: `dict`
+
+Specifies the canvas DSL of the agent.
+
+##### description: `str`
+
+The description of the agent. Defaults to `None`.
+
+#### Returns
+
+- Success: Nothing.
+- Failure: `Exception`.
+
+#### Examples
+
+```python
+from ragflow_sdk import RAGFlow
+rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
+rag_object.create_agent(
+  title="Test Agent",
+  description="A test agent",
+  dsl={
+    # ... canvas DSL here ...
+  }
+)
+```
+
+---
+
+### Update agent
+
+```python
+RAGFlow.update_agent(
+    agent_id: str,
+    title: str | None = None,
+    description: str | None = None,
+    dsl: dict | None = None
+) -> None
+```
+
+Update an agent.
+
+#### Parameters
+
+##### agent_id: `str`
+
+Specifies the id of the agent to be updated.
+
+##### title: `str`
+
+Specifies the new title of the agent. `None` if you do not want to update this.
+
+##### dsl: `dict`
+
+Specifies the new canvas DSL of the agent. `None` if you do not want to update this.
+
+##### description: `str`
+
+The new description of the agent. `None` if you do not want to update this.
+
+#### Returns
+
+- Success: Nothing.
+- Failure: `Exception`.
+
+#### Examples
+
+```python
+from ragflow_sdk import RAGFlow
+rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
+rag_object.update_agent(
+  agent_id="58af890a2a8911f0a71a11b922ed82d6",
+  title="Test Agent",
+  description="A test agent",
+  dsl={
+    # ... canvas DSL here ...
+  }
+)
+```
+
+---
+
+### Delete agent
+
+```python
+RAGFlow.delete_agent(
+    agent_id: str
+) -> None
+```
+
+Delete an agent.
+
+#### Parameters
+
+##### agent_id: `str`
+
+Specifies the id of the agent to be deleted.
+
+#### Returns
+
+- Success: Nothing.
+- Failure: `Exception`.
+
+#### Examples
+
+```python
+from ragflow_sdk import RAGFlow
+rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
+rag_object.delete_agent("58af890a2a8911f0a71a11b922ed82d6")
+```
+
+---