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

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

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

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

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

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

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

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

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

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：验证远程智能体的签名收据

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