更新时间：2026-06-04 GMT+08:00
基础示例：创建基础对话智能体
场景概述
传统开发Agent的方式，是用户在本地使用LangChain或 LangGraph等编写智能体脚本，但当需要将其推向生产环境时，往往会卡在繁琐的工程化步骤上：需要手动编写路由、处理请求、构建Docker镜像，并自行寻找服务器部署。
AgentArts提供了一条从代码到生产的完整链路。
本示例作为高代码开发的入门第一课，将暂时剥离复杂的外部工具，带您体验AgentArts最基础但也最核心的“智能体运行时（Runtime）托管能力”。示例中将编写一个纯粹的带有模型的对话智能体，并展示如何通过AgentArts SDK将本地脚本转化为标准的HTTP Web服务，并托管到云端的AgentArts中。
适用场景：
- 存量代码迁移：学习如何将已有的LangChain/LangGraph本地资产无缝接入AgentArts平台。
- 熟悉开发链路：跑通“本地代码开发->SDK标准化封装->云端托管部署”的AgentArts高码开发流程。
- 学习调用MaaS模型：学习如何在智能体中调用华为云MaaS服务提供的模型接口。
环境准备
- 操作系统：Linux ARM64及X86，服务器可访问公网。
- 安装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
华为云SWR基础版不支持OCI镜像格式，如果您使用的是Docker 27及以上版本，并且需要处理OCI镜像，可以通过设置环境变量来关闭OCI支持。
export DOCKER_BUILDKIT=0 # 或者 export BUILDKIT_USE_OCI_MEDIA_TYPES=0
- 执行以下命令安装SDK（建议在Python虚拟环境中安装，以避免与系统包产生冲突）。
# 创建并激活虚拟环境 (linux) python3 -m venv venv source venv/bin/activate # 安装sdk pip install agentarts-sdk
- 执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。
export HUAWEICLOUD_SDK_AK="your-access-key" export HUAWEICLOUD_SDK_SK="your-secret-key"
核心代码实现
- 执行如下命令安装langchain、langgraph、langchain-openai。
pip install -U langchain langgraph langchain-openai
- 在本地创建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-v3.2"), 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 - 创建.env环境变量配置文件。
# 必填：您的华为云 MaaS API 密钥 MODEL_API_KEY=xxxxxxxxxxxxxxxxxxxx # 选填：如果您想使用其他模型，取消下方注释并修改 # MODEL_NAME=deepseek-v3.2 # MODEL_URL=https://api.modelarts-maas.com/openai/v1
获取模型API Key的方法请参考获取华为云MaaS服务模型API Key。
agent.py文件的示例中，使用华为云MaaS服务提供的deepseek-v3.2模型，如果使用其他模型注意MODEL_NAME的值，需填写为模型接口中model参数的值，可以参考如下方式获取。注意需要选择OpenAI兼容接口。
图1 获取OpenAI兼容接口的model值
- 创建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() - 将agent.py、.env、main.py上传至服务器中。
如果您使用MobaXterm、Xshell这类客户端软件，可以直接在软件界面上拖拽上传。
- 执行python main.py命令对智能体进行本地测试。
由于在main.py文件中已经设置好了问题“你好，请用一句话做个自我介绍。”，智能体本地运行时会调用大模型进行回复。有正常的回复即表示本地测试成功。
- 创建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) - 执行python app.py启动http server，执行以下命令调用。通过该方法，在将代码真正推送到云端之前，在本地模拟云端环境，验证Agent的HTTP接口是否已经被正确封装且能正常通信。
执行python app.py回显效果如下。
打开一个新的终端窗口（保持原窗口运行），使用curl命令进行测试。测试完成后，可以使用Ctrl + C停止运行的进程。curl --location --request POST 'http://localhost:8080/invocations' \ --header 'Content-Type: application/json' \ --data-raw '{"message": "你好，请用一句话做个自我介绍。"}'
- 部署智能体运行时。
按上述步骤完成后，基本代码开发已经完成，接下来准备将本地创建好的智能体部署托管到AgentArts平台。
首先准备依赖文件requirements.txt，内容可参考如下：
# ================================================================================ # 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
- 执行如下命令配置智能体。
agentarts configure --entrypoint app:app
执行后按照操作指引进行配置。
配置智能体名称（以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线）、服务部署区域（使用cn-southwest-2，仅支持此区域）、requirements.txt依赖文件、SWR Organization镜像组织名称（如果使用自定义的镜像组织名，需要在SWR服务控制台贵阳一region创建）
- 执行命令部署智能体。
agentarts launch
该命令会自动完成以下步骤：
- 本地构建Docker镜像。
- 将Docker镜像推送到华为云SWR镜像仓库。
- 部署到AgentArts运行时托管环境。
- 调用云端Agent进行会话。
agentarts invoke '{"message": "你好，请用一句话做个自我介绍。"}'
常见问题
- 执行agentarts launch命令时 出现AK/SK认证报错 执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。
export HUAWEICLOUD_SDK_AK="your-access-key" export HUAWEICLOUD_SDK_SK="your-secret-key"
- 执行agentarts launch命令出现运行时Runtime名称错误
智能体的名称需要以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线，长度为2-48个字符。
请重新执行agentarts configure --entrypoint app:app命令进行配置。
- 执行agentarts launch命令，在执行requirements.txt步骤中出现Read timed out ... files.pythonhosted.org报错。
问题现象及原因
Docker镜像在构建过程中，尝试从官方PyPI服务器下载在requirements.txt里写的那些Python包，由于网络环境原因造成超时。
解决方案
执行以下命令让其在安装依赖时使用华为云官方的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基础环境时，网络连接超时（网络连接被阻断或者限速）。
解决方案
配置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命令，在执行requirements.txt步骤中出现Read timed out ... files.pythonhosted.org报错。
问题现象及原因
Docker镜像在构建过程中，尝试从官方PyPI服务器下载在requirements.txt里写的那些Python包，由于网络环境原因造成超时。
解决方案
执行以下命令让其在安装依赖时使用华为云官方的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命令进行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控制台“总览”页面右上角处可切换至新版）。
