Python API调用：将Open-AutoGLM集成到项目中

Python API调用：将Open-AutoGLM集成到项目中

摘要：本文聚焦于工程落地，手把手教你如何在Python项目中调用Open-AutoGLM的API接口，将手机AI助理能力无缝嵌入自有系统。不讲原理、不堆概念，只提供可直接复用的代码、清晰的调用逻辑和真实场景下的集成建议。

1. 为什么需要API集成？——从命令行到工程化

1.1 命令行只是起点，不是终点

当你第一次运行python main.py "打开微信发消息"，看到手机自动执行操作时，那种“它真的懂我”的兴奋感很强烈。但很快你会发现：

• 每次都要手动敲命令，无法嵌入业务流程；
• 无法与现有Web服务、后台任务或自动化脚本联动；
• 不能按需控制执行节奏、捕获中间状态、处理异常分支；
• 更没法把它变成你App里的一个功能按钮。

换句话说：命令行是玩具，API才是工具。

1.2 API集成能为你带来什么？

API不是锦上添花，而是把Open-AutoGLM从“演示项目”升级为“可交付能力模块”的关键一步。

2. API调用全景图：三层结构与职责划分

2.1 整体架构：客户端 → 控制层 → 设备层

┌─────────────────────────────────────────────────────────────┐ │ 你的Python项目（主程序） │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ phone_agent.* 模块封装 │ │ │ │ • ADBConnection：设备连接管理 │ │ │ │ • PhoneAgent：核心代理控制器 │ │ │ │ • ModelConfig / AgentConfig：配置抽象 │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Open-AutoGLM SDK（已安装） │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ adb/ → 封装ADB命令，屏蔽平台差异 │ │ │ │ model/ → 统一模型加载与推理接口 │ │ │ │ agent/ → 实现Perception-Thinking-Action循环 │ │ │ │ utils/ → 日志、重试、超时等工程化支持 │ │ │ └─────────────────────────────────────────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ 安卓设备（真机或模拟器） │ │ • 通过USB/WiFi连接 │ │ • 截图、UI树解析、ADB指令执行均由SDK自动完成 │ └─────────────────────────────────────────────────────────────┘

关键认知：你不需要自己写adb shell screencap或解析XML，SDK已全部封装；你只需关注“我要做什么”和“拿到结果后怎么做”。

3. 快速上手：5分钟完成首次API调用

3.1 环境确认（跳过重复步骤）

确保已完成以下准备（如未完成，请先回看镜像文档）：

• Python 3.10+ 环境已就绪；
• ADB 工具已安装并加入PATH；
• 安卓手机已开启开发者模式、USB调试、ADB Keyboard；
• Open-AutoGLM仓库已克隆，依赖已安装（pip install -e .）；
• 设备已通过adb devices正常识别。

3.2 最简可用代码（无任何配置，直奔结果）

# example_simple.py from phone_agent import PhoneAgent from phone_agent.model import ModelConfig from phone_agent.agent import AgentConfig # 1. 配置本地模型路径（使用你已下载的模型） model_config = ModelConfig( model_name="./models/AutoGLM-Phone-9B", # 替换为你的实际路径 is_local=True, ) # 2. 配置代理行为（默认即可） agent_config = AgentConfig( max_steps=30, # 最多执行30步，防死循环 verbose=False, # 关闭详细日志，生产环境推荐 ) # 3. 创建代理实例（自动连接默认设备） agent = PhoneAgent( model_config=model_config, agent_config=agent_config, ) # 4. 执行任务（同步阻塞调用） result = agent.run("打开小红书搜索'咖啡拉花教程'") print(" 任务完成！") print(f"最终状态: {result.status}") # success / failed / interrupted print(f"执行步数: {result.step_count}") print(f"耗时: {result.total_time:.1f}秒") if result.screenshot_path: print(f"最后截图: {result.screenshot_path}")

