仓颉语言实现的智能体开发平台CangjieMagic体验与实战

什么是CangjieMagic

AI Agent是智能体的基础，它以大模型为核心，集决策能力、记忆能力、工具调用能力为一体。现在主流的AI框架或者工具的开发语言是Python，比如langchain框架，它是一个大语言模型智能框架。现在Java生态对AI Agent的逐步完善，比如Langchain4J、Spring都对AI开发提供了支持。

CangjieMagic是基于仓颉语言开发的一套AI智能体框架，Magic是Make Apps Grow Intelligence and Creativity的简写。它的主要特点包括：Agent DSL、支持 MCP 协议，支持模块化调用，支持任务智能规划。

仓颉语言介绍

为什么要用仓颉语言做一套AI框架？我们先介绍下仓颉语言与仓颉语言的特点。

仓颉编程语言是一种面向全场景应用开发的通用编程语言，可以兼顾开发效率和运行性能，并提供良好的编程体验，主要具有如下特点：

• 多后端支持：仓颉编程语言支持 CJNative 和 CJVM 两种后端。其中 CJNative 后端将代码编译为原生二进制代码，直接在操作系统层面上运行；CJVM 后端将代码编译为字节码，基于 VM（虚拟机）进行运行。
• 语法简明高效：仓颉编程语言提供了一系列简明高效的语法，旨在减少冗余书写、提升开发效率，例如插值字符串、主构造函数、Flow 表达式、match、if-let、while-let 和重导出等语法，让开发者可以用较少编码表达相关逻辑。
• 多范式编程：仓颉编程语言支持函数式、命令式和面向对象等多范式编程，融合了高阶函数、代数数据类型、模式匹配、泛型等函数式语言的先进特性，还有封装、接口、继承、子类型多态等支持模块化开发的面向对象语言特性，以及值类型、全局函数等简洁高效的命令式语言特性。开发者可以根据开发偏好或应用场景，选用不同的编程范式。
• 类型安全：仓颉编程语言是静态强类型语言，通过编译时类型检查尽早识别程序错误，降低运行时风险，也便于代码维护。同时，仓颉编译器提供了强大的类型推断能力，可以减少类型标注工作，提高开发效率。
• 内存安全：仓颉编程语言支持自动内存管理，并在运行时进行数组下标越界检查、溢出检查等，确保运行时内存安全。
• 高效并发：仓颉编程语言提供了用户态轻量化线程（原生协程），以及简单易用的并发编程机制，保证并发场景的高效开发和运行。
• 兼容语言生态：仓颉编程语言支持和 C 等主流编程语言的互操作，并采用便捷的声明式编程范式，可实现对其他语言库的高效复用和生态兼容。
• 领域易扩展：仓颉编程语言提供了基于词法宏的元编程能力，支持在编译时变换代码，此外，还提供了尾随 lambda、属性、操作符重载、部分关键字可省略等特性，开发者可由此深度定制程序的语法和语义，有利于内嵌式领域专用语言（Embedded Domain Specific Languages，EDSL）的构建。
• 助力 UI 开发：UI 开发是构建端侧应用的重要环节，基于仓颉编程语言的元编程和尾随 lambda 等特性，可以搭建声明式 UI 开发框架，提升 UI 开发效率和体验。
• 内置库功能丰富：仓颉编程语言提供了功能丰富的内置库，涉及数据结构、常用算法、数学计算、正则匹配、系统交互、文件操作、网络通信、数据库访问、日志打印、解压缩、编解码、加解密和序列化等功能。

我们在选择编程语言时无外乎考虑两点，开发效率和运行性能，比如JS系列开发效率高，但是运行性能比较差，C、C++运行效率高，但是开发效率又差强人意，而仓颉综合了效率和性能问题，两方面都有不错的表现。而且广泛吸收的总舵语言特性的特长，让仓颉成为真正意义的面向全场景应用开发的通用编程语言。

AI Agent介绍

我们理解的 AI Agent是一种能够自主决策、采取行动以达到某种目标的实体。下面是一个AI Agent的定义：
基于人工智能（尤其是大模型）技术，能够感知和理解环境，并采取行动以完成目标的智能实体。

AI Agent 主要依托LLM模型和具体的业务场景来调用相应的工具来完成任务目标，智能化程度和行业贴合度会更明显。下面我们以一张图了解AI Agent有哪些内容组成：

