夜雨聆风本文记录一个开发 AI Agent 的完整过程。
项目基于阿里云百炼平台，使用 Python 调用 Qwen 大模型，实现一个具备：
用户意图识别 工具自动调用 任务处理 自我约束 能力的智能学习助手。
一、什么是 AI Agent？
近年来，大语言模型（LLM）快速发展，例如 GPT、Qwen、Claude 等模型已经具备非常强大的文本理解和生成能力。
但是，一个普通的大模型聊天机器人仍然存在明显限制：
只能根据已有知识回答； 无法主动执行任务； 无法调用外部工具； 缺少任务规划能力。
例如：
帮我计算 123 × 456普通 ChatBot：
直接生成答案而 AI Agent：
用户输入↓理解用户意图↓判断是否需要工具↓调用计算器↓返回结果
因此：
AI Agent = 大模型 + 规划能力 + 工具调用 + 状态管理
它让 LLM 从“回答问题”升级为“完成任务”。
二、开发环境准备
2.1 开通阿里云百炼
首先登录阿里云账号，访问百炼控制台：https://bailian.console.aliyun.com
2.2 创建 API Key（调用凭证）
右上角头像下拉，进入「API-KEY 管理」 点击创建 API Key，归属选择默认业务空间，权限勾选全部 生成密钥仅展示一次，建议立即保存。（格式以 sk-开头，丢失无法找回）
安全提醒：API Key 等同于账户余额，禁止明文上传代码、Git 仓库
三、Python 环境搭建
3.1 安装 dashscope 包
pip install dashscope -i https://pypi.tuna.tsinghua.edu.cn/simple3.2 配置 API Key 环境变量（推荐，避免硬编码密钥）
Windows 系统
此电脑→右键属性→高级系统设置→环境变量 系统变量新建： 变量名： DASHSCOPE_API_KEY变量值：你的 sk 开头密钥关闭所有终端、IDE 重启生效
四、实操
4.1项目第一个 Demo
在开发 Agent 之前，我们先实现一个基础 ChatBot：
#第一个对话测试import osfrom dashscope import Generationimport dashscopedashscope.base_http_api_url = 'https://ws-vkgohet4fph1199m.cn-beijing.maas.aliyuncs.com/api/v1'messages = [{'role': 'system', 'content': 'You are Professor Snape from Harry Potter.'},]def Chat():user_input = input("User：")messages.append({"role": "user", "content": user_input})response = Generation.call(api_key=os.getenv("DASHSCOPE_API_KEY"), # 已配置为环境变量model="qwen-turbo",messages=messages,temperature=0.5,result_format="message")if response.status_code == 200:print(response.output.choices[0].message.content)else:print(f"HTTP返回码：{response.status_code}")print(f"错误码：{response.code}")print(f"错误信息：{response.message}")print("请参考文档：https://help.aliyun.com/model-studio/developer-reference/error-code")try:while True:Chat()except KeyboardInterrupt:print("\n\n对话结束，已退出。")
运行：
其中 Generation.call() 负责向大模型发送请求。
此 Demo1 中使用了：
messages 保存上下文； result_format="message" 返回消息格式。
4.1.1 messages 对话结构解析
大模型通常通过 messages 保存上下文。
messages=[{"role":"system","content":"你是一个助手"},{"role":"user","content":"你好"}]
其中：
system——定义模型身份
你是一个Python专家user——用户输入
解释一下AI Agentassistant——模型历史回答
AI Agent 是...4.1.2 Generation vs MultiModalConversation 对比
Agent 开发场景
- Generation（纯文本）
：接口简洁，入参只有文本，工具调用、prompt、历史消息结构非常轻量。做纯文本 Agent，代码简单、调试方便、返回格式稳定。 - MultiModalConversation（多模态）
： 它为了兼容图片，消息体结构变得复杂，每条消息要区分 text/image模块。 如果你只是做纯文本 Agent，也要套多模态的复杂结构体，代码冗余；它不是不能做 Agent，纯文本场景不如 Generation 顺手； 如果要做带图片的 Agent，那 MultiModalConversation 才是首选。
RAG 检索增强场景
RAG 绝大多数业务：把检索出来的文本片段塞进大模型，纯文本问答。
- Generation
专为文本设计，上下文、参考文档直接字符串传入，token 开销可控，输出稳定性好，RAG 场景体验拉满 。 - MultiModalConversation
多模态消息包装带来额外的结构体开销； 很多版本下对超长纯文本上下文优化不如 Generation； RAG 基本用不到图片能力，却要承担多模态接口的额外负担；
4.2 构建真正的 AI Agent
前面的内容实现了一个基础 ChatBot：
用户输入↓Generation↓模型回答
虽然可以进行自然语言交流，但是它仍然缺少 Agent 最核心的能力：
判断任务类型； 调用外部能力； 根据任务选择执行路径。
因此，我们需要进一步升级。
本次示例最终目标：
用户输入|↓意图识别模块|--------------------| |非学习问题 学习问题| |拒绝处理 Agent决策|----------------------| | |calculator translator summarizer|↓生成最终答案
代码示例：
#可调用工具的智能体import osfrom dashscope import Generationimport dashscopefrom AgentTools import AgentToolsimport redashscope.base_http_api_url = 'https://ws-vkgohet4fph1199m.cn-beijing.maas.aliyuncs.com/api/v1'#定义一个智能体的角色和能力SYSTEM_PROMPT = """你是一个具备自主思考、工具调用、自我校验能力的高阶学习助手,名叫Joseph。你不再是简单聊天机器人，你拥有严格的Agent工作流程。【你的工作流程必须严格遵守】1. 用户提问后，首先判断用户意图：学习任务 / 非学习闲聊2. 如果是非学习内容：统一礼貌拒绝，不解释、不回应闲聊内容3. 如果是学习内容：先思考拆解步骤，再判断是否需要调用工具4. 完成回答后，必须自我校验：是否偏离主题、是否有误答、是否越界5. 输出干净、结构化、准确的答案【可使用的内置工具】- calculator: 数学计算- translator: 中英互译- summarizer: 文本总结【禁止行为】不闲聊、不解答娱乐、生活、情感、游戏、八卦内容，严格语义识别，不依赖关键词。"""messages = [{'role': 'system', 'content': SYSTEM_PROMPT},]def semantic_intent_check(user_text):"""True = 违规闲聊False = 合法学习问题增加完整异常捕获，解决choices空、接口异常报错"""check_prompt = f"""请判断用户这句话是否属于【学习、课程、编程、学科、考试、知识】相关问题。仅输出：合法 或 违规用户内容：{user_text}"""try:messages.append({'role': 'user', 'content': check_prompt})res = Generation.call(api_key=os.getenv("DASHSCOPE_API_KEY"),model="qwen-turbo",messages=messages,temperature=0.1)# 校验接口是否请求成功if res.status_code != 200:print("res.status_code:{res.status_code}")return False# 校验返回内容是否为空# if not res.output or not res.output.choices or len(res.output.choices) == 0:# print('11111',res.output.text)# return Falseans = res.output.text.strip()# print(ans)return "违规" in ansexcept Exception as e:# 接口异常默认放行正常学习对话，不阻断程序print(e)return Falsedef tool_auto_dispatch(user_text):# 工具实例tools = AgentTools()# 数学计算匹配if re.search(r"[\d\+\-\*\/\(\)]{3,}", user_text):return tools.calculator(user_text)# 翻译匹配if "翻译" in user_text or len(re.findall(r"[a-zA-Z]{3,}",user_text)) > 10:return tools.translator(user_text)# 总结匹配if len(user_text) > 150 and ("总结" in user_text or "概括" in user_text):return tools.summarizer(user_text)# 无需工具return Nonedef Chat():user_input = input("用户：")if semantic_intent_check(user_input):print('Sorry啊宝宝，Joseph不能回答与学习无关的问题~')else:answer = tool_auto_dispatch(user_input)if answer is not None:print('约瑟夫:'+answer)else:res = Generation.call(api_key=os.getenv("DASHSCOPE_API_KEY"),model="qwen-turbo",messages=[{"role": "user", "content": user_input}],temperature=0.1)if res.status_code == 200:content = res.output.textprint(f'约瑟夫:{content}')else:print("调用模型失败")try:while True:Chat()except KeyboardInterrupt:print("\n\n答疑结束，欢迎下次再来！")
AI Agent 的第一步不是写代码，而是定义它的角色。
而示例代码定义了 Agent 的身份（源于项目中的 SYSTEM_PROMPT 设计）：
Joseph 不再是普通聊天机器人，而是一个具有工作流程约束的智能助手。
而一个 Agent 是否强大，关键取决于它拥有多少工具。
即Agent 最重要的能力：
根据用户需求选择工具。
本项目设计有三个基础工具，存于AgentTools.py（本文不做此部分代码展示）：
五、小结
最重要的理解：
AI Agent 并不是简单调用大模型，而是在大模型基础上增加“规划、执行、工具调用”的能力。
从 ChatBot 到 Agent：
不是模型变强了，而是系统架构升级了。
后续可以继续扩展：
RAG知识库 Agent 多模态 Agent 自动代码 Agent 多智能体系统
这也是未来 AI 应用开发的重要方向。