基础示例：创建基础对话智能体

场景概述

传统开发Agent的方式，是用户在本地使用LangChain或LangGraph等编写智能体脚本，但当需要将其推向生产环境时，往往会卡在繁琐的工程化步骤上：需要手动编写路由、处理请求、构建Docker镜像，并自行寻找服务器部署。

AgentArts提供了一条从代码到生产的完整链路。

本示例作为高代码开发的入门第一课，将暂时剥离复杂的外部工具，带您体验AgentArts最基础但也最核心的“智能体运行时（Runtime）托管能力”。示例中将编写一个纯粹的带有模型的对话智能体，并展示如何通过AgentArts SDK将本地脚本转化为标准的HTTP Web服务，并托管到云端的AgentArts中。

适用场景：

存量代码迁移：学习如何将已有的LangChain/LangGraph本地资产无缝接入AgentArts平台。
熟悉开发链路：跑通“本地代码开发->SDK标准化封装->云端托管部署”的AgentArts高码开发流程。
学习调用MaaS模型：学习如何在智能体中调用华为云MaaS服务提供的模型接口。

环境准备

操作系统：Linux ARM64，服务器可访问公网。

需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时时会调用失败。

可以使用华为云ECS服务购买服务器，购买时需要选择鲲鹏架构（ARM64）。
安装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
```
华为云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
```
- 执行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包。

执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。

export HUAWEICLOUD_SDK_AK="your-access-key"
export HUAWEICLOUD_SDK_SK="your-secret-key"

核心代码实现

步骤一：编写Agent核心逻辑

使用LangGraph框架编写智能体的核心对话逻辑，并配置模型访问密钥。

执行如下命令安装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文件中已经设置好了问题“你好，请用一句话做个自我介绍。”，智能体本地运行时会调用大模型进行回复。有正常的回复即表示本地测试成功。

步骤三：SDK封装与本地接口验证

将智能体封装为符合AgentArts平台规范的HTTP服务，并在本地模拟云端接口调用，确认封装正确后再执行后续的部署上云操作。

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)

接口验证，在正式推送镜像之前，先在本地模拟云端HTTP调用环境，验证Agent的接口封装是否正确、通信是否正常，可以大幅降低因接口问题导致云端部署后才发现错误的调试成本。

执行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": "你好，请用一句话做个自我介绍。"}'
```

步骤四：云端部署

将本地智能体打包为Docker镜像并一键部署至AgentArts云端运行时。

部署智能体运行时。

按上述步骤验证完成后，接下来将智能体打包并托管到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

执行如下命令配置智能体。
```
agentarts configure --entrypoint app:app
```
执行后按照操作指引进行配置。

配置智能体名称（以小写字母开头，以小写字母或数字结尾，可以包含小写字母、数字和中划线）、服务部署区域（使用cn-southwest-2，仅支持此区域）、requirements.txt依赖文件、SWR Organization镜像组织名称（如果使用自定义的镜像组织名，需要在SWR服务控制台贵阳一region创建）
执行命令部署智能体。
```
agentarts launch
```
该命令会自动完成以下步骤：
1. 本地构建Docker镜像。
2. 将Docker镜像推送到华为云SWR镜像仓库。
3. 部署到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命令进行配置。
执行命令，出现SWR.4040010,error_msg:Repository does not exists,ERROR: Organization 'xxx' not found报错。
问题现象及原因

SWR服务镜像组织不存在，出现该报错的原因通常是在执行agentarts configure --entrypoint app:app命令时，手动指定了一个SWR镜像组织名称，但是未在SWR控制台创建同名组织导致。

解决方案

登录SWR服务控制台（贵阳一区域），在“组织管理”中手动创建一个与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控制台“总览”页面右上角处可切换至新版）。
执行agentarts invoke与智能体进行会话出现invoke_agent failed、Failed to create sandbox且平台运行时日志出现python: exec format error报错。
问题现象及原因

当前AgentArts服务部署于贵阳一区域，在创建智能体镜像时需要使用ARM64机器打镜像，使用X86机器打镜像会出现此报错。

解决方案

请更换为ARM64机器制作智能体镜像。