自定义工作流式智能体 

使用示例自定义工作流式智能体

SuperMap AgentX Server安装包已内置一套自定义工作流示例，本节将以示例文件为例讲解如何使用自定义工作流式智能体。

解压并查看文件

解压并启动SuperMap AgentX Server后，可以在【安装包路径】/custom_workflows/custom_workflow_example内看到如下文件：

  • __init__.py: 工作流示例的入口文件。
  • custom_workflow_example.py: 继承基本类文件。
  • custom_workflow_example_nodes.py: 包含工作流示例中具体执行节点的定义与实现。
  • system_prompt.txt: 工作流式智能体调用大语言模型时使用的系统提示词。

在Fiddler中使用

  1. Fiddler请求信息栏选择 Composer 页签
  2. 在请求方法下拉菜单中选中 POST
  3. 在URL输入框填入API地址：

    http://<ip地址>:8490/agentx/workflow/api/custom/custom_workflow_example

  4. 设置请求头。在Headers区域配置：

    Content-Type: application/json

  5. 填写请求体,在Request Body区域输入JSON数据：

    {
            "messages": [{
                    "role": "user",
                    "content": "10 除以2"
            }]
    }

  6. 点击 Execute 发送请求
    图：Fiddler中发送请求示意
  7. 查看执行结果
    图：Fiddler中查看执行结果
注意：

实际有效JSON应为双引号格式，如"10 除以2"。

 在标准AI-Chat应用中使用（支持OpenAI风格接口）

以 NextChat为例

图：NextChat中使用示例自定义工作流式智能体
  1. 点击设置按钮进入设置页面，设置以下三个参数，其余参数均遵循默认配置
    • 自定义接口：选择“开启”
    • 模型服务商：选择“OpenAI”
    • 接口地址：使用http://<ip地址>:8490/agentx/workflow/api/custom/{custom_workflows下目录名}作为自定义接口地址
      图：NextChat设置项
  2. 点击“新的聊天”，发送指令或问题，即可获取结果
    图：NextChat会话
注意：

由于浏览器的限制，无法在https的网页中向非localhost的地址中发送http请求

以 Cherry Studio为例

图：Cherry Studio中使用示例自定义工作流式智能体
  1. 点击设置按钮进入设置页面，点击模型服务->+添加，填写提供商名称（可自定义），提供商类型选择“OpenAI”；
  2. 设置API地址及模型，其余参数均遵循默认配置。
    • API地址：使用http://<ip地址>:8490/agentx/workflow/api/custom/{custom_workflows下目录名}作为自定义接口地址
    • 模型：点击+添加，输入模型ID、模型名称及分组名称（可自定义）
  3. 点击会话按钮进入对话页面，点击切换至上一步中配置好的模型
    图：Cherry Studio模型切换弹窗
  4. 在对话框中发送指令或问题，即可获取结果。
    图：Cherry Studio会话

使用非示例的工作流式智能体

若需要使用自研的自定义工作流，则需按照以下步骤准备工作流文件、部署与使用。