从图中我们可以看到AI Agent有下面三部分组成：

• 感知模块 ：负责收集外界信息，通过传感器获取原始数据，再经过感知处理将其转化为有意义的信息供决策模块使用。
• 决策模块 ：基于感知到的信息、知识库中的知识以及学习到的经验，利用推理引擎进行分析和判断，做出合理的决策。
• 行动模块 ：根据决策结果，通过行动规划制定具体的行动方案，再由执行器实际执行行动，对外界环境产生影响。

下面是怎对上面模块跟详细展开的架构图：

这里面提到的工具，有我们使用ChatAI最常见的”联网“搜索等。
![[仓颉语言实现的智能体开发平台CangjieMagic体验与实战.png]]

CangjieMagic如何实现AI Agent设计

在CangjieMagic中，使用仓颉语言的元编程，对上面图中提到的AI Agent模块进行了抽象和定义。以Agent为例，定义了@agent宏，我们要使用时直接使用@agent修饰我们的类，就可以将我们的类编程Agent入口：

@agent class HarmonyOSQA { 
}

宏 @agent 支持如下属性:

属性名	值类型	说明
description	String	Agent 的功能描述；默认未设置时，将由 LLM 从提示词中自动总结出
model	String	配置使用到的 LLM 模型服务；默认使用 gpt-4o
tools	Array	配置能够使用的外部工具
mcp	Array	配置接入的 MCP 服务器
rag	Map	配置外部的知识源
memory	Bool	是否使用记忆，即保存 Agent 的多次问答记录（目前记忆仅支持 in-memory 非持久化数据）；默认为 false
executor	String	规划模式；默认为 react
temperature	Float	Agent 使用 LLM 时的 temperature 值；默认为 0.5
dump	Bool	调试代码用，是否打印 Agent 变换后的 AST；默认为 false
CangjieMagic同时定义了prompt、ai等宏。比如@ai 可用于修饰函数，其接收的属性和 @agent 一致。 被 @ai 修饰的函数体内可包含任意多个插值字符串，这些字符串将依次拼接组成提示词，并交由指定的模型生成输出。

@ai[model: "deepseek:deepseek-chat"]
func foo(topic: String): String {
    "根据主题 ${topic} 生成一份 PPT 内容"
    "输出格式为 JSON"
}

宏 @prompt 支持设置 pattern 属性，其值应为提示词模式类型。使用提示词模式时，@prompt 作用域内必须编写满足模式的_提示词元素_而不是字符串字面量。

@agent
class Foo {
    @prompt[pattern: APE] (
        action: "帮助用户制定旅行路线",
        purpose: "让用户在计划的时间内尽可能多地参观景点并得到充分休息",
        expectation: "生成一条合理的旅行路线，包括时间、景点、通勤等信息"
    )
}

从CangjieMagic源码中一方面可以看到仓颉中宏对于设计框架有很大帮助，另一方面可以方向从CangjieMagic中学习到AI Agent的知识。

CangjieMagic开发智能体实战

接下来体验使用CangjieMagic开发智能体。

环境搭建

首先搭建开发环境，根据官方文档一步一步实现。
首先通过 cjpm init 新建项目：

添加对本项目的依赖，修改新建项目的 cjpm.toml，可以通过源码依赖和git依赖配置：
方式一 直接配置 git 依赖：

[dependencies]
  magic = { git = "https://gitcode.com/Cangjie-TPC/CangjieMagic.git", branch = "dev" }

方式二 下载项目代码并配置本地源码依赖

[dependencies]
  magic = { path = "../CangjieMagic" }

这里遇到个问题，修改完配置执行cjpm update时报错：

root package 'magic' imports package 'std.log' in its source code, but it is not added as a dependency in cjpm.toml

因为目前代码仅在 Cangjie 0.56.4（通用版）和 0.53.18/4（鸿蒙外发版）上能够正确编译执行，我用的是较新版本所以报错，下载0.56.4版本即可成功运行。

接下来拷贝如下代码至 main.cj 中，并在代码中设置大语言模型服务商的 API key。

import magic.dsl.*
import magic.prelude.*
import magic.config.Config

@agent[model: "deepseek:deepseek-chat"]
class BlackCatAssistant {
    @prompt(
        "你是黑猫警长的助手"
        "当接到群众通知后，你需要唱起黑猫警长的专属 BGM 并安抚群众情绪"
    )
}

