如何将已有的Agent应用迁移至AgentArts运行时

背景

如果您已有一个完整的Agent应用，希望将其运行在AgentArts平台上，但不希望基于AgentArts SDK进行重新开发。AgentArts支持轻量迁移模式：只需对原有应用进行少量微调，即可部署到 AgentArts 运行时。

迁移步骤

1. 添加健康检查接口

   AgentArts底座沙箱会通过健康探查接口检测您的Agent是否就绪。您需要在原有应用中新增一个GET /ping接口。

   项目	说明
   请求方法	GET
   路径	/ping
   响应状态码	200
   响应体格式	JSON
   触发时机	镜像启动完成后，沙箱会周期性调用此接口

   响应体格式

   {
     "status": "Initing | Healthy | HealthyBusy"
   }

   状态值	含义	说明
   Initing	初始化中	应用正在启动，依赖服务或模型加载中
   Healthy	进程健康且空闲	应用已就绪，可接受请求
   HealthyBusy	进程健康且非空闲	应用运行中但正忙于处理其他请求

   镜像启动完成后，进程处于健康状态时，接口必须返回200状态码且status字段为 Healthy，沙箱才会认为实例就绪。

   代码示例

   Python (Flask)

   from flask import Flask, jsonify
   
   app = Flask(__name__)
   
   # 新增健康检查接口
   @app.route('/ping', methods=['GET'])
   def ping():
       return jsonify({"status": "Healthy"}), 200
   
   # 保留您原有的业务接口
   @app.route('/chat', methods=['POST'])
   def chat():
       # 您原有的业务逻辑
       ...
   
   if __name__ == '__main__':
       app.run(host='0.0.0.0', port=8080)

   Python (FastAPI)

   from fastapi import FastAPI
   
   app = FastAPI()
   
   # 新增健康检查接口
   @app.get("/ping")
   async def ping():
       return {"status": "Healthy"}
   
   # 保留您原有的业务接口
   @app.post("/chat")
   async def chat():
       # 您原有的业务逻辑
       ...

   Node.js (Express)

   const express = require('express');
   const app = express();
   
   // 新增健康检查接口
   app.get('/ping', (req, res) => {
       res.status(200).json({ status: 'Healthy' });
   });
   
   // 保留您原有的业务接口
   app.post('/chat', (req, res) => {
       // 您原有的业务逻辑
   });
   
   app.listen(8080, '0.0.0.0');

   Java (Spring Boot)

   @RestController
   public class AgentController {
   
       // 新增健康检查接口
       @GetMapping("/ping")
       public ResponseEntity<Map<String, String>> ping() {
           return ResponseEntity.ok(Collections.singletonMap("status", "Healthy"));
       }
   
       // 保留您原有的业务接口
       @PostMapping("/chat")
       public ResponseEntity<?> chat(@RequestBody Map<String, Object> request) {
           // 您原有的业务逻辑
           ...
       }
   }

   • 健康检查接口应确保在应用完全启动（依赖服务就绪、模型加载完成等）后再返回 Healthy 状态。
   • 如果应用尚未就绪，可返回 {"status": "Initing"}，沙箱会继续重试。

2. 打包镜像并上传至华为云 SWR。
   1. 登录容器镜像服务控制台，选择区域，要和AgentArts区域保持一致，否则无法选择到镜像。
   2. 单击右上角“创建组织”，输入组织名称完成组织创建。请自定义组织名称，本示例使用“demo-886633”，下面的命令中涉及组织名称“demo-886633”也请替换为自定义的值。
   3. 单击右上角“登录指令”，获取登录访问指令，本文选择复制“通用型登录指令”。

      以root用户登录本地环境，输入复制的SWR临时登录指令。

   4. 上传镜像至容器镜像服务镜像仓库。
      1. 使用docker tag命令给上传镜像打标签。

         #region和domain信息请替换为实际值，组织名称demo-886633也请替换为自定义的值。
         sudo docker tag agentarts-custom:latest swr.{region-id}.{domain}/demo-886633/agentarts-custom:latest 
         #此处以华为云cn-southwest-2为例 
         sudo docker tag agentarts-custom:latest swr.cn-southwest-2.myhuaweicloud.com/demo-886633/agentarts-custom:latest

      2. 使用docker push命令上传镜像。

         #region和domain信息请替换为实际值，组织名称demo-886633也请替换为自定义的值。 
         sudo docker push swr.{region-id}.{domain}/demo-886633/agentarts-custom:latest
         #此处以华为云cn-southwest-2为例 
         sudo docker push swr.cn-southwest-2.myhuaweicloud.com/demo-886633/agentarts-custom:latest

   5. 完成镜像上传后，在容器镜像服务控制台的“我的镜像”页面可查看已上传的自定义镜像。

3. 部署智能体运行时

   部署智能体运行时，具体请参考通过控制台部署。

   部署时必须确保路由配置为“前缀匹配”，以便请求能正确转发到镜像内部的自定义接口。

   图1 路由配置
   

4. 调整调用方式，

   部署完成后，原有的接口调用路径需要按照新规则进行调整。

   路径转换规则

   旧路径：POST https://旧的平台域名/<接口路径>
   
   新路径：POST https://<AgentArts运行时访问域名>/runtimes/<运行时名称>/invocations/<接口路径>

   转换示例

   场景	旧调用方式	新调用方式
   对话接口	POST https://旧域名/chat	POST https://<运行时访问域名>/runtimes/<运行时名称>/invocations/chat
   completions接口	POST https://旧域名/v1/completions	POST https://<运行时访问域名>/runtimes/<运行时名称>/invocations/v1/completions
   自定义接口	POST https://旧域名/my/custom/api	POST https://<运行时访问域名>/runtimes/<运行时名称>/invocations/my/custom/api

   完整调用示例

   假设：

   • 运行时访问域名为 https://example.cn-southwest-2.huaweicloud-agentarts.com
   • 运行时名称为 my-agent-runtime
   • 原有接口为 POST /chat

   调整后的调用方式：

   curl -X POST https://example.cn-southwest-2.huaweicloud-agentarts.com/runtimes/my-agent-runtime/invocations/chat \
     -H "Content-Type: application/json" \
     -d '{
       "messages": [
         {"role": "user", "content": "你好"}
       ]
     }'

常见问题

1. 原有的业务接口需要修改吗？

   不需要。原有的业务接口代码无需改动，只需确保路由配置为前缀匹配，AgentArts会将 /runtimes/<运行时名称>/invocations/ 前缀剥离后转发到您的实际接口。

2. 部署后调用返回404？

   请检查：

   1. 部署时路由配置是否为前缀匹配模式。
   2. 调用路径是否已按新规则调整，包含 /runtimes/<运行时名称>/invocations/ 前缀。
   3. 镜像中的服务是否已正确启动（可通过健康检查状态确认）。