UFO 第三方 Agent 配置完全指南扩展 LinuxAgent 与 HardwareAgent 等专用能力【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO本篇技术指南围绕 UFO 项目中 config/ufo/third_party.yaml 配置文件的完整用法展开系统讲解第三方 AgentThird-Party Agent的设计动机、核心配置字段、LinuxAgent / HardwareAgent / MobileAgent 的启用方式以及如何与 UFO³ Galaxy 多设备编排场景对接。读完本文你将掌握如何通过一行配置为 UFO 增加 Linux CLI 执行、物理硬件控制与 Android 移动设备操控等非 GUI 能力并能独立排查常见配置故障。一、为什么需要第三方 Agent定位与适用场景UFO 的核心自动化能力面向 Windows GUI 操作由 HostAgent宿主代理与 AppAgent应用代理协作完成界面级任务。但在真实生产环境中很多任务并不依赖 GUI需要在 Linux 服务器上执行 CLI 命令、查看日志、管理服务需要通过机械臂模拟键盘鼠标输入、插拔 USB 设备等物理操作需要通过 ADB 远程控制 Android 设备。第三方 Agent 正是为这些非 GUI 交互场景而设计的扩展机制。它们与标准 HostAgent、AppAgent 并行工作被注册为 HostAgent 目标列表中的独立目标TargetKind.THIRD_PARTY_AGENT当 HostAgent 判定任务应交给专用能力处理时便会实例化对应的第三方 Agent 完成子任务。定位说明第三方 Agent 配置是高级可选功能。绝大多数用户只需要核心的 HostAgent 与 AppAgent仅在确实需要上述专用能力时才应配置启用。二、配置文件位置与整体结构第三方 Agent 配置文件位于config/ufo/third_party.yaml。系统配置加载入口为 config/config_loader.py 中的load_ufo_config/get_ufo_config配置键会经 config/config_schemas.py 映射为结构化对象例如ENABLED_THIRD_PARTY_AGENTS映射为system.enabled_third_party_agentsTHIRD_PARTY_AGENT_CONFIG映射为system.third_party_agent_config供代码以属性方式安全访问。文件包含两个顶层配置键配置键类型作用ENABLED_THIRD_PARTY_AGENTSList[String]需要启用的第三方 Agent 名称白名单只有出现在此列表中的 Agent 才会被加载THIRD_PARTY_AGENT_CONFIGDict[String, Dict]每个第三方 Agent 的独立配置块以 Agent 名为键仓库默认的 config/ufo/third_party.yaml 中内置了三个 Agent 的完整配置骨架# Enabled Third-Party Agents ENABLED_THIRD_PARTY_AGENTS: [HardwareAgent, LinuxAgent, MobileAgent] THIRD_PARTY_AGENT_CONFIG: HardwareAgent: VISUAL_MODE: True AGENT_NAME: HardwareAgent APPAGENT_PROMPT: ufo/prompts/share/base/app_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/examples/visual/app_agent_example.yaml API_PROMPT: ufo/prompts/third_party/hardware_agent_api.yaml INTRODUCTION: The HardwareAgent is used to manipulate hardware components of the computer without using GUI, such as robotic arms for keyboard input and mouse control, plug and unplug devices such as USB drives, and other hardware-related tasks. LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only. MobileAgent: AGENT_NAME: MobileAgent APPAGENT_PROMPT: ufo/prompts/third_party/mobile_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/mobile_agent_example.yaml INTRODUCTION: For Android Mobile Device Control. Enables remote control and automation of Android devices via ADB and UI interactions.注意仓库默认配置默认启用了全部三个 Agent如果你只使用 Windows GUI 自动化建议按下文快速开始将其收窄或置空。三、快速开始一分钟完成启用/禁用3.1 仅启用 LinuxAgentUFO³ Galaxy 推荐# Enable third-party agents ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent] THIRD_PARTY_AGENT_CONFIG: LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only.3.2 禁用全部第三方 Agent纯 Windows GUI 场景# Disable all third-party agents ENABLED_THIRD_PARTY_AGENTS: []置空列表后HostAgent 在注册目标时见host_agent_processing_strategy.py的_register_third_party_agents方法会打印 No third-party agents configured 并跳过注册系统行为与未启用任何第三方 Agent 完全一致。四、可用第三方 Agent 详解4.1 LinuxAgentLinux CLI 与服务器运维用途执行 Linux 命令行操作与服务器管理任务。在 UFO³ Galaxy 中当编排器将任务路由到 Linux 设备时会通过 LinuxAgent 以 CLI 方式执行命令实现多设备工作流中对 Linux 设备的编排。除 Galaxy 场景外它同样适用于从 Windows 管理 Linux 服务器以及跨平台自动化工作流。启用场景使用 UFO³ Galaxy 编排 Linux 设备需要执行 Linux CLI 命令查看日志、管理进程/服务、操作文件与权限、网络与包管理从 Windows 侧管理 Linux 服务器构建跨平台自动化流程配置块THIRD_PARTY_AGENT_CONFIG: LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only.字段说明字段类型说明AGENT_NAMEStringAgent 标识符必须与 Agent 类名一致此处为 LinuxAgentAPPAGENT_PROMPTString主提示词模板路径APPAGENT_EXAMPLE_PROMPTString示例提示词模板路径INTRODUCTIONString提供给 LLM 的 Agent 描述文本源码印证LinuxAgent 定义于 ufo/agents/agent/customized_agent.py通过AgentRegistry.register(agent_nameLinuxAgent, third_partyTrue, processor_clsLinuxAgentProcessor)注册内部使用LinuxAgentPrompter构造提示词、ContinueLinuxAgentState管理状态。其主提示词 ufo/prompts/third_party/linux_agent.yaml 明确了行为约束只输出可被json.loads()直接解析的 JSON含observation/thought/action/plan/result字段禁止执行rm -rf /、mkfs、shutdown等危险命令并在任务完成时通过FINISH状态返回完整文本结果。4.2 HardwareAgent物理硬件控制实验特性用途控制计算机的物理硬件组件例如用机械臂模拟键盘输入与鼠标控制、插拔 USB 设备等硬件相关任务。实验性警告HardwareAgent 是实验性功能依赖专用硬件环境如机械臂、USB 控制设备并非通用场景绝大多数用户无需启用。配置块THIRD_PARTY_AGENT_CONFIG: HardwareAgent: VISUAL_MODE: True AGENT_NAME: HardwareAgent APPAGENT_PROMPT: ufo/prompts/share/base/app_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/examples/visual/app_agent_example.yaml API_PROMPT: ufo/prompts/third_party/hardware_agent_api.yaml INTRODUCTION: The HardwareAgent is used to manipulate hardware components of the computer without using GUI, such as robotic arms for keyboard input and mouse control, plug and unplug devices such as USB drives, and other hardware-related tasks.字段说明字段类型说明VISUAL_MODEBoolean是否启用视觉模式截图理解能力默认开启AGENT_NAMEStringAgent 标识符必须为 HardwareAgentAPPAGENT_PROMPTString主提示词模板路径硬件 Agent 复用基础 AppAgent 提示词APPAGENT_EXAMPLE_PROMPTString示例提示词模板路径API_PROMPTString硬件 API 提示词模板路径INTRODUCTIONString提供给 LLM 的 Agent 描述文本启用场景使用机械臂完成物理输入操作自动化 USB 设备插拔管理物理硬件测试与自动化硬件控制类研究项目4.3 MobileAgentAndroid 移动设备控制从仓库当前实现ufo/agents/agent/customized_agent.py与默认配置可以看出项目还内置了第三个第三方 Agent——MobileAgent用于通过 ADB 与 UI 交互远程控制 Android 设备THIRD_PARTY_AGENT_CONFIG: MobileAgent: AGENT_NAME: MobileAgent APPAGENT_PROMPT: ufo/prompts/third_party/mobile_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/mobile_agent_example.yaml INTRODUCTION: For Android Mobile Device Control. Enables remote control and automation of Android devices via ADB and UI interactions.MobileAgent 同样以third_partyTrue注册agent_nameMobileAgent使用MobileAgentPrompter构造包含安装应用列表、当前屏幕控件、截图与标注截图的提示消息并以ContinueMobileAgentState作为默认状态。五、配置字段全解5.1 ENABLED_THIRD_PARTY_AGENTS类型List[String]默认值[]不启用任何第三方 Agent该列表是启用白名单只有出现在这里的 Agent 才会被加载并注册为目标。结合 config/config_schemas.py 的映射该配置在运行时对应system.enabled_third_party_agents。在 ufo/agents/agent/basic.py 的AgentRegistry.register中third_partyTrue的 Agent 若不在白名单内会被跳过并记录警告日志从而保证未启用的 Agent 不参与运行。可选值LinuxAgent— Linux CLI 执行HardwareAgent— 物理硬件控制MobileAgent— Android 移动设备控制配置示例# 仅启用 LinuxAgentUFO³ 推荐 ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent] # 同时启用两个 ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent, HardwareAgent] # 禁用全部 ENABLED_THIRD_PARTY_AGENTS: []5.2 THIRD_PARTY_AGENT_CONFIG类型Dict[String, Dict]每个 Agent 的独立配置字典结构约定为Agent 名 → 配置块THIRD_PARTY_AGENT_CONFIG: AgentName: AGENT_NAME: AgentName # Agent-specific fields...其中AGENT_NAME必须与类名一致。在 ufo/agents/agent/host_agent.py 的resolve_third_party_config中会读取system.third_party_agent_config.get(agent_name, {})并从中取出VISUAL_MODE默认 True、APPAGENT_PROMPT、APPAGENT_EXAMPLE_PROMPT组装 Agent 构造参数——这也是AGENT_NAME 不可随意修改的根源HostAgent 需要以该名称从配置块中定位到正确的字段。六、完整配置示例6.1 UFO³ Galaxy 场景推荐# Enable LinuxAgent for UFO³ Galaxy multi-device orchestration ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent] THIRD_PARTY_AGENT_CONFIG: LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only.6.2 同时启用 Linux 与硬件支持# Enable both Linux and Hardware agents ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent, HardwareAgent] THIRD_PARTY_AGENT_CONFIG: LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only. HardwareAgent: VISUAL_MODE: True AGENT_NAME: HardwareAgent APPAGENT_PROMPT: ufo/prompts/share/base/app_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/examples/visual/app_agent_example.yaml API_PROMPT: ufo/prompts/third_party/hardware_agent_api.yaml INTRODUCTION: The HardwareAgent is used to manipulate hardware components of the computer without using GUI, such as robotic arms for keyboard input and mouse control, plug and unplug devices such as USB drives, and other hardware-related tasks.6.3 最小配置不启用任何第三方 Agent# Disable all third-party agents (default for standalone UFO²) ENABLED_THIRD_PARTY_AGENTS: []七、UFO³ Galaxy 多设备编排集成在 UFO³ Galaxy 多设备编排场景中LinuxAgent 是支持 Linux 设备的必需组件完整接入分为三步Step 1在config/ufo/third_party.yaml中启用 LinuxAgentENABLED_THIRD_PARTY_AGENTS: [LinuxAgent] THIRD_PARTY_AGENT_CONFIG: LinuxAgent: AGENT_NAME: LinuxAgent APPAGENT_PROMPT: ufo/prompts/third_party/linux_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/linux_agent_example.yaml INTRODUCTION: For Linux Use Only.Step 2在config/galaxy/devices.yaml中登记 Linux 设备devices: - device_id: linux_server_1 server_url: ws://192.168.1.100:5001/ws os: linux capabilities: - server - cli - databaseStep 3启动 Linux Agent 组件完整的启动与部署步骤参见 Linux Agent 作为 Galaxy 设备 与 Linux Agent 快速开始。从源码看Galaxy 将任务路由到 Linux 设备后宿主侧会通过第三方 Agent 机制完成执行HostAgent 在目标注册阶段将所有已启用的第三方 Agent 作为kindthird_party_agent的目标写入注册表见ufo/agents/processors/strategies/host_agent_processing_strategy.py当选中第三方 Agent 目标时target.kind TargetKind.THIRD_PARTY_AGENT执行策略会调用_select_third_party_agent完成分配并最终通过resolve_third_party_config实例化对应 Agent。八、程序化访问配置第三方 Agent 配置可以像其他系统配置一样通过 Python API 读取。配置加载采用缓存机制get_ufo_config(reloadFalse)读取示例如下from config.config_loader import get_ufo_config config get_ufo_config() # 查看已启用的第三方 Agent enabled_agents config.ENABLED_THIRD_PARTY_AGENTS print(fEnabled third-party agents: {enabled_agents}) # 访问单个 Agent 的配置 if LinuxAgent in enabled_agents: linux_config config.THIRD_PARTY_AGENT_CONFIG[LinuxAgent] print(fLinuxAgent prompt: {linux_config[APPAGENT_PROMPT]}) # 判断特定 Agent 是否启用 linux_enabled LinuxAgent in config.ENABLED_THIRD_PARTY_AGENTS print(fLinuxAgent enabled: {linux_enabled})在运行时ENABLED_THIRD_PARTY_AGENTS实际对应config.system.enabled_third_party_agentsTHIRD_PARTY_AGENT_CONFIG对应config.system.third_party_agent_config映射关系定义于 config/config_schemas.py两种写法访问的是同一份数据。九、注册自定义第三方 Agent如果你想为项目增加新的专用 Agent可以遵循以下三步模式完整的以 HardwareAgent 为例的分步教程见 创建自定义第三方 Agent 教程。Step 1实现 Agent 类继承AppAgent或CustomizedAgent# ufo/agents/third_party/my_agent.py class MyCustomAgent: def __init__(self, config): self.config config # Initialize your agent参照仓库中CustomizedAgent/HardwareAgent/LinuxAgent/MobileAgent的写法自定义 Agent 需要以AgentRegistry.register(agent_nameMyCustomAgent, third_partyTrue, processor_cls...)完成注册并实现get_prompter、message_constructor、default_state等成员参见 ufo/agents/agent/customized_agent.py。Step 2添加配置ENABLED_THIRD_PARTY_AGENTS: [MyCustomAgent] THIRD_PARTY_AGENT_CONFIG: MyCustomAgent: AGENT_NAME: MyCustomAgent APPAGENT_PROMPT: ufo/prompts/third_party/my_agent.yaml APPAGENT_EXAMPLE_PROMPT: ufo/prompts/third_party/my_agent_example.yaml INTRODUCTION: Custom agent description. # 自定义字段 CUSTOM_FIELD: valueStep 3注册到 Agent 加载器将新 Agent 类纳入AgentRegistry通过register装饰器完成并确保AGENT_NAME与注册名一致HostAgent 才能以该名称解析配置并实例化。十、常见问题排查Issue 1LinuxAgent 不工作报错信息LinuxAgent not found or not enabled解决方案检查ENABLED_THIRD_PARTY_AGENTS是否包含 LinuxAgent且 Agent 是否已通过AgentRegistry注册# 确认 LinuxAgent 在启用列表中 ENABLED_THIRD_PARTY_AGENTS: [LinuxAgent]Issue 2提示词文件不存在报错信息FileNotFoundError: ufo/prompts/third_party/linux_agent.yaml解决方案确认提示词文件确实存在于配置指定的相对路径。在 Windows 上可用 PowerShell 校验Test-Path ufo\prompts\third_party\linux_agent.yaml Test-Path ufo\prompts\third_party\linux_agent_example.yaml仓库当前实际存在的第三方提示词目录为 ufo/prompts/third_party含linux_agent.yaml、linux_agent_example.yaml、mobile_agent.yaml、mobile_agent_example.yaml配置路径需与之一一对应。Issue 3配置修改不生效症状修改第三方 Agent 配置后行为未变化。解决方案配置在启动时一次性加载get_ufo_config带缓存修改后需重启 UFO 应用才能生效。十一、最佳实践与注意事项推荐做法✅只启用需要的 Agent——未使用的 Agent 不应出现在启用列表中避免不必要的目标注册与 LLM 上下文开销✅UFO³ Galaxy 场景务必启用 LinuxAgent——只要涉及 Linux 设备编排就必须启用✅保持提示词文件最新——确保配置中引用的提示词文件存在且内容与当前 Agent 能力一致✅为自定义 Agent 编写清晰的 INTRODUCTION——该文本会进入 LLM 上下文直接影响 Agent 被调用的准确性✅修改配置后验证加载——重启后通过日志或上文程序化访问脚本确认 Agent 正确加载风险警告❌未配备硬件环境时不要启用 HardwareAgent——它会注册为可选目标但缺少硬件时无法正常工作❌不要修改 AGENT_NAME——它必须与 Agent 类名/注册名一致否则resolve_third_party_config无法正确解析配置❌不要删除提示词文件——Agent 初始化时会直接读取这些路径文件缺失将导致初始化失败十二、小结third_party.yaml是 UFO 扩展非 GUI 能力的统一入口通过ENABLED_THIRD_PARTY_AGENTS白名单控制加载范围通过THIRD_PARTY_AGENT_CONFIG提供每个 Agent 的提示词与描述信息。LinuxAgent 支撑 UFO³ Galaxy 的 Linux 设备编排HardwareAgent 面向物理硬件控制实验特性MobileAgent 面向 Android 设备自动化三者与核心 HostAgent/AppAgent 以同一套 Agent 注册、目标注册、策略执行机制协作构成一个可平滑扩展的专用 Agent 生态。关键要点回顾✅third_party.yaml是可选配置仅在需要专用 Agent 时才使用✅ UFO³ 场景下 LinuxAgent 是使用 Linux 设备的必需配置✅ HardwareAgent 为实验特性仅用于物理硬件控制✅ 按需选择性启用避免无关 Agent 进入运行路径✅ 配置结构简单清晰——只需将 Agent 名加入启用列表并维护对应配置块延伸阅读创建自定义第三方 Agent 教程 — 以 HardwareAgent 为例的完整构建指南Linux Agent 作为 Galaxy 设备 — UFO³ 中 LinuxAgent 的部署使用Linux Agent 快速开始 — LinuxAgent 环境搭建Agent 配置 — 核心 Agent 的 LLM 设置Galaxy 设备配置 — 多设备配置【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考