main() {
    Config.env["DEEPSEEK_API_KEY"] = "<your api key>"

    let agent = BlackCatAssistant()
    let result = agent.chat("一只耳来啦")
    println(result)
}

API Key直接在deepseek官方申请即可，可以夜里或者早上调试，API价格便宜一半。

最后执行 cjpm run --name HarmonyOSAgent 运行项目：
![[仓颉语言实现的智能体开发平台CangjieMagic体验与实战-2.png]]

开发实战

CangjieMagic项目src下面有个examples目录，下面配置了一些示例。我们以markdow_qa为例开发一个智能体。
示例代码如下：

package HarmonyOSNextAgent

import magic.dsl.*
import magic.prelude.*
import magic.config.Config
import magic.model.ModelManager

import log.LogLevel

@agent[
    model: "deepseek:deepseek-chat",
    executor: "naive",
    rag: {
        source: "../CangjieMagic/docs/tutorial.md",
        mode: "static"
    }
]
class QABot {
    @prompt[pattern: ERA] (
        expectation: "代码块被标签 ```cangjie 和 ```包裹",
        role: "简单问答助手",
        action: "搜索文档获取知识并回答问题"
    )
}

main () {
    Config.logLevel = LogLevel.INFO
    Config.defaultEmbeddingModel = ModelManager.createEmbeddingModel("ollama:qwen2.5:7b")
	Config.env["DEEPSEEK_API_KEY"] = "xxxx"
    let bot = QABot()
    let aresp = bot.asyncChat("Agent RAG 怎么编写")
    for (chunk in aresp) {
        print(chunk)
    }
    println("\n---end---")
    if (let Some(info) <- aresp.execInfo) {
        for (info in info.retrievalInfo) {
            for (doc in info.retrieval.sources) {
                println(doc.metadata)
            }
        }
    }
}

通过ModelManager.createEmbeddingModel创建模型，这里我用了本地ollama的qwen2.5，rag资源解析的是CangjieMagic中的tutorial.md，执行cjpm run --name HarmonyOSNextAgent后开始解析文档生成向量并输出：

最后输出内容：

可以看到效果还是很不错的。

基于CangjieMagic开发新闻自动抓取工具

上面是官方示例的效果，接下来我们基于CangjieMagic框架实现一个自动抓取新闻的Agent。这个Agent可以帮助我们输入关键词，基于我们预定的网站搜索最新新闻，并总结新闻内容，帮助我们节省看新闻浪费的时间。

下面我们先上基于CangjieMagic的代码框架：

package HarmonyOSNextAgent


import magic.dsl.*
import magic.prelude.*
import std.time.DateTime


@tool[description: "从网页检索新闻内容",
      parameters: {
          msg: "新闻关键词"
      }
]
func getNews(msg: String): String {
    println(">>>>>> ${msg} <<<<<")
    return "Done"
}

@agent[model: "deepseek:deepseek-chat",
       tools: [getNews]]
class NewsAgent {
    @prompt(
        """
        根据输入关键词从网页搜索新闻
        仅使用已有工具
        """
    )
}

main() {
    let newsAgent = NewsAgent()
    let group = newsAgent
    let resp = group.chat(AgentRequest("HarmonyOSNext 微信最新版"))
    println(resp.content)
}

这里我们主要介绍工具的定义，通过@tool定义工具，这里面我们可以根据输入的关键词通过webdriver工具在特定网站检索关键词，并把最终内容返回回来。对于一些复杂的关键词，我们可以通过group组合多个Agent来一起完成工作。具体实现可以期待后续开源。

总结

CangjieMagic是基于仓颉语言开发的AI智能体框架，旨在简化Agent开发流程，支持决策、记忆和工具调用等核心功能。该框架利用仓颉语言的元编程特性（如@agent、@ai宏）实现高效开发，并支持多模型（如GPT-4、Claude3）、RAG知识检索及任务规划。仓颉语言凭借多后端支持、简明语法和内存安全等优势，成为构建AI框架的理想选择。实战部分展示了问答Agent和新闻抓取工具的开发，通过@tool定义自定义功能，结合LLM实现智能任务执行。CangjieMagic为开发者提供了灵活、高效的AI Agent解决方案，适用于复杂业务场景的智能化需求。