# kdeps：用YAML编排AI智能体的声明式框架

> kdeps是一个实验性的AI智能体编排框架，通过声明式YAML配置将大语言模型、数据库和API统一编排，无需编写胶水代码即可构建复杂的智能体工作流。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-02T02:15:11.000Z
- 最近活动: 2026-04-02T02:25:31.690Z
- 热度: 157.8
- 关键词: AI-agent, YAML, orchestration, workflow, RAG, federation, deterministic
- 页面链接: https://www.zingnex.cn/forum/thread/kdeps-yamlai
- Canonical: https://www.zingnex.cn/forum/thread/kdeps-yamlai
- Markdown 来源: ingested_event

---

## 智能体生产的痛点：不一致性与不可追溯

AI智能体在概念验证阶段往往表现亮眼，但一旦进入生产环境，就会暴露出一系列工程问题。最核心的问题是**不一致性**：同样的输入在不同时间可能产生不同的输出，缺乏审计轨迹，出现问题时难以调试和复现。

传统的智能体实现通常采用命令式编程模式，开发者需要编写大量的胶水代码来连接不同的组件——调用LLM的代码、访问数据库的代码、调用外部API的代码，以及将这些步骤串联起来的编排逻辑。这种模式下，业务逻辑散落在各处，系统行为难以预测，维护成本随复杂度指数增长。

## kdeps的核心理念：有序、可重复的系统

kdeps项目提出了一种截然不同的方法论：**将AI智能体视为有序、可重复的系统（Ordered, Repeatable Systems）**。这一理念通过声明式配置和确定性执行来实现，具体体现在三个维度：

**有序（Ordered）**：通过声明式YAML定义每一个执行步骤，以图结构明确指定执行顺序。没有隐藏逻辑，没有意外的工具调用，系统的行为完全由配置决定。

**可重复（Repeatable）**：相同的输入产生相同的输出。通过确定性的管道和版本控制的智能体定义，保证执行结果的一致性。

**系统（Systems）**：将LLM、数据库和API统一在一个规格中描述，无需胶水代码，无需遗留桥接。

## YAML驱动的智能体定义

kdeps的核心创新在于使用YAML作为智能体的定义语言。一个典型的kdeps工作流文件如下所示：

```yaml
apiVersion: kdeps.io/v1
kind: Resource
metadata:
  actionId: analyze
run:
  before:
    - scraper:
        type: url
        source: "{{ get('url') }}"
    - embedding:
        operation: search
        input: "{{ get('scraper').content }}"
        collection: docs
  chat:
    model: gpt-4o
    prompt: |
      Context: {{ get('embedding').results }}
      Data: {{ get('scraper').content }}
      Question: {{ get('q') }}
  apiResponse:
    success: true
    response:
      data: "{{ output('analyze') }}"
```

这个示例展示了一个典型的RAG（检索增强生成）工作流：首先通过scraper提取网页内容，然后通过embedding进行向量检索，最后将检索结果和原始内容一起输入给大语言模型生成回答。整个过程通过YAML声明式定义，无需编写任何胶水代码。

## 丰富的资源类型支持

kdeps提供了广泛的资源类型，覆盖了智能体应用的常见需求：

**数据获取与处理**：scraper支持从15种以上文件类型提取文本；embedding提供向量RAG的索引和搜索能力；file和input支持访问上传文件和硬件输入数据。

**模型交互**：chat资源支持Ollama、OpenAI、Anthropic、Groq等多种LLM提供商，支持流式输出和MCP工具服务器集成。

**外部系统集成**：httpClient用于REST API调用；sql支持Postgres、MySQL、SQLite、Oracle等数据库；email支持SMTP发送和IMAP读取；calendar支持ICS文件读写。

**代码执行**：python资源通过隔离的uv环境执行脚本；exec支持shell命令和自动化任务。

**高级功能**：browser提供Playwright浏览器自动化；tts支持文本转语音；pdf支持从HTML或Markdown生成PDF；search集成Brave、SerpAPI、DuckDuckGo、Tavily等搜索服务。

**智能体协作**：agent支持将工作委托给同一agency中的其他智能体；remoteAgent支持联邦智能体调用（UAF），通过Ed25519签名收据实现跨组织协作。

## 多层次的抽象与组合

kdeps设计了多层次的抽象机制，支持从简单工作流到复杂智能体系统的渐进式构建：

**Workflow（工作流）**：单个YAML文件定义一个可执行的工作流，是最基础的构建单元。

**Agency（智能体机构）**：通过agency.yaml将多个智能体打包在一个清单下，指定targetAgentId作为入口点。支持自动发现和.kagency归档格式，可以将整个机构打包成一个可移植文件。

**Component（组件）**：通过component.yaml定义可复用的接口和实现，支持自动加载和.komponent归档分发，实现智能体能力的模块化复用。

这种分层设计使得开发者可以从简单场景开始，随着需求增长逐步引入更复杂的抽象，而无需推倒重来。

## 开发工具链与部署选项

kdeps提供了完整的CLI工具链，覆盖开发、验证、打包、部署的全生命周期：

- `kdeps run`：执行工作流或机构，支持热重载
- `kdeps new`：通过交互式向导创建新项目
- `kdeps validate`：检查YAML语法和逻辑
- `kdeps package`：打包工作流、机构或组件
- `kdeps build`：从工作流或机构创建Docker镜像
- `kdeps push`：实时更新运行中的容器
- `kdeps export iso`：生成可启动的边缘计算ISO
- `kdeps prepackage`：打包为特定架构的自包含可执行文件

部署选项的多样性是kdeps的一大特色。除了传统的Docker部署，还支持生成可启动ISO用于边缘计算场景，以及打包为原生可执行文件用于资源受限环境。

## 联邦智能体与信任机制

kdeps在智能体协作方面进行了前瞻性探索，提出了联邦智能体（Federation）的概念。通过Ed25519密钥对实现跨组织的智能体调用和身份验证：

- `kdeps federation keygen`：生成组织的密钥对
- `kdeps federation register`：在UAF注册表中注册智能体
- `kdeps federation trust add`：添加注册表信任锚点
- `kdeps federation receipt verify`：验证远程智能体的签名收据

这一设计为构建跨组织的智能体协作网络奠定了基础，在保持去中心化架构的同时提供了必要的信任机制。

## 实验性质与生产建议

需要特别指出的是，kdeps目前处于高度实验阶段。官方文档明确说明API、YAML模式、CLI标志和行为可能在任何时候无预警地更改，不建议在生产环境中使用。

对于希望尝试的开发者，建议从实验性项目开始，密切关注版本更新和破坏性变更。同时，项目的快速迭代也意味着新功能和改进会持续加入，保持关注可以获得最新的智能体编排能力。

## 总结

kdeps代表了一种构建AI智能体的新范式——从命令式编程转向声明式配置，从胶水代码转向统一编排。尽管目前仍处于实验阶段，但其设计理念和实现方式为解决智能体生产化面临的根本挑战提供了有价值的思路。对于希望探索下一代智能体开发模式的团队，kdeps是一个值得关注的项目。