# 基础示例：创建基础对话智能体 #### 场景概述 传统开发Agent的方式，是用户在本地使用LangChain或LangGraph等编写智能体脚本，但当需要将其推向生产环境时，往往会卡在繁琐的工程化步骤上：需要手动编写路由、处理请求、构建Docker镜像，并自行寻找服务器部署。 AgentArts提供了一条从代码到生产的完整链路。 本示例作为高代码开发的入门第一课，将暂时剥离复杂的外部工具，带您体验AgentArts最基础但也最核心的"智能体运行时（Runtime）托管能力"。示例中将编写一个纯粹的带有模型的对话智能体，并展示如何通过AgentArts SDK将本地脚本转化为标准的HTTP Web服务，并托管到云端的AgentArts中。 **适用场景：** - 存量代码迁移：学习如何将已有的LangChain/LangGraph本地资产无缝接入AgentArts平台。 - 熟悉开发链路：跑通"**本地代码开发-\>SDK标准化封装-\>云端托管部署**"的AgentArts高码开发流程。 - 学习调用MaaS模型：学习如何在智能体中调用华为云MaaS服务提供的模型接口。 #### 环境准备 - 操作系统：Linux ARM64，服务器可访问公网。 ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/caution_3.0-zh-cn.png) 需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时时会调用失败。 可以使用华为云ECS服务购买服务器，购买时需要选择鲲鹏架构（ARM64）。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002675304607.png "点击放大") - 安装Python：请确保Python 3.10及以上版本已安装。 大多数Linux发行版（如Ubuntu）都预装了Python，您可以先通过python3 --version检查。如未安装，可以使用如下命令安装： ``` sudo apt update sudo apt install python3 ``` - 安装Docker：请确保Docker 18.06及以上版本已安装。如未安装，可以使用如下命令安装： ``` # 查询 Docker 版本 docker --version # 安装Docker sudo apt update sudo apt install docker.io ``` 安装完成后，建议立即配置国内镜像加速器。在后续执行agentarts launch构建镜像时，Docker需要拉取python:3.10-slim基础镜像，默认从docker.io官方仓库下载，可能超时失败。提前配置加速器可避免此问题。 执行以下命令创建Docker配置目录： ``` sudo mkdir -p /etc/docker ``` 执行以下命令配置国内镜像源（直接复制并回车执行）： ``` sudo tee /etc/docker/daemon.json <<-'EOF' { "registry-mirrors":[ "https://docker.m.daocloud.net", "https://dockerproxy.net", "https://mirror.baidubce.com" ] } EOF ``` 依次执行以下命令重启Docker服务，使配置生效： ``` sudo systemctl daemon-reload sudo systemctl restart docker ``` ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) 华为云SWR基础版不支持OCI镜像格式，如果您使用的是Docker 27及以上版本，并且需要处理OCI镜像，可以通过设置环境变量来关闭OCI支持。 ``` export DOCKER_BUILDKIT=0 # 或者 export BUILDKIT_USE_OCI_MEDIA_TYPES=0 ``` - 执行以下命令安装SDK（建议在Python虚拟环境中安装，以避免与系统包产生冲突）。 ``` # 安装依赖包 apt install python3.12-venv # 创建并激活虚拟环境 (linux) python3 -m venv venv source venv/bin/activate # 安装sdk pip install agentarts-sdk ``` ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png) - 执行pip install agentarts-sdk命令下载缓慢、超时可以更改为使用如下命令 ``` pip install agentarts-sdk -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com ``` - 如果系统缺少python3-venv包，导致无法创建虚拟环境，请按照命令回显提示安装python3-venv包。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002568294810.png "点击放大") - 执行以下命令配置华为云凭证，获取华为云凭证请参考[认证鉴权](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html)。 ``` export HUAWEICLOUD_SDK_AK="your-access-key" export HUAWEICLOUD_SDK_SK="your-secret-key" ``` #### 核心代码实现 #### 步骤一：编写Agent核心逻辑 使用LangGraph框架编写智能体的核心对话逻辑，并配置模型访问密钥。 1. 执行如下命令安装langchain、langgraph、langchain-openai。 ``` pip install -U langchain langgraph langchain-openai ``` 2. 在本地创建agent.py文件，编辑代码如下。 示例代码中创建了一个对话智能体，并对接华为云MaaS服务提供的模型。 ``` import os from typing import List, Dict, Any, TypedDict, Annotated from dotenv import load_dotenv from langgraph.graph import StateGraph, END from langgraph.graph.message import add_messages from langchain_core.messages import BaseMessage, HumanMessage, SystemMessage from langchain_openai import ChatOpenAI # 从 .env 文件加载环境变量 load_dotenv() # ================================================================================ # 第一部分：状态定义与配置 # ================================================================================ class AgentState(TypedDict): """ Agent 状态类型定义 这是 LangGraph 运行时的核心数据结构。 - messages: 使用 add_messages 确保每次对话的新消息会被安全追加，而不是覆盖。 """ messages: Annotated[List[BaseMessage], add_messages] # ================================================================================ # 第二部分：Agent 主类与工作流构建 # ================================================================================ class BasicAgent: """ 基础对话智能体类 封装了 LLM 的初始化、LangGraph 工作流的构建与执行。 """ def __init__(self): # 强校验：没有 API Key 直接报错阻断，避免产生难以排查的网络错误 api_key = os.getenv("MODEL_API_KEY") if not api_key: raise ValueError("[错误] 未找到 MODEL_API_KEY！请在 .env 文件中进行配置。") # 实例化大模型客户端 (对接华为云MaaS服务提供的模型) self._llm = ChatOpenAI( model=os.getenv("MODEL_NAME", "deepseek-v4-flash"), base_url=os.getenv("MODEL_URL", "https://api.modelarts-maas.com/openai/v1"), api_key=api_key, temperature=0.7, ) self.graph = self._build_graph() self.system_prompt = "你是一个乐于助人的 AI 助手，请简明扼要地回答问题。" def _build_graph(self): """ 创建 Agent 工作流图 使用 LangGraph 的 StateGraph 构建极简工作流： 1. 添加 agent 节点（调用 LLM 生成回复） 2. 设置起点为 agent 节点 3. 设置终点（执行完 agent 节点后直接结束，无工具循环） Returns: 编译后的 LangGraph 图 """ def model_node(state: AgentState) -> AgentState: response = self._llm.invoke(state["messages"]) return {"messages": [response]} workflow = StateGraph(AgentState) workflow.add_node("agent", model_node) workflow.set_entry_point("agent") workflow.add_edge("agent", END) return workflow.compile() def run(self, user_input: str) -> str: """ 执行 Agent 处理用户输入 """ messages = [ SystemMessage(content=self.system_prompt), HumanMessage(content=user_input) ] result = self.graph.invoke({"messages": messages}) return result["messages"][-1].content ``` 3. 创建.env环境变量配置文件。 ``` # 必填：您的华为云 MaaS API 密钥 MODEL_API_KEY=xxxxxxxxxxxxxxxxxxxx # 选填：如果您想使用其他模型，取消下方注释并修改 # MODEL_NAME=deepseek-v4-flash # MODEL_URL=https://api.modelarts-maas.com/openai/v1 ``` 获取模型API Key的方法请参考[获取华为云MaaS服务模型API Key](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_053.html)。 agent.py文件的示例中，使用华为云MaaS服务提供的deepseek-v4-flash模型，如果使用其他模型注意MODEL_NAME的值，需填写为模型接口中model参数的值，可以参考如下方式获取。注意需要选择OpenAI兼容接口。 图1获取OpenAI兼容接口的model值 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002678097559.png "点击放大") #### 步骤二：本地功能验证 在本地直接运行智能体，确认智能体可以正常运行。 1. 创建main.py文件，用于本地运行智能体，并进行测试。 ``` from agent import BasicAgent def main(): print("正在初始化 Agent...") try: agent = BasicAgent() except Exception as e: print(e) return print("=" * 50) response = agent.run("你好，请用一句话做个自我介绍。") print(f"Agent 回复: \n{response}") print("=" * 50) if __name__ == "__main__": main() ``` 2. 将agent.py、.env、main.py上传至服务器中。 如果您使用MobaXterm、Xshell这类客户端软件，可以直接在软件界面上拖拽上传。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002648017838.png) 3. 执行python main.py命令对智能体进行本地测试。 由于在main.py文件中已经设置好了问题"你好，请用一句话做个自我介绍。"，智能体本地运行时会调用大模型进行回复。有正常的回复即表示本地测试成功。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002677937711.png) #### 步骤三：SDK封装与本地接口验证 将智能体封装为符合AgentArts平台规范的HTTP服务，并在本地模拟云端接口调用，确认封装正确后再执行后续的部署上云操作。 1. SDK封装，AgentArts平台通过标准HTTP协议与智能体通信，您需要用AgentArts SDK将Agent逻辑包一层，将其暴露为符合平台规范的/invocations接口，平台才能正确调度和管理您的智能体。 创建app.py文件，并上传至服务器中。该文件会将本地的Agent逻辑封装为符合AgentArts平台规范的Web服务。 ``` import os from typing import Dict, Any from agentarts.sdk import AgentArtsRuntimeApp, RequestContext from agent import BasicAgent # 实例化平台运行时应用 app = AgentArtsRuntimeApp() try: my_agent = BasicAgent() except Exception as e: print(f"Agent 初始化失败: {e}") my_agent = None # ================================================================================ # AgentArts 平台标准化接入 (核心) # ================================================================================ @app.entrypoint async def handler(payload: Dict[str, Any], context: RequestContext = None) -> Dict[str, Any]: """ AgentArts 平台标准 HTTP 暴露入口 Args: payload: 请求载荷，包含用户输入 (如 payload.get("message")) context: 请求上下文，包含 session_id 等平台注入信息 """ if not my_agent: return {"response": "服务未正确初始化，请检查环境变量。", "status": "error"} query = payload.get("message", "") try: response = my_agent.run(query) return {"response": response, "status": "success"} except Exception as e: return {"response": f"执行出错: {str(e)}", "status": "error"} if __name__ == "__main__": # 平台托管时，必须读取 AGENT_RUN_PORT 环境变量以匹配容器端口契约 run_port = int(os.getenv("AGENT_RUN_PORT", 8080)) app.run(port=run_port) ``` 2. 接口验证，在正式推送镜像之前，先在本地模拟云端HTTP调用环境，验证Agent的接口封装是否正确、通信是否正常，可以大幅降低因接口问题导致云端部署后才发现错误的调试成本。 执行python app.py启动http server，执行以下命令调用验证Agent的HTTP接口是否已经被正确封装且能正常通信。 执行python app.py回显效果如下。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002647857952.png "点击放大") 打开一个新的终端窗口（保持原窗口运行），使用curl命令进行测试。测试完成后，可以使用Ctrl + C停止运行的进程。 ``` curl --location --request POST 'http://localhost:8080/invocations' \ --header 'Content-Type: application/json' \ --data-raw '{"message": "你好，请用一句话做个自我介绍。"}' ``` ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002678097569.png "点击放大") #### 步骤四：云端部署 将本地智能体打包为Docker镜像并一键部署至AgentArts云端运行时。 1. 部署智能体运行时。 按上述步骤验证完成后，接下来将智能体打包并托管到AgentArts云端运行时。平台将自动完成镜像构建、推送与部署，您只需准备好依赖清单和配置文件即可。 首先准备依赖文件requirements.txt，内容如下： ``` # ================================================================================ # 指定国内 PyPI 镜像源 # ================================================================================ --index-url https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com # ================================================================================ # AgentArts LangGraph Agent Demo - 依赖清单 # ================================================================================ # # 本项目基于 AgentArts 平台，使用 LangGraph 框架构建 AI Agent # 依赖分为两部分：基础框架依赖 + 平台 SDK 依赖 # # 安装方式: # pip install -r requirements.txt # # ================================================================================ # ================================================================================ # 第一部分：LangGraph & LangChain 核心框架 # ================================================================================ # LangGraph: AI Agent 工作流编排框架 # - 状态图定义与执行 # - Checkpoint 持久化机制 # - 条件边与节点路由 langgraph>=0.2.0 # LangChain: LLM 应用开发工具链 # - 消息类型定义 (HumanMessage, AIMessage, SystemMessage) # - 工具系统 (@tool 装饰器) # - LLM 客户端封装 langchain>=0.3.0 langchain-core>=0.3.0 langchain-community>=0.3.0 # ================================================================================ # 第二部分：LLM Provider 支持 # ================================================================================ # OpenAI 兼容接口 openai>=1.0.0 langchain-openai>=0.1.0 # Anthropic (Claude) 支持 anthropic>=0.18.0 langchain-anthropic>=0.1.0 # ================================================================================ # 第三部分：HTTP & 网络 # ================================================================================ requests>=2.31.0 httpx>=0.27.0 # ================================================================================ # 第四部分：工具与配置 # ================================================================================ # 环境变量管理 python-dotenv>=1.0.0 # 异步支持 aiofiles>=23.0.0 # JSON/YAML 支持 pyyaml>=6.0 # ================================================================================ # 第五部分：AgentArts 平台 SDK（核心依赖） # ================================================================================ agentarts-sdk ``` 2. 执行如下命令配置智能体。 ``` agentarts configure --entrypoint app:app ``` 执行后按照操作指引进行配置。 表1配置参数 | 参数 | 说明 | |:---|:---| | Agent name | 智能体名称。 以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线。 | | Region | 服务部署区域。 cn-southwest-2，仅支持此区域。 | | Dependency file | 依赖文件默认为requirements.txt。 | | SWR Organization | 镜像组织名称（建议自定义的镜像组织名，可以在SWR服务控制台贵阳一region创建）。 | | SWR Repository | - 不填写（推荐）。 SWR Repository项直接回车留空，工具会自动生成仓库名称，部署agentarts launch时自动创建镜像仓库，避免仓库不存在报错。 - 填写自定义仓库名称。 若需要手动指定仓库，请填写SWR中已预先存在的镜像仓库名称，如未创建，此处请留空不填写。 | ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002709434345.png "点击放大") 3. 执行命令部署智能体。 ``` agentarts launch ``` 该命令会自动完成以下步骤： 1. 本地构建Docker镜像。 2. 将Docker镜像推送到华为云SWR镜像仓库。 3. 部署到AgentArts运行时托管环境。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002677937721.png "点击放大") 4. 调用云端Agent进行会话。 ``` agentarts invoke '{"message": "你好，请用一句话做个自我介绍。"}' ``` ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002647857962.png "点击放大") #### 常见问题 - **执行agentarts launch命令时出现AK/SK认证报错** 执行以下命令配置华为云凭证，获取华为云凭证请参考[认证鉴权](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html)。 ``` export HUAWEICLOUD_SDK_AK="your-access-key" export HUAWEICLOUD_SDK_SK="your-secret-key" ``` ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002610450897.png "点击放大") - **执行agentarts launch命令** **出现运行时Runtime名称错误** 智能体的名称需要以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。 请重新执行agentarts configure --entrypoint app:app命令进行配置。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002580903228.png "点击放大") - **执行命令，出现SWR.4040010,error_msg:Repository does not exists,ERROR: Organization 'xxx' not found报错。** 问题现象及原因 SWR服务镜像组织不存在，出现该报错的原因通常是在执行agentarts configure --entrypoint app:app命令时，手动指定了一个SWR镜像组织名称，但是未在SWR控制台创建同名组织导致。 解决方案 登录[SWR服务控制台](https://console.huaweicloud.com/swr/?locale=zh-cn#/dashboard)（贵阳一区域），在"组织管理"中手动创建一个与agentarts configure --entrypoint app:app命令中同名的镜像组织。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002675310509.png "点击放大") - **执行agentarts launch命令** **，在执行requirements.txt步骤中出现Read timed out ... files.pythonhosted.org报错。** 问题现象及原因 Docker镜像在构建过程中，尝试从官方PyPI服务器下载在requirements.txt里写的那些Python包，由于网络环境原因造成超时。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002580902726.png "点击放大") 解决方案 执行以下命令让其在安装依赖时使用华为云官方的Python镜像加速器。 ``` sed -i 's|pip install --no-cache-dir -r requirements.txt|pip install --no-cache-dir -r requirements.txt -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com|g' Dockerfile ``` - **执行agentarts launch命令，出现failed to resolve reference "docker.io/library/python:3.10-slim"类型报错** **。** 问题现象及原因 尝试连接Docker官方镜像仓库（docker.io）下载python:3.10-slim基础环境时，网络连接超时（网络连接被阻断或者限速）。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002620626883.png "点击放大") 解决方案 配置Docker国内镜像加速器 执行以下命令在系统配置目录下创建一个名为docker的文件夹。 ``` sudo mkdir -p /etc/docker ``` 执行以下命令（直接复制下面这段代码并回车执行），更换Docker镜像源，从国内镜像站寻找python:3.10-slim。 ``` sudo tee /etc/docker/daemon.json <<-'EOF' { "registry-mirrors":[ "https://docker.m.daocloud.net", "https://dockerproxy.net", "https://mirror.baidubce.com" ] } EOF ``` 依次执行下面两条命令，重启Docker服务： ``` sudo systemctl daemon-reload sudo systemctl restart docker ``` Docker配置完成后，再次执行agentarts launch命令进行Agent部署。 - **执行agentarts launch命令** **，** **出现Organization 'agentarts-org1' already exists、Failed to create/get organization 'agentarts-org1'报错。** SWR服务镜像名称已被占用，请重新更换名称，即更换.agentarts_config.yaml文件中swr_config配置中organization参数的值、artifact_source参数中的值（在yaml文件中，该值共有2处需要替换）。 可依次执行以下命令进行替换，也可以直接手动执行nano .agentarts_config.yaml命令进入到yaml文件中进行修改。 ``` # 将.agentarts_config.yaml文件中原有的 agentarts-org1 组织名替换为一个不容易重名的名字，比如 org_agent_6731 sed -i 's/organization: agentarts-org1/organization: org_agent_6731/g' .agentarts_config.yaml # 修正 artifact_source 里的 URL 中的组织名，这里以 org_agent_6731 为例 sed -i 's|url: swr.cn-southwest-2.myhuaweicloud.com/agentarts-org1/agent_my-agent:latest|url: swr.cn-southwest-2.myhuaweicloud.com/org_agent_6731/agent_my-agent:latest|g' .agentarts_config.yaml ``` - **执行agentarts launch命令** **，** **出现** **SVCSCTG.SWR.4030017、403 Insufficient permissions报错。** 如果使用IAM账户执行agentarts launch命令产生该报错，表示IAM用户没有SWR服务中创建组织或管理资源的权限。请联系主账号授予SWRFullAccessPolicy权限（在IAM新版控制台中授权，IAM控制台"总览"页面右上角处可切换至新版）。 - **执行agentarts invoke命令与智能体进行会话出现invoke_agent failed、Failed to create sandbox且平台运行时日志出现python: exec format error报错。** 问题现象及原因 当前AgentArts服务部署于贵阳一区域，在创建智能体镜像时需要使用ARM64机器打镜像，使用X86机器打镜像会出现此报错。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002678048947.png "点击放大") 解决方案 请更换为ARM64机器制作智能体镜像。 - **执行agentarts launch命令** **时出现** **ERROR: Repository 'xxx' not found报错。** 问题现象及原因 执行agentarts launch部署智能体，构建Docker镜像成功，但推送SWR镜像仓库阶段报错：ERROR: Repository 'xxx/xxx' not found。 原因在于通过agentarts configure --entrypoint app:app做交互式配置时，SWR Repository输入的镜像仓库名称在SWR中不存在。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002716328033.png "点击放大") 解决方案 使用nano .agentarts_config.yaml命令进入config文件，将organization_auto_create的值修改为true即可。 1. 编辑配置文件 ``` nano .agentarts_config.yaml ``` 2. 在swr_config配置块下，设置repository_auto_create: true，同时填写自定义仓库名称： ``` swr_config: repository: "自定义仓库名" repository_auto_create: true ``` 3. 保存退出，重新执行agentarts launch。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002686488216.png)