运行效果：手机自动亮屏→解锁→打开小红书→点击搜索框→输入文字→点击搜索。全程无需人工干预，代码返回结构化结果。

3.3 关键返回字段说明（result对象）

4. 生产级集成：连接管理、异常处理与状态控制

4.1 精确控制设备连接（避免“默认设备”陷阱）

命令行中--device-id参数在API中由AgentConfig.device_id控制。强烈建议显式指定设备ID，尤其当多台设备连接时：

from phone_agent.adb import list_devices # 列出所有已连接设备 devices = list_devices() print("当前连接设备：") for i, dev in enumerate(devices): print(f"{i+1}. {dev.device_id} ({dev.connection_type.value})") # 选择第一台设备（或根据条件筛选） selected_device = devices[0].device_id # 在AgentConfig中指定 agent_config = AgentConfig( device_id=selected_device, # 显式绑定 max_steps=50, )

4.2 处理常见失败场景（健壮性保障）

Open-AutoGLM在真实环境中可能遇到：设备断连、截图失败、模型无响应、敏感操作拦截。API提供统一异常处理入口：

from phone_agent.exceptions import ( DeviceConnectionError, ModelTimeoutError, OperationFailedError, TakeoverRequiredError, ) try: result = agent.run("打开微信发送测试消息") if result.status == "success": print(" 任务成功完成") elif result.status == "interrupted": print(" 需要人工接管（如验证码、支付确认）") # 可在此触发通知、暂停流程、等待人工输入 else: print(f"❌ 任务失败: {result.error_message}") except DeviceConnectionError as e: print(f"🔌 设备连接异常: {e}") # 尝试重连 agent.reconnect() except ModelTimeoutError as e: print(f"⏳ 模型响应超时: {e}") # 可降级为简单操作，或重试 result = agent.run("打开微信", timeout=120) # 延长超时 except TakeoverRequiredError as e: print(f"✋ 检测到敏感操作: {e.message}") # 调用自定义接管函数（见5.2节） handle_takeover(e.message)

4.3 状态感知与流程控制（不止于“执行完就结束”）

真实业务中，你往往需要：

• 等待某个UI元素出现（如“登录成功”文字）；
• 根据当前界面动态决定下一步；
• 中断正在执行的任务。

SDK提供底层控制能力：

# 获取当前屏幕状态（不触发新动作） state = agent.get_current_state() print(f"当前APP: {state.app_package}") print(f"当前Activity: {state.activity}") print(f"是否在首页: {state.is_home}") # 等待特定元素出现（例如等待“搜索结果页”加载） wait_result = agent.wait_for_element( text="共找到", timeout=15, interval=2 # 每2秒检查一次 ) if wait_result: print(" 搜索结果已加载") else: print("❌ 等待超时，尝试重新搜索") # 主动中断任务（如用户点击“取消”按钮） agent.interrupt()

5. 高级集成技巧：回调、批量、自定义与远程部署

5.1 敏感操作回调：让AI懂得“分寸”

当AI检测到支付、账号登录、权限申请等敏感操作时，会主动暂停并触发回调。这是保障安全的核心机制：

def on_sensitive_operation(message: str) -> bool: """ 敏感操作确认回调 :param message: AI识别出的操作描述，如"即将进行微信支付" :return: True允许继续，False中止 """ print(f"\n 安全提示: {message}") print(" [1] 允许执行 [2] 中止任务 [3] 人工接管") choice = input("请选择 (1/2/3): ").strip() if choice == "1": return True elif choice == "2": return False else: # choice == "3" print("➡ 已切换至人工模式...") # 可在此启动远程控制界面或发送通知 notify_human_operator(message) return True # 允许AI继续，但后续步骤需人工确认 def on_human_takeover(message: str) -> None: """人工接管回调：当AI无法自动处理时触发""" print(f"\n 需要人工介入: {message}") input("请完成操作后，按回车键继续...") # 创建Agent时注册回调 agent = PhoneAgent( model_config=model_config, agent_config=agent_config, confirmation_callback=on_sensitive_operation, takeover_callback=on_human_takeover, )

