本文介绍了一套ComfyUI自定义节点，允许用户通过可视化方式设计、部署和管理基于RunPod云的Agentic工作流，将复杂的AI代理系统编排简化为节点图操作。

CRAG节点：用ComfyUI可视化编排Agentic工作流\n\n## 引言\n\n随着AI Agent技术的快速发展，如何高效地设计、部署和管理复杂的代理工作流成为开发者面临的重要挑战。传统的代码编写方式虽然灵活，但对于快速原型设计和可视化调试并不友好。comfyui-runpod-agentic-nodes（简称CRAG节点）项目创新性地将ComfyUI的节点式工作流理念引入Agentic系统领域，让用户可以通过拖拽连接的方式构建和部署云端AI代理。\n\n## 项目概述\n\nCRAG节点是一套ComfyUI自定义节点集合，专为在RunPod云平台上设计、运行和管理Agentic工作流而设计。它遵循一个核心原则：除"Run on Runpod"节点外，所有节点都是声明式的——它们定义了期望的状态，而非执行具体的操作。\n\n### 核心理念\n\n声明式配置：用户通过节点图描述期望的系统状态，包括代理配置、浏览器环境、LLM服务、数据库连接等，而具体的创建、连接、清理操作由系统自动处理。\n\n可视化编排：将复杂的Agentic系统架构转化为直观的节点图，降低设计和沟通成本。\n\n云原生部署：与RunPod云平台深度集成，支持按需创建和销毁GPU实例，优化成本效率。\n\n## 核心组件解析\n\n### 1. 资源节点\n\nCRAG节点提供了丰富的资源类型，覆盖Agentic系统的各个层面：\n\n#### Agent节点\n\nAgent节点是系统的核心，支持配置：\n- 代理框架（OpenCode、Codex、Pi等）\n- 模型选择（Claude、GPT、Ollama本地模型等）\n- 系统提示词\n- MCP服务器连接\n- 技能框架集成\n\n#### 浏览器节点\n\n支持两种浏览器后端：\n- Neko：基于容器的远程浏览器方案\n- Playwright：自动化浏览器测试框架\n\n#### LLM服务节点\n\n提供灵活的模型服务选项：\n- LLM Server：在RunPod上部署vLLM或Ollama服务\n- LLM API：直接调用OpenAI、Anthropic等云API\n\n#### 数据库节点\n\n- Remote SQL：远程PostgreSQL或MySQL服务\n- Local SQL：本地SQLite数据库\n- Vector Database：Chroma或Qdrant向量数据库\n\n#### 存储节点\n\n- Network Storage：RunPod网络存储卷\n- S3 Storage：兼容S3的对象存储\n\n### 2. 编排节点\n\n#### Run on Runpod\n\n这是唯一非声明式的节点，负责实际执行部署计划。支持多种运行模式：\n\n- plan：生成部署计划但不执行，用于预览和验证\n- apply：执行部署计划\n- apply_and_wait：执行部署并等待完成\n- stop/terminate/destroy：管理Pod生命周期\n\n#### Keep Alive\n\n配置Pod的保活策略：\n- 基于时间的自动停止\n- 基于回合数的自动停止\n- 基于成本的自动停止\n- 手动控制模式\n\n#### SSH Command\n\n在Pod启动前后执行自定义命令，用于环境准备、依赖安装等。\n\n### 3. MCP与技能集成\n\n#### MCP Server节点\n\n支持连接各类MCP（Model Context Protocol）服务器：\n- stdio模式：本地命令行工具\n- http/sse模式：远程HTTP服务\n- 内置支持文件系统、数据库、搜索等常用工具\n\n#### Skill Framework节点\n\n自动下载和配置流行的Agent技能框架，如Superpowers，扩展代理能力。\n\n## 工作流示例\n\n### 示例1：Claude数据代理\n\n\nLLM API(provider=Claude, model=claude-sonnet, secret=anthropic_key)\nMCP Server(name=filesystem, transport=stdio, command=npx, args=\"-y @modelcontextprotocol/server-filesystem /workspace\")\nSkill Framework(framework=Superpowers, target_root=/workspace/.codex/skills)\nRemote SQL Database(engine=Postgres, connection_mode=own_pod, database=app, username=app, secret=pg_password)\nVector Database(engine=Qdrant, collection=docs)\nBrowser(browser=Playwright, placement=same_pod)\nAgent(harness=OpenCode, model=claude-sonnet, system_prompt=\"Follow repository conventions.\", mcp_servers=MCP Server)\nSSH Command(phase=before_start, command=\"pip install -e /workspace/tools\")\nNetwork Storage(volume_id=..., mount=/workspace)\nKeep Alive(mode=time, value=30 minutes, action=stop)\nRunpod Pod(app=Agent, network_storage=Network Storage, commands=SSH Command, keep_alive=Keep Alive)\nRun on Runpod(mode=plan or apply, prompt=\"Implement the requested change.\")\n\n\n这个工作流展示了如何构建一个功能完整的数据处理代理：Claude模型 + 文件系统MCP + Postgres数据库 + Qdrant向量库 + Playwright浏览器。\n\n### 示例2：本地LLM服务\n\n\nLLM Server(engine=vLLM, model=Qwen/Qwen3-0.6B, placement=own_pod)\nAgent(harness=Codex, llm=LLM Server)\nRunpod Pod(app=Agent)\nRun on Runpod(mode=apply)\n\n\n这个简化示例展示了如何在RunPod上部署vLLM服务，并配置代理使用本地模型。\n\n## 部署计划生成\n\n当运行"plan"模式时，系统会生成有序的部署计划：\n\n\nPlan order:\nCREATE_OR_RESUME sql\nCREATE_OR_RESUME vector\nWAIT_READY sql\nWAIT_READY vector\nRESOLVE_DEPENDENCY_CONTRACTS\nCREATE_OR_RESUME agent\nWAIT_SSH agent\nRUN_SSH_COMMAND before_start\nWRITE_RUNTIME_CONFIG\nLAUNCH_AGENT\nMONITOR_KEEP_ALIVE\n\n\n这个计划展示了系统的智能编排能力：\n- 自动识别依赖关系（数据库先于代理创建）\n- 等待资源就绪后再进行下一步\n- 注入运行时配置（如数据库连接字符串）\n- 监控生命周期，自动执行保活策略\n\n## 开发与测试\n\n### 本地开发\n\n项目提供了完整的开发工具链：\n\nbash\npython -m pip install -e .[dev]\nscripts/test # 运行单元测试\nscripts/lint # 代码检查\nscripts/build # 构建发布包\n\n\n### 测试策略\n\n项目采用了良好的测试设计：\n- 单元测试：使用模拟的RunPod和SSH客户端，无需真实凭证\n- E2E测试：在临时ComfyUI环境中验证节点加载\n- 截图测试：自动生成工作流UI截图用于文档\n\n### 安全设计\n\n- API密钥通过环境变量注入，不出现在工作流JSON中\n- 支持测试模式，使用假客户端验证逻辑\n- 敏感操作需要显式确认\n\n## 技术架构亮点\n\n### 类型化部署图\n\nCRAG节点构建了一个类型化的部署图，在计划阶段进行依赖分析和合约验证，提前发现配置错误。\n\n### 状态管理\n\n使用SQLite数据库存储运行状态，包括：\n- 资源创建记录\n- 运行历史\n- 事件日志\n- 计数器统计\n\n### 可测试性\n\n通过依赖注入实现可测试架构：\n- RunPod客户端可替换为模拟实现\n- SSH操作可注入测试行为\n- 状态存储可配置为内存模式\n\n## 应用场景\n\n### 快速原型设计\n\n通过可视化节点图快速搭建Agentic系统原型，验证架构设计的可行性。\n\n### 团队协作\n\n节点图作为系统架构的可视化文档，便于团队成员理解和讨论设计方案。\n\n### 教学演示\n\n直观展示Agentic系统的组成和工作原理，适合技术分享和培训场景。\n\n### 生产部署\n\n经过验证的工作流可以直接用于生产部署，声明式配置确保环境一致性。\n\n## 未来展望\n\nCRAG节点代表了AI系统部署工具的一个重要方向——将基础设施即代码（IaC）的理念与可视化编排相结合。未来可能的发展包括：\n\n- 支持更多云平台（AWS、GCP、Azure）\n- 引入Terraform等IaC工具集成\n- 工作流版本管理和回滚\n- 成本分析和优化建议\n- 多区域部署支持\n\n## 结语\n\ncomfyui-runpod-agentic-nodes项目展示了如何将ComfyUI的节点式工作流理念应用于Agentic系统领域。它不仅是一个工具，更是一种新的设计和部署范式——通过声明式配置和可视化编排，让复杂的AI代理系统变得易于理解、设计和管理。对于正在探索Agentic工作流的开发者来说，这是一个值得关注和尝试的项目。

