# Decision Agent

中文 | [English](README.md)

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.txt)

Decision Agent 是 KWeaver 生态的一部分。如果您喜欢这个项目，欢迎也给 **[KWeaver](https://github.com/kweaver-ai/kweaver-core)** 项目点个 ⭐！

## 📚 快速链接

- 🐛 [报告 Bug](https://github.com/kweaver-ai/kweaver-core/issues) - 报告问题或 Bug
- 💡 [功能建议](https://github.com/kweaver-ai/kweaver-core/issues) - 提出新功能建议
- 📘 [用户手册](docs/user_manual/README.md) - 概念、REST API、CLI、SDK 与可运行示例
- 🍳 [Cookbook](docs/cookbook/README.md) - 按场景组织的 Decision Agent 接入菜谱

## Decision Agent 定义

Decision Agent 是将业务知识网络加载形成高质量的上下文，再通过 Agent 框架实现多智能体协同，进行规划、推理、执行及安全控制的一种专有 Agent。

Decision Agent 是以业务知识网络为统一业务语义基础，融合企业多源异构数据、业务系统与自动化流程，通过 ContextLoader 动态精准构建高质量上下文，并由 Dolphin 动态编排引擎驱动多智能体完成规划、推理、行动与工具调用闭环，在全链路可观测、可评测、可审计等机制保障下，借助大语言模型实现 Data+AI 落地企业核心业务场景的专有智能体。

## Decision Agent 的关键需求

- **降低智能体开发复杂性：业务逻辑强耦合、难复用**
  - 业务语义/指标口径分散，Agent配置者需要把语义逻辑写进Prompt及控制链路里，导致Agent配置业务场景适应力差，Decision Agent强耦合了业务逻辑。
  - 多系统工具接入碎片化（接口、参数、错误处理不统一），集成与编排成本被放大。

- **维护与优化困难：上线后不可观测、不可回归，优化靠人肉**
  - 业务规则、数据口径、模型版本一变就波动，但缺少标准评测与回归集，问题只能线上"救火"。
  - 缺少运行轨迹与失败原因沉淀（调用了什么数据/工具、哪里错），难定位也难形成可迭代闭环。

- **难以形成高质量上下文：上下文难"可信、完整、可控"**
  - 多源异构数据口径冲突、时效不一致，Agent缺少证据优先级与约束时容易推理漂移。
  - 权限与动态状态下的上下文难按人按岗装配：要么信息不足导致答错，要么越权带来风险。

- **多智能体协同难：协作协议不统一导致内耗与失真**
  - Agent之间输入输出标准不一致，信息在多轮传递中被压缩、丢关键约束，结果偏离目标。
  - 缺少全局调度/仲裁/冲突治理机制，多Agent容易循环、争论或重复劳动，成本飙升。

- **安全控制风险链路不完善：核心链路不可信导致难以进行核心生产链路**
  - 推理与执行链路不可追溯（用什么数据、调什么工具、为何这样做），出错难追责复盘。
  - 提示词注入与越权调用风险突出，工具权限、数据脱敏、审批留痕不完善时无法进入核心生产链路。

## Decision Agent 的技术目标

### 1. 降低智能体开发复杂性：语义建模解耦与低代码装配

通过业务知识网络实现业务语义建模的解耦，统一完成结构化/非结构化数据的语义对齐与指标口径标准化，消除硬编码复杂语义逻辑的依赖；通过无代码/低代码模型定义（Agent角色、Dolphin指令及技能配置），实现Agent组件化复用，支持快速迁移至新业务场景，降低开发门槛与定制成本。

- **业务知识网络统一语义建模**：在业务知识网络中统一抽象现实世界中的概念和对象、关系、逻辑和行动，统一了所有指标和业务语义，实现所有Agent全局复用，而无需在每个Agent中单独重复定义业务语义。
- **智能体节点嵌入**：允许将不同Agent（如数据治理Agent、情报分析Agent）作为"节点"嵌入流程，实现跨Agent的协同。
- **流程复用**：通过模板化流程（如"数据清洗-分析-报告"），降低企业定制Agent的开发成本，实现完全无代码配置方式。

### 2. 提高维护与优化效率：Agent全生命周期自动化闭环

基于运行轨迹数据（上下文、推理、工具、权限环节）快速定位问题根源，通过Benchmark与效果评估驱动自动优化（提示词、工具参数、业务知识网络定义），结合人工审核核心配置，实现"配置-测评-运行-可观测-优化"的自动化闭环，提升Agent稳定性与迭代效率。

- **观测**：通过Dolphin Runtime的可观测模块，收集Agent的运行数据（如性能指标、错误日志）。
- **优化**：基于观测数据，自动调整Agent参数（如：Plan策略、模型权重、召回策略等）。

### 3. 高质量上下文：精准装配与按需加载

依托业务知识网络与ContextLoader实现跨系统、跨会话的精准上下文加载（替代粗放向量检索），结合权限策略与Memory（按人/岗/任务及Agent状态动态装配），减少上下文噪声与越权风险，提升Agent任务执行的准确性。

- **概念召回**：基于知识图谱或语义理解，提取上下文中的核心概念。
- **对象召回**：基于识别的概念通过语义转换精准召回上下文中的实体数据。
- **Pre-Ranking/Re-Ranking**：基于配置不同的召回策略并自动关联合适的排序算法，筛选与任务最相关的上下文。

### 4. 多智能体协同：统一语义与动态调度

基于统一语义协议与Dolphin调度引擎，实现Agent间任务动态分工与自动编排，通过共享Memory（多Agent传递任务状态、业务知识网络语义）降低协作失真与孤岛效应，提升多Agent协同效率。

- **上下文压缩**：可能采用自研算法（如动态上下文裁剪、语义压缩），减少推理时的内存占用。
- **协程调度**：通过轻量级协程管理，优化多任务并发（如同时处理数据查询、工具调用）。
- **状态机管理**：将Agent的决策过程（Plan-Reason-Act）抽象为状态机，确保流程的可控性与可追溯性。
- **可观测**：内置监控指标（如推理延迟、错误率、资源占用），为"观测-优化"环节提供数据支撑。

### 5. 安全控制：全链路可审计的防御围栏

通过安全策略层（权限校验、敏感信息过滤、提示词注入防护）与工具调用白名单/最小权限，结合Human-in-the-loop审批（关键动作），实现全链路可追踪、可审计，满足企业合规、风控与责任界定需求。

- **角色与访问策略**：基于角色的访问控制（RBAC）的访问控制，限制不同用户对Agent的权限。
- **日志审计**：记录Agent的所有操作（如Plan决策、Act执行），满足等保、GDPR等合规要求。
- **数据安全服务**：支持数据加密、数据脱敏、敏感数据检测与过滤、提示词注入防护等安全能力。

## Decision Agent 的业务价值

- **决策提效：从"信息生产"到"决策驱动"**
  - 把数据收集、对口径、分析撰写的"人力成本"转化为可复用的决策资产，让管理动作更快、更一致。如经营复盘/周月报场景，面向销量下滑、利润波动、TopN异常等问题自动拉齐口径，输出可上会的结论、归因、关键证据与行动建议。

- **知识可信：从"口口相传"到"有据可查"**
  - 统一企业内部对同一问题的答案口径，回答可追溯、可复核，降低沟通成本与误判风险。如在业务问答场景，DecisionAgent基于ContextLoader统一召回多源信息，并引用业务知识网络的来源依据，输出"结论 + 证据链"。

- **流程自动化：从"人肉串联"到"闭环交付"**
  - 把跨部门任务变成可执行、可追踪、可审批的标准流程，显著减少协作内耗与反复返工。如专项汇报材料/运营跟进场景，将"查询—分析—撰写—校验—审批—落地"串为AutoFlow；不同节点由不同Agent分工完成，人只做关键确认/审批，任务自动推进到交付。

- **数据资产可用：从"事后救火"到"持续稳定可用"**
  - 持续降低指标口径冲突与数据质量问题对业务的影响，沉淀"同一套数"的长期能力。当指标异常、口径冲突、数据源变更发生时，DecisionAgent自动定位影响范围与差异点，生成治理建议并联动工单/流程推动闭环处理。

- **风险可控：从"不可用的黑盒"到"可审计的生产能力"**
  - 在不牺牲效率的前提下，保证数据与行为合规可控，让AI能够进入核心业务链路。财务/法务/人事/客户数据等敏感场景，敏感数据访问与关键操作引入权限边界、审批留痕与全链路追溯；输出可复核、可回放，满足审计与内控要求。

## 产品架构图

```text
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                               Decision Agent 应用                                        │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐    │
│  │ 数据治理Agent │ │ 情报分析Agent │ │ 质量探测Agent │ │ 运维分析Agent │ │ 报告生成Agent │    │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘    │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                          Decision Agent 生命周期管理                                      │
│              配置 → 测试 → 发布 → 运行 → 观测 → 优化                                   │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                                  核心组件                                            │
│  ┌─────────────────────────────────────────────────────────────────────────────┐   │
│  │  Autoflow: 智能体节点嵌入 → Node → Node → Node (可编排流程复用)                   │
│  ├─────────────────────────────────────────────────────────────────────────────┤   │
│  │  信息安全编织ISF: 统一身份认证 | 角色与访问策略 | 日志及审计 | 数据安全服务          │
│  ├─────────────────────────────────────────────────────────────────────────────┤   │
│  │  模型工厂: 通用模型 | 行业模型                                                   │
│  ├─────────────────────────────────────────────────────────────────────────────┤   │
│  │  业务知识网络:                                                                  │
│  │    数据(非结构化/结构化/机器数据) → 查找数据                                       │
│  │    逻辑(方法或函数/领域模型) → 查找算子                                           │
│  │    行动(API/MPC) → 查找行动                                                     │
│  ├─────────────────────────────────────────────────────────────────────────────┤   │
│  │  ContextLoader: 概念召回 | 对象召回 | Pre-Ranking | Re-Ranking | 系统提示词       │
│  ├─────────────────────────────────────────────────────────────────────────────┤   │
│  │  Dolphin Runtime:                                                              │
│  │    Plan → Act → Reason (闭环) | 协程调度 | 上下文压缩 | 状态机管理 | 可观测         │
│  └─────────────────────────────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────────────────────────────┤
│                              交互与流程                                              │
│  主控Agent ─┬→ 数据召回Agent → 数据召回 → 返回数据                                    │
│             ├→ 工具调用Agent → 工具调用 → 返回数据                                    │
│             └→ 结果生成Agent → 结果生成 → 返回结果                                    │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

## 贡献指南

我们欢迎贡献！请查看我们的[贡献指南](../rules/CONTRIBUTING.zh.md)了解如何为项目做出贡献。

快速开始：

1. Fork 代码库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 代码质量

本项目使用 pre-commit hooks 进行代码质量检查。根目录配置会调度到各子项目的独立配置。

### 从根目录执行 Lint

```bash
make lint
```

### Git Commit（自动触发）

`git commit` 时会自动运行 pre-commit hooks：

```bash
git commit -m "your message"
```

### 按子项目手动执行 Lint

```bash
# agent-executor (Python)
cd agent-backend/agent-executor && make lint

# agent-memory (Python)
cd agent-backend/agent-memory && make lint

# agent-factory (Go)
cd agent-backend/agent-factory && make lint
```

## 开发者 API 文档

如果你想快速生成或查看 REST API 生成文档，可以执行：

```bash
cd agent-backend/agent-factory
make gen-api-docs
make validate-api-docs
```

相关说明：

- [对外文档使用说明](agent-backend/agent-factory/docs/api/README.md)
- [Agent Factory README](agent-backend/agent-factory/README.zh.md)

## 旧版 API Chat 对接指南

推荐入口已经切换为 [Decision Agent 用户手册](docs/user_manual/README.md)。旧版 API Chat 对接说明仍保留在这里，供查阅历史内容：

- English: [agent-backend/agent-factory/docs/api-chat-integration.md](agent-backend/agent-factory/docs/api-chat-integration.md)
- 中文: [agent-backend/agent-factory/docs/api-chat-integration.zh.md](agent-backend/agent-factory/docs/api-chat-integration.zh.md)

## 许可证

本项目采用 Apache License 2.0 许可证。详情请参阅 [LICENSE](LICENSE.txt) 文件。

## 支持与联系

- **贡献指南**: [贡献指南](../rules/CONTRIBUTING.zh.md)
- **问题反馈**: [GitHub Issues](https://github.com/kweaver-ai/kweaver-core/issues)
- **许可证**: [Apache License 2.0](LICENSE.txt)

---

后续更多组件开源，敬请期待！