5.2 批量任务执行：提升运营效率

电商、测试、内容审核等场景常需批量操作。利用PhoneAgent的reset()方法可复用实例：

tasks = [ "打开淘宝搜索'无线耳机'并截图第1个商品", "打开京东搜索'机械键盘'并截图价格区域", "打开拼多多搜索'防晒霜'并截图销量排序", ] results = [] for i, task in enumerate(tasks, 1): print(f"\n 执行任务 {i}/{len(tasks)}: {task}") try: result = agent.run(task, timeout=60) results.append({ "task": task, "status": result.status, "screenshot": result.screenshot_path, "time": result.total_time, }) print(f" 完成，耗时{result.total_time:.1f}s") except Exception as e: print(f" ❌ 失败: {e}") results.append({"task": task, "status": "error", "error": str(e)}) # 重置Agent状态，为下一次任务准备 agent.reset() # 导出结果报告 import json with open("batch_report.json", "w", encoding="utf-8") as f: json.dump(results, f, ensure_ascii=False, indent=2) print("\n 批量任务报告已保存至 batch_report.json")

5.3 自定义模型服务端（云部署场景）

当你的服务部署在服务器上，而手机在用户本地时，需将--base-url指向远程模型服务。此时API调用方式不变，仅需修改配置：

# 远程模型服务（如vLLM部署在云服务器） model_config = ModelConfig( model_name="autoglm-phone-9b", # 模型名（服务端注册名） is_local=False, # 关键：设为False base_url="http://your-server-ip:8000/v1", # vLLM服务地址 api_key="sk-xxx", # 如需认证 ) # 设备仍通过本地ADB连接（手机需与服务器网络互通） agent_config = AgentConfig( device_id="192.168.1.100:5555", # WiFi连接的手机IP ) agent = PhoneAgent(model_config=model_config, agent_config=agent_config) result = agent.run("打开抖音刷3个视频") # 推理在云端，操作在本地

注意：此模式下，手机必须能被服务器访问（WiFi同网段或端口映射），且ADB需开启adb tcpip 5555。

6. 实战案例：构建一个“App健康度巡检”脚本

6.1 需求分析

某公司需每日检查旗下5款App在主流机型上的基础功能：

• 是否能正常启动；
• 首页是否加载成功（检测“首页”、“推荐”等文字）；
• 关键按钮是否可点击（如“我的”、“购物车”）；
• 截图存档供UI对比。

6.2 完整可运行代码

