# 如何将已有的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. **部署智能体运行时**
   
   部署智能体运行时，具体请参考[通过控制台部署](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_031.html)。
   部署时必须确保路由配置为**"前缀匹配"**，以便请求能正确转发到镜像内部的自定义接口。
   图1路由配置   
   ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002712354654.png "点击放大")
   
   
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. 镜像中的服务是否已正确启动（可通过健康检查状态确认）。