CRAG节点：用ComfyUI可视化编排Agentic工作流\n\n引言\n\n随着AI Agent技术的快速发展，如何高效地设计、部署和管理复杂的代理工作流成为开发者面临的重要挑战。传统的代码编写方式虽然灵活，但对于快速原型设计和可视化调试并不友好。comfyui-runpod-agentic-nodes（简称CRAG节点）项目创新性地将ComfyUI的节点式工作流理念引入Agentic系统领域，让用户可以通过拖拽连接的方式构建和部署云端AI代理。\n\n项目概述\n\nCRAG节点是一套ComfyUI自定义节点集合，专为在RunPod云平台上设计、运行和管理Agentic工作流而设计。它遵循一个核心原则：除"Run on Runpod"节点外，所有节点都是声明式的——它们定义了期望的状态，而非执行具体的操作。\n\n核心理念\n\n声明式配置：用户通过节点图描述期望的系统状态，包括代理配置、浏览器环境、LLM服务、数据库连接等，而具体的创建、连接、清理操作由系统自动处理。\n\n可视化编排：将复杂的Agentic系统架构转化为直观的节点图，降低设计和沟通成本。\n\n云原生部署：与RunPod云平台深度集成，支持按需创建和销毁GPU实例，优化成本效率。\n\n核心组件解析\n\n1. 资源节点\n\nCRAG节点提供了丰富的资源类型，覆盖Agentic系统的各个层面：\n\nAgent节点\n\nAgent节点是系统的核心，支持配置：\n- 代理框架（OpenCode、Codex、Pi等）\n- 模型选择（Claude、GPT、Ollama本地模型等）\n- 系统提示词\n- MCP服务器连接\n- 技能框架集成\n\n浏览器节点\n\n支持两种浏览器后端：\n- Neko：基于容器的远程浏览器方案\n- Playwright：自动化浏览器测试框架\n\nLLM服务节点\n\n提供灵活的模型服务选项：\n- LLM Server：在RunPod上部署vLLM或Ollama服务\n- LLM API：直接调用OpenAI、Anthropic等云API\n\n数据库节点\n\n- Remote SQL：远程PostgreSQL或MySQL服务\n- Local SQL：本地SQLite数据库\n- Vector Database：Chroma或Qdrant向量数据库\n\n存储节点\n\n- Network Storage：RunPod网络存储卷\n- S3 Storage：兼容S3的对象存储\n\n2. 编排节点\n\nRun on Runpod\n\n这是唯一非声明式的节点，负责实际执行部署计划。支持多种运行模式：\n\n- plan：生成部署计划但不执行，用于预览和验证\n- apply：执行部署计划\n- apply_and_wait：执行部署并等待完成\n- stop/terminate/destroy：管理Pod生命周期\n\nKeep Alive\n\n配置Pod的保活策略：\n- 基于时间的自动停止\n- 基于回合数的自动停止\n- 基于成本的自动停止\n- 手动控制模式\n\nSSH Command\n\n在Pod启动前后执行自定义命令，用于环境准备、依赖安装等。\n\n3. MCP与技能集成\n\nMCP Server节点\n\n支持连接各类MCP（Model Context Protocol）服务器：\n- stdio模式：本地命令行工具\n- http/sse模式：远程HTTP服务\n- 内置支持文件系统、数据库、搜索等常用工具\n\nSkill Framework节点\n\n自动下载和配置流行的Agent技能框架，如Superpowers，扩展代理能力。\n\n工作流示例\n\n示例1：Claude数据代理\n\n\nLLM API(provider=Claude, model=claude-sonnet, secret=anthropic_key)\nMCP Server(name=filesystem, transport=stdio, command=npx, args=\"-y @modelcontextprotocol/server-filesystem /workspace\")\nSkill Framework(framework=Superpowers, target_root=/workspace/.codex/skills)\nRemote SQL Database(engine=Postgres, connection_mode=own_pod, database=app, username=app, secret=pg_password)\nVector Database(engine=Qdrant, collection=docs)\nBrowser(browser=Playwright, placement=same_pod)\nAgent(harness=OpenCode, model=claude-sonnet, system_prompt=\"Follow repository conventions.\", mcp_servers=MCP Server)\nSSH Command(phase=before_start, command=\"pip install -e /workspace/tools\")\nNetwork Storage(volume_id=..., mount=/workspace)\nKeep Alive(mode=time, value=30 minutes, action=stop)\nRunpod Pod(app=Agent, network_storage=Network Storage, commands=SSH Command, keep_alive=Keep Alive)\nRun on Runpod(mode=plan or apply, prompt=\"Implement the requested change.\")\n\n\n这个工作流展示了如何构建一个功能完整的数据处理代理：Claude模型 + 文件系统MCP + Postgres数据库 + Qdrant向量库 + Playwright浏览器。\n\n示例2：本地LLM服务\n\n\nLLM Server(engine=vLLM, model=Qwen/Qwen3-0.6B, placement=own_pod)\nAgent(harness=Codex, llm=LLM Server)\nRunpod Pod(app=Agent)\nRun on Runpod(mode=apply)\n\n\n这个简化示例展示了如何在RunPod上部署vLLM服务，并配置代理使用本地模型。\n\n部署计划生成\n\n当运行"plan"模式时，系统会生成有序的部署计划：\n\n\nPlan order:\nCREATE_OR_RESUME sql\nCREATE_OR_RESUME vector\nWAIT_READY sql\nWAIT_READY vector\nRESOLVE_DEPENDENCY_CONTRACTS\nCREATE_OR_RESUME agent\nWAIT_SSH agent\nRUN_SSH_COMMAND before_start\nWRITE_RUNTIME_CONFIG\nLAUNCH_AGENT\nMONITOR_KEEP_ALIVE\n\n\n这个计划展示了系统的智能编排能力：\n- 自动识别依赖关系（数据库先于代理创建）\n- 等待资源就绪后再进行下一步\n- 注入运行时配置（如数据库连接字符串）\n- 监控生命周期，自动执行保活策略\n\n开发与测试\n\n本地开发\n\n项目提供了完整的开发工具链：\n\nbash\npython -m pip install -e .[dev]\nscripts/test 运行单元测试\nscripts/lint 代码检查\nscripts/build 构建发布包\n\n\n测试策略\n\n项目采用了良好的测试设计：\n- 单元测试：使用模拟的RunPod和SSH客户端，无需真实凭证\n- E2E测试：在临时ComfyUI环境中验证节点加载\n- 截图测试：自动生成工作流UI截图用于文档\n\n安全设计\n\n- API密钥通过环境变量注入，不出现在工作流JSON中\n- 支持测试模式，使用假客户端验证逻辑\n- 敏感操作需要显式确认\n\n技术架构亮点\n\n类型化部署图\n\nCRAG节点构建了一个类型化的部署图，在计划阶段进行依赖分析和合约验证，提前发现配置错误。\n\n状态管理\n\n使用SQLite数据库存储运行状态，包括：\n- 资源创建记录\n- 运行历史\n- 事件日志\n- 计数器统计\n\n可测试性\n\n通过依赖注入实现可测试架构：\n- RunPod客户端可替换为模拟实现\n- SSH操作可注入测试行为\n- 状态存储可配置为内存模式\n\n应用场景\n\n快速原型设计\n\n通过可视化节点图快速搭建Agentic系统原型，验证架构设计的可行性。\n\n团队协作\n\n节点图作为系统架构的可视化文档，便于团队成员理解和讨论设计方案。\n\n教学演示\n\n直观展示Agentic系统的组成和工作原理，适合技术分享和培训场景。\n\n生产部署\n\n经过验证的工作流可以直接用于生产部署，声明式配置确保环境一致性。\n\n未来展望\n\nCRAG节点代表了AI系统部署工具的一个重要方向——将基础设施即代码（IaC）的理念与可视化编排相结合。未来可能的发展包括：\n\n- 支持更多云平台（AWS、GCP、Azure）\n- 引入Terraform等IaC工具集成\n- 工作流版本管理和回滚\n- 成本分析和优化建议\n- 多区域部署支持\n\n结语\n\ncomfyui-runpod-agentic-nodes项目展示了如何将ComfyUI的节点式工作流理念应用于Agentic系统领域。它不仅是一个工具，更是一种新的设计和部署范式——通过声明式配置和可视化编排，让复杂的AI代理系统变得易于理解、设计和管理。对于正在探索Agentic工作流的开发者来说，这是一个值得关注和尝试的项目。