# app_health_check.py import os import time from datetime import datetime from phone_agent import PhoneAgent from phone_agent.model import ModelConfig from phone_agent.agent import AgentConfig from phone_agent.exceptions import * # ===== 配置区 ===== APPS_TO_CHECK = { "com.xiaohongshu.main": "小红书", "com.ss.android.ugc.aweme": "抖音", "com.taobao.taobao": "淘宝", "com.jd.mobile": "京东", "com.pinduoduo": "拼多多", } CHECK_STEPS = [ ("启动App", lambda pkg: f"打开{pkg}"), ("检查首页", lambda pkg: f"查看{pkg}首页是否显示'推荐'或'首页'文字"), ("点击我的", lambda pkg: f"点击{pkg}底部'我的'按钮"), ] REPORT_DIR = "./health_reports" os.makedirs(REPORT_DIR, exist_ok=True) # ===== 初始化Agent ===== model_config = ModelConfig( model_name="./models/AutoGLM-Phone-9B", is_local=True, ) agent_config = AgentConfig( max_steps=20, verbose=False, ) agent = PhoneAgent(model_config=model_config, agent_config=agent_config) # ===== 执行巡检 ===== report = { "timestamp": datetime.now().isoformat(), "results": {} } print(" 开始App健康度巡检...\n") for pkg, name in APPS_TO_CHECK.items(): print(f" 检查 {name} ({pkg})") app_report = {"steps": []} for step_name, cmd_func in CHECK_STEPS: cmd = cmd_func(name) print(f" ├─ {step_name}: {cmd}") try: start_time = time.time() result = agent.run(cmd, timeout=45) duration = time.time() - start_time step_result = { "step": step_name, "command": cmd, "status": result.status, "duration": round(duration, 1), "screenshot": None, } if result.screenshot_path and os.path.exists(result.screenshot_path): # 重命名截图便于归档 new_screenshot = os.path.join( REPORT_DIR, f"{name}_{step_name.replace(' ', '_')}_{int(time.time())}.png" ) os.rename(result.screenshot_path, new_screenshot) step_result["screenshot"] = os.path.basename(new_screenshot) app_report["steps"].append(step_result) print(f" │ {result.status} ({duration:.1f}s)") except Exception as e: app_report["steps"].append({ "step": step_name, "command": cmd, "status": "error", "error": str(e), "duration": 0, }) print(f" │ ❌ {e}") report["results"][pkg] = app_report print(f" └─ {name} 检查完成\n") agent.reset() # 清空状态，准备下一个App # ===== 生成报告 ===== report_file = os.path.join(REPORT_DIR, f"health_{datetime.now():%Y%m%d_%H%M%S}.json") with open(report_file, "w", encoding="utf-8") as f: import json json.dump(report, f, ensure_ascii=False, indent=2) print(f" 巡检完成！报告已保存至 {report_file}") print(" 提示：可将此脚本加入crontab每日自动执行")

运行后，你会得到结构化JSON报告，包含每个App每步操作的状态、耗时、截图路径，可直接用于CI/CD或人工复核。

7. 性能与稳定性建议：让API在生产环境可靠运行

7.1 连接稳定性加固

• ADB保活：在长时间任务前，执行adb connect和adb devices验证连接；
• 自动重连：捕获DeviceConnectionError后，调用agent.reconnect()；
• WiFi优选：若使用WiFi连接，建议在路由器中为手机分配静态IP，避免IP变动导致断连。

7.2 内存与速度优化（针对Mac本地部署）

7.3 日志与监控（生产必备）

import logging from phone_agent.utils.logger import setup_logger # 全局日志配置 setup_logger( level=logging.INFO, log_file="./logs/agent_api.log", max_size=10*1024*1024, # 10MB backup_count=5, ) # 在Agent中启用详细日志（调试期） agent_config = AgentConfig(verbose=True)

日志将记录：设备连接、截图获取、模型输入输出、ADB命令、异常堆栈，便于问题定位。

8. 总结：API集成不是终点，而是能力延伸的起点

8.1 你已掌握的核心能力

• 零配置快速调用：5行代码启动一个手机AI代理；
• 生产级错误处理：覆盖设备、网络、模型、UI全部异常链路；
• 状态感知与控制：不再黑盒执行，可等待、中断、查询当前状态；
• 安全边界设计：通过回调机制，让AI在支付、登录等场景主动“请示”；
• 批量与定制化：从单任务到百任务，从本地到云端，灵活适配业务形态。

8.2 下一步行动建议

• 立即尝试：复制example_simple.py，替换你的模型路径，运行第一条指令；
• 接入业务：选一个低风险场景（如内部App巡检），用本文代码替换原有手工流程；
• 封装为服务：用FastAPI包装PhoneAgent，提供HTTP接口，供前端或其它系统调用；
• 贡献社区：遇到未覆盖的场景？欢迎向Open-AutoGLM提交Issue或PR。

技术的价值不在炫技，而在解决真实问题。当你第一次看到自己的系统调用Open-AutoGLM，自动完成一个曾需人工点击10次的操作时，你就已经站在了AI Agent工程化的正确起点上。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。