Relf-Agent：轻量起步，灵活编排

做一个 Agent，最让人犹豫的往往不是第一条 Prompt，而是接下来的选择：要先部署数据库吗？流程固定时能不能按步骤执行，遇到复杂任务又能不能动态规划？以后想换模型、加知识库，会不会要重新搭一遍？

我开源的 Relf-Agent，围绕这些问题做了一个比较明确的选择：用可运行的模板降低起步成本，用可组合的组件承接后续变化。

它是一个 Python Agent 开发框架。安装后可以生成独立工程，先用本地 SQLite 跑通任务，再选择静态工作流、动态 Plan/DAG、多 Agent 团队、RAG 和记忆。等应用确实需要服务化或独立 Worker，再增加对应基础设施。

如果只记住一句话：开箱有模板，编排可静可动，知识与工具按需接入，本地运行不必先搭一套服务。

一分钟概览

• 开箱起步： 内置工单、RAG、静态图、Plan、Team 等独立工程模板，可以看到代码、配置和实际运行结果。
• 编排灵活： 已知流程用顺序或静态图；任务步骤需要边做边判断时，用受约束的动态规划与 DAG。
• 知识完整接入： 文档摄取、词法检索、向量检索、混合召回和重排有对应实现与扩展入口。
• 架构可以拆开改： 模型、工具、上下文、会话、记忆和检索组件分别接入，业务逻辑可以保留为普通 Python 函数。
• 部署逐级增加成本： Local + SQLite 是低依赖起点；HTTP 服务与 Temporal 后端分别需要额外配置。
• 执行有控制： 关键写操作可以审批，任务保留执行记录，中断后依据原配置和证据恢复。

项目入口：官网 · GitHub · 文档目录 · 开源项目栏目

Relf-Agent：模板起步，按需组合静态动态编排、RAG 与工具

图 1：从一个 Agent 起步，按任务选择编排方式，再组合知识与工具。白底原创动图，是能力地图，不表示所有能力默认开启。依据基础能力与编排指南绘制。

1. 开箱即用，具体能拿到什么

对开发框架来说，“开箱即用”应当落实到一个可以运行和修改的工程，而不只是接口列表。Relf-Agent 的 ralf init 会生成应用代码、配置和说明，安装 wheel 后也能使用，不必先克隆整个源码仓库。

例如，按安装指南装好 SDK 后，在目标工程的父目录中生成一个新的知识助手目录：

ralf init my-knowledge-agent --template rag
cd my-knowledge-agent
python -m agent_app --query '缓存连接失败怎么恢复'

这段入口按官方 RAG 模板文档核对，本轮未重新安装公开 wheel 执行。模板用真实摄入的本地种子文档验证检索与引用链路，默认 Provider 是离线的，不会偷偷调用付费模型。目标目录需是新目录，不能拿已有项目目录来覆盖。

开箱就绪的是应用骨架、默认组件与执行链路。 接入自己的模型要配置凭据，接入业务要替换工具，真实回答质量也要单独评估。它不是安装后就拥有全部业务知识的成品助手。各模板的运行方式见示例与独立工程模板。

2. 编排可静可动：流程明确就固定，需要探索再规划

“支持工作流”和“支持多 Agent”很容易写成两个功能标签。真正使用时，更重要的是：下一步由谁决定，又受哪些约束？

静态编排：开发者先定义路径

假设工单处理一直遵循“读取工单 → 查手册 → 形成建议 → 复核”，这些步骤和依赖可以提前确定，就适合顺序 Workflow 或静态图。

静态图可以声明依赖、条件分支、输入映射、结果合并，并显式开启有界并行。节点按各自合同承载 Agent、受管理工具或纯数据变换。相互独立的检查可以并行，依赖前一步结果的节点则等待结果就绪。

例如，“查服务状态”和“查最近变更”可以同时进行，诊断步骤等两者完成再开始。静态指的是图的结构预先定义，不代表每个节点都是硬编码，也不代表不能按条件选择分支。 节点中的 Agent 仍可根据任务调用允许的工具。

优势是路径清楚、输入输出可查，适合规则稳定、验收明确的任务。具体接口见静态图和有界并行。

动态编排：执行过程中提出计划，再受控推进

如果问题是“调查这次异常的原因”，事先未必知道需要哪些步骤。可能先看日志，再决定查配置；也可能发现信息不足，需要补充检索。

Relf-Agent 的动态编排提供两类路径：

• Plan： 提出一批任务，执行后验证，必要时在有限次数内重新规划。
• 动态 DAG： 用 plan_mode="dag" 表达带依赖的计划；独立就绪节点按并发上限执行，后续节点显式引用前序结果。

规划器可以采用规则，也可以通过受管理的模型子任务生成计划。模型给出的是待验证的计划提案，框架会检查成员是否在允许名单、依赖是否有效、输入引用是否合法，以及步数、修订次数、并发和额度是否超限。

