如何让 AI 智能体更聪明CangjieMagic-Examples 中 tool 注解与任务规划的完整指南【免费下载链接】CangjieMagic-Examples项目地址: https://gitcode.com/Cangjie/CangjieMagic-ExamplesCangjieMagic-Examples是 Cangjie Magic 框架的官方示例仓库它用三个真实项目端侧智能体MagicAgent、RAG 代码助手CangjieRAGCodeAssistant、MCP 工具服务集合CangjieMagicMCPServer演示了智能体开发中最核心的两件事用tool注解把普通函数变成大模型可调用、可自主规划的工具。读完本文你就能理解工具设计模式是怎么让 Agent 从会聊天变成会干活的。️ 一图看懂仓库里的三类智能体示例模块定位核心看点CangjieMagicMCPServer/工具集MCP Servertool注解的完整形态参数描述、示例、安全边界、自动修复MagicAgent/端侧智能体 App任务规划工具 react执行器 MCP 混合接入CangjieRAGCodeAssistant/本地 RAG 助手agent声明式绑定检索源代码问答助手其中工具示例覆盖了 5 种典型场景fetcher网页抓取语义检索、filesystem文件操作摘要、pyexec代码执行自动修复、imageGen文生图、time时间查询完整源码见 CangjieMagicMCPServer/README.md。 tool 注解深度解析Agent 调用工具前的说明书大模型本身不能执行代码它只能决定调用哪个工具、传什么参数。tool注解的作用就是把一个普通函数翻译成模型能读懂的说明书。1. 最小用法零参数工具最简单的工具只需要一句功能描述见 time/src/main.cjtool[ description 获取当前时间 ] public func getCurrentTime(): String { ... }配合一行StdioMCPServer.startWith(getCurrentTime)这个函数就成了标准 MCP 协议下的可调用工具。描述写得越准确模型选工具、传参数就越准——这是工具设计的第一原则。2. 进阶用法参数描述 调用示例给有参数的工具用parameters字段逐项说明语义见 pyexec/src/main.cjtool[ description: ...环境每次执行都会重置必须发送完整脚本..., parameters: { code: The python code to execute... }, examples: [ codeInterpreter(\print(12)\) ] ] public func codeInterpreter(code: String): String { ... }这里有三个细节值得学习描述中写明坑告诉模型环境每次重置、代码不要包在 markdown 代码块里能显著减少无效调用参数说明精确到格式连字符串字面量的引号写法都做了约束examples提供调用范例等价于给模型做 few-shot降低幻觉参数概率。fetcher工具则展示了参数即检索意图的设计——target参数描述用户期望从网页获取什么内容工具内部直接用它做语义检索见 fetcher/src/main.cj。3. 工具族模式安全边界 复合能力filesystem模块filesystem/src/main.cj是一个完整的工具族设计范本安全沙箱所有工具入口先走checkPath校验只允许访问启动时声明的--allowed-dir路径越界直接返回错误信息能力分层listDir、readFile、searchFile三个原子工具 一个高阶工具summarizeFile工具内嵌子智能体summarizeFile内部用一个agent声明的SummaryAgent生成摘要——工具不只是执行还可以是一个小型智能体。 设计启示一个高质量工具 清晰的 description 明确的参数约束 可靠的错误返回。错误信息会直接喂给模型让它有机会自我纠正。 智能体任务规划让 Agent 自己想步骤工具解决能做什么任务规划解决怎么做。仓库中pyexec和MagicAgent展示了两种典型规划模式。1. 代码自修复把试错-修复规划进工具内部codeInterpreter工具在内部实现了一个最多 3 轮的规划循环执行 Python → 失败则把错误信息交给程序修复模型 → 重试。修复模型的系统提示词里还内置了THOUGHT PROTOCOL先理解、再分析根因、最后探索修复方案见 pyexec/src/main.cj。这种工具内部自带 ReAct 循环的模式让上层 Agent 无需关心修复细节一次调用就拿到可用结果。2. 端侧任务规划规划工具 react 执行器MagicAgent的 entry/src/main/cangjie/src/pages/llm.cj 是整仓最精彩的部分核心技巧把流程本身做成一个工具。ticketPlan工具不执行任何操作只是返回一份购票步骤清单定位出发地 → 推断目的地 → 确认日期 → 查票 → 确认车次 → 确认座位 → 天气提醒tool[description: 购买车票流程规划预订/购买车票相关的优先调用该工具] public func ticketPlan(): String { return 具体分为以下步骤...; }prompt中再约定涉及购票时先调用ticketPlan进行规划模型就会先取计划、再按步骤执行。这就是规划与执行分离agent[model: ${MODEL}, executor: react, mcp: [ http(https://mcp.amap.com/sse?key${AMAP_MCP_KEY}), tools(ticketPlan, starbucksBooking, getCurLocation, queryContacts, ...) ] ] class Superman { prompt(...) ... }react执行器让 Agent 自主思考 → 调用工具 → 观察结果 → 再思考mcp混合接入既挂远程地图 MCP 服务路线规划、天气又挂本地tool函数通讯录、日历、定位askUser也是工具向用户提问被建模为一次工具调用配合BlockingQueue同步等待用户输入实现多轮交互式规划。 RAG 代码助手声明式绑定知识库CangjieRAGCodeAssistant/src/main.cj 展示了另一类能力挂载agent注解里直接声明rag检索源Agent 每次对话前自动检索仓颉官方文档语料agent[model: ${MODEL}, executor: naive, rag: {source: retriver()}] class Superman { prompt(...) }配套的prompt用完整示例教模型只引用有用的文档、回答末尾列出参考文档。构建向量库只需cjpm run --name cjca --run-args --build详见 CangjieRAGCodeAssistant/README.md。 快速上手3 步跑通你的第一个 tool 服务装环境安装仓颉 SDK 1.0.5 与 stdx配置CANGJIE_STDX_PATH见 CangjieMagicMCPServer/README.md选最简示例克隆仓库后先跑无外部依赖的time工具cjpm build cjpm run --name time改造为你自己的工具参考filesystem的模式写函数 → 加tool注解描述参数→StdioMCPServer.startWith([...])暴露出去即可接入任意支持 MCP 的 Agent。✅ 小结CangjieMagic-Examples 用可运行的代码回答了智能体开发的核心问题tool注解description 是灵魂parameters 是护栏examples 是范例三者决定工具被调用的质量工具设计模式安全边界沙箱校验、能力分层原子工具复合工具、工具内嵌子智能体摘要/自修复任务规划react执行器负责思考-行动循环规划工具负责给模型一张流程图askUser让规划可以中途向用户校准。掌握这三层你就拥有了从零构建可靠 Agent 应用的方法论——而本仓库就是这套方法论的活教材。【免费下载链接】CangjieMagic-Examples项目地址: https://gitcode.com/Cangjie/CangjieMagic-Examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考