实现一个自定义工作流 Python文件

  1. CustomWorkflowBase 类说明
    图：CustomWorkflowBase 类说明
    方法 输入 输出 说明 是否重写
    process_input request: BaseModel    dict[str, Any]  提取请求参数。默认返回请求体的字典形式，可通过覆写此方法实现自定义输入处理逻辑。  按需
    process_request request: BaseModel dict[str, Any] 生成graph.astream的输入参数。当stream_mode未指定时，默认组合 values 与 process_input 的结果作为输入。   按需
    process_result    step_result: dict[str, Any] str | dict[str, Any] 格式化输出结果参数。默认提取工作流最后一条消息的 content 字段，支持异常处理机制。     按需
    do_chat args: dict[str, Any]     str | dict     执行工作流图并返回最终结果。内部通过调用 build_graph 实现工作流运行。   按需
    chat request: BaseModel     str | dict 主入口方法，按顺序调用：process_request → do_chat → process_result 完成全流程处理。     按需
    build_graph（抽象方法）     无 CompiledGraph 由子类实现，返回预编译的 LangGraph 工作流图实例，定义业务逻辑执行流程。 必须
    process_config request: BaseModel   RunnableConfig 返回graph运行的RunnableConfig，默认实现会调用process_llm方法生成智能体并注入到RunnableConfig.configurable.llm中方便后续使用   按需
    process_llm request: BaseModel   Runnable （实际上是其实现类 ChatOpenAI）   根据请求体中的参数生成智能体
    1. 按需
  2. CustomWorkflowBase 类继承并实现

    需在Python文件中导入CustomWorkflowBase类，示例文件代码参考：

    from graph.custom_workflow_base import CustomWorkflowBase

    from langgraph.graph.graph import CompiledGraph

    from .custom_workflow_example_nodes import build_graph

    class CustomWorkflow(CustomWorkflowBase):

    def build_graph(self) -> CompiledGraph:

    """主要需要重写的地方，这里直接使用了内置的graph作为演示

    """ return build_graph()

  3. 第三方依赖参考
    技术栈名称 中文名称 基本能力
    langgraph 语言图处理库 构建基于语言模型的工作流，支持创建有状态的多步骤对话系统 
    langgraph-prebuilt 预构建语言图工具 提供预定义的工作流模板，快速实现常见语言处理场景
    langchain-openai LangChain的OpenAI集成 在LangChain框架中无缝接 OpenAI模型  
    langchain-community LangChain社区扩展 提供第三方工具/模型集成   
    langchain-experimental LangChain实验性功能 包含前沿但未稳定的新特性，供开发者提前试用
    langchain-mcp-adapters LangChain的MCP适配器  实现LangChain与MCP系统间的协议转换和数据交互
    uvicorn ASGI服务器 轻量级服务器，用于运行FastAPI等ASGI应用，支持热重载 
    concurrent-log-handler 并发日志处理器 多进程安全的日志记录工具，支持日志轮转和高并发场景  
    mcp MCP工具 MCP工具，专为大模型设计的数据交互标准
    InquirerPy 命令行交互式问答工具 在终端创建交互式问卷，支持单选/多选/输入等UI组件
    json-repair JSON修复工具 自动修复格式错误的JSON数据，处理缺失引号/注释等非标准结构
    jinja2 Jinja2模板引擎    动态生成文本内容（HTML/配置文件等），支持变量替换和逻辑控制
    python-dotenv 环境变量加载工具   从.env文件加载配置参数，实现开发/生产环境隔离
    pydantic 数据验证和设置管理库 通过类型注解验证数据结构，提供配置管理和序列化功能
    chromadb Chroma向量数据库 轻量级嵌入向量存储，支持相似性搜索和高效检索
    gradio 快速构建机器学习UI的工具 创建交互式模型演示界面，支持输入/输出组件
    fastembed 快速文本嵌入库   高性能文本向量化工具，优化嵌入生成速度
    jsonref JSON引用解析工具 解析JSON中的$ref引用，实现跨文档数据引用和去重
    langchain-chroma LangChain的Chroma集成 在LangChain中直接操作ChromaDB，实现检索增强生成（RAG）工作流
    python-consul2 Consul客户端 服务发现与配置管理工具，实现分布式系统的健康检查和动态配置
    watchdog 文件系统监控工具   实时监控文件/目录变化（创建/修改/删除），触发事件回调

部署自定义工作流

  1. 解压并启动SuperMap AgentX Server后，把上述写好的Python模块目录(含资源文件) , 复制到【安装包路径】/custom_workflows目录下。
    • 每个自定义工作流必须作为独立子目录部署，子目录名称即为工作流 ID
  2. 自定义工作流目录下文件加载顺序
    • 当目录下有 __init__.py 文件时，优先从此文件加载 CustomWorkflowBase类的实现类
    • 如果 __init__.py缺失或加载失败，则扫描当前目录（不含子目录）下的所有 .py 文件，自动识别首个有效的 CustomWorkflowBase 实现类
  3. AgentX Server启动后，即可动态发现，自动加载Python文件

使用自定义工作流式文件 

请参考“使用示例自定义工作流式智能体”->在Fiddler中使用/在标准AI-Chat应用中使用（支持OpenAI风格接口）