动态 DAG 还提供显式的计划修订入口，但已派发、完成或跳过的节点被冻结；对待执行节点的修改也要保留修订记录。“动态”是允许计划变化，不是允许 Agent 随意增加工具、绕过审批或改写已经发生的结果。 这也不意味着 DAG 本身可以有环；重新规划属于图外的控制过程。

相关实现见动态规划与动态 DAG。

静态图预先定义依赖，动态编排受约束地产生与修订计划

图 2：两种方式都可以调用模型，区别在于流程结构如何确定。右侧虚线是有限重规划的控制关系，不是 DAG 中的循环边。依据上述静态、动态编排文档绘制。

Team：有角色分工，不必每次都动态规划

多 Agent 团队解决的是“谁来做、如何汇总”。当前提供顺序协作、规则路由和 Supervisor 等策略：可以顺序传递结果，也可以把独立任务交给多个 Worker，再由指定成员汇总。

Team 和动态规划并不是一回事。一个固定的“研究 → 复核”团队也可以完全不需要模型规划。它们可以在所支持的范围内嵌套，但使用复杂组合之前，应先把单独的步骤验收清楚。

我的选择原则是：能预先确定的流程先固定下来，把真正需要判断的部分留给模型。这样既保留灵活性，也方便定位问题；没有必要为了“多 Agent”而增加调度成本。

3. RAG、记忆和工具：让 Agent 有资料，也有行动能力

RAG 是一条可组合的链路

知识问答要解决的不只是“连一个向量库”。资料怎样进入系统、如何分块、用什么召回、怎样重排、最终答案依据哪一版文档，都是应用需要处理的部分。

Relf-Agent 已有文档摄取与分块、知识版本与来源记录、词法检索、向量检索、混合召回和重排等能力。你可以从本地 SQLite 与词法检索开始，再替换 Embedding、向量索引或重排器。

混合检索可以并行召回不同分支，再通过 RRF 等融合方法组织候选，必要时重排。这里的优势是链路可以逐层调整：换 Embedding 不等于要重写会话逻辑，换检索器也不等于要更换整个 Agent。

默认离线 HashEmbedding 与词项基线用于验证装配，不能代表真实语义检索效果。需要语义能力时要显式配置相应模型或服务，并用自己的问题集验证。输入来源校验也不能代替最终答案引用校验。详见混合检索。

会话、长期记忆与上下文各自分工

• Session / Turn： 组织当前会话与每轮任务，让用户能接着追问。
• Facts： 保存应用确认、允许跨轮保留的事实，带作用域与版本。
• Knowledge / RAG： 保存并检索外部文档，不把全部资料塞进聊天历史。
• Context： 决定这一轮实际提供给模型哪些历史、记忆和证据。

例如，“刚才讨论的工单”属于会话，“用户确认的通知偏好”可以进入 Facts，“操作手册”属于知识库。明确分工后，历史召回、长期记忆和知识检索可以分别改进。

工具接入优先复用现有代码

一个 Python 业务函数可以通过 ToolRegistry 注册成工具：

from ralf_agent import ToolRegistry

tools = ToolRegistry()

@tools.tool(effect="read_only", description="查询测试工单")
def lookup_ticket(ticket_id: str):
    return {"ticket_id": ticket_id, "status": "open"}

这只是工具定义片段，还需配置 Provider 和 Agent 才会运行。受支持的类型注解用于生成输入 Schema，工具集合控制模型能调用哪些能力。真正的业务查询可以留在函数体里，写操作则进一步配置效果类别、审批与核验方式。

已有服务、固定脚本或外部工具，还可以按需评估 HTTP、CLI 和 MCP 接入；Workspace 与 Skills 则提供工作资料和操作说明的组织方式。它们都有独立支持边界，不能把“有一个集成入口”理解为任意外部系统都已适配。模型与工具 SDK是最直接的起点。

4. 扩展性来自哪里：把需要变化的部分拆开

我希望保留的一个使用体验是：先用默认实现跑起来，遇到真实需求时再替换某一层，而不是从第一天就要求开发者实现全部接口。

Relf-Agent 的任务、知识组件、执行内核与后端分层

图 3：上层组合任务，中间替换协作组件，执行内核检查并保存事实。Local 与 Temporal 有各自的执行权威，不是同一个数据库上的两个开关。依据执行组件与扩展指南绘制。

多数明确端口采用结构化接口接入，不要求继承一棵庞大的框架类树。Python 代码和 JSON/TOML 配置可以分别承担业务实现与运行装配，详见运行装配。

扩展也有边界。组件要提供稳定身份、正确管理资源，并遵守作用域与恢复契约；部分受管理记忆、上下文能力有专门的继承或绑定要求。高层 Local / Temporal Facade 也不是能任意替换底层引擎的通用容器。

例如，换检索器可以改变送给模型的资料，不能顺便改变已批准的工具参数。可替换的是协作实现，不能被顺便替换的是原任务已经发生的事实。

5. 部署方便吗：本地轻，服务化按需增加依赖

如果目标是本地开发或单宿主应用，起步依赖比较少；如果目标是多人服务或独立 Worker，就要承担对应的部署工作。 这两件事应该分开评价。

本地运行：Python 环境加 SQLite

核心运行依赖是 httpx 与 jsonschema，默认执行与知识示例使用本地 SQLite。无需先准备 Redis、PostgreSQL、Temporal、Docker 或向量数据库，也不强制要求真实模型密钥。

因此可以先生成工程、检查配置、看一次任务如何执行，再决定是否接付费模型和外部服务。数据与配置也比较直观，适合开发、学习和单宿主上的小场景。

当前安装文档面向 Linux / macOS，公开制品列有具体已测平台。纯 Python wheel 不等于原生 Windows 已验收。 本文没有新增 Windows 平台测试，跨平台使用应先核对安装指南和 Release 范围。

HTTP 服务：有模板，但仍需配置认证和运行环境

a2a 模板提供可编辑的 ASGI 任务服务与客户端。默认本地路径不要求 Redis 或 PostgreSQL，但要安装 server 可选依赖，并显式配置拥有者令牌；任务接受与任务完成通过原任务 ID 区分。

默认服务采用单 HTTP Worker、单 Local Coordinator。部署到服务器时，还要处理 TLS、凭据、持久化目录、备份、进程管理与监控。企业身份、ACL 和故障切换不因为启动了服务就自动具备。具体见异步服务指南。

Temporal：为独立执行后端增加基础设施

Temporal 路径需要服务连接、Worker、队列和匹配的发布配置；某些组合还需要额外存储与组件。它以原 Workflow History 为执行权威，不是给 Local 换一个远程数据库就完成的迁移。

它有独立支持的能力子集和实验性边界，不能把本地路径的运行结果直接当成该后端已验收。选择前应阅读Temporal 执行与相应组合指南。

安装某个 extra 只会安装客户端依赖，不会替你创建对应数据库或服务。我的建议是：先把 Local 做好，只有实际需求出现时，再增加运行基础设施。

6. 为什么还把审批与恢复放进框架

能接工具、做编排以后，Agent 就可能真的修改业务数据。此时“回答说完成了”与“业务确实完成了”必须分开。

Relf-Agent 用 Run 标识任务，用 Action 记录模型或工具动作。关键写入可以暂停审批；已经保存的模型响应和工具回执可以在恢复时继续处理，不必从头再做整个任务。

Relf-Agent 在审批等待、已有回执与未知写效果下的恢复路径

图 4：恢复先看证据。审批等待继续处理原待办，已有结果继续采纳，写入结果不明时先核验。依据恢复指南绘制。

比如建议已经写回工单，但本地没收到确认，直接重试可能多发一条评论。工具效果声明、业务幂等键和查询接口共同决定怎么处理，不能仅靠框架宣称“恰好执行一次”。

审批通过也不等于写入完成，取消后续调度不会撤销已发出的业务操作。原代码、组件身份、配置和执行数据需要一起保留，才能按相应版本的规则恢复。这个底座让前面的灵活编排仍有可检查的执行边界。

7. 适合谁，现在该怎样看它

如果你想用 Python 构建内部助手、知识问答、分步诊断或调研复核流程，希望从模板开始，再逐层替换组件，Relf-Agent 值得进入候选名单。

我认为它的吸引力可以收敛为四点：本地起步依赖少，有可修改的工程模板；静态与动态编排可以按任务选择；RAG、记忆和工具能够逐层组合；执行控制不会只留在一段临时对话里。 这些是设计取舍，不是相对其他框架的性能或效果排名。

如果只是一次性文本生成，直接调用模型 API 可能更省事。如果要的是成熟的企业身份平台、托管服务、任意版本无缝恢复或已经验证的高可用部署，当前 Alpha 不应承担这些承诺。

普通 Python 工具在可信宿主运行，不自动获得沙箱隔离；整数 execution credits 是执行额度，不是金额或供应商 Token 硬上限。扩展集成和后端组合以实现清单及安全说明为准。

当前版本与阅读入口

截至 2026-10-23，源码在准备 0.1.0a4 候选，公开安装推荐仍为 v0.1.0a2 Alpha，尚未发布到 PyPI。项目采用 Apache-2.0 许可。

展示名称与仓库是 Relf-Agent / relf-agent；发行包仍为 ralf-agent，Python 导入为 ralf_agent，命令是 ralf。按安装指南选精确制品，不要凭名称猜安装命令。

想了解项目，可以先看官网；想真正判断适不适合自己，则从首用教程或连续工单教程选择一个小场景，检查这五件事：

1. 能否用内置模板跑通，而不先增加不必要的服务？
2. 固定流程是否能直接表达，动态任务是否真的需要规划？
3. 资料是否正确召回，回答依据是否能核对？
4. 能否只替换自己的模型或工具，而保留其他部分？
5. 拒绝审批时是否没有写入，中断后是否能依据原记录继续？

先用最少的组件完成一件具体的事，再根据问题增加能力。这是 Relf-Agent 希望提供的开发路径，也是我会继续打磨这个项目的方向。源码与问题反馈在 GitHub，后续实践记录会更新到开源项目栏目。