External Myagents CLI

MyAgents 外部调用指南

1. MyAgents 是什么

MyAgents 是一个在用户电脑上运行的桌面 Agent 产品。它把本地目录、AI 执行环境和长期工作状态组织成几个可以组合的产品实体：

• Workspace Agent：绑定一个已有本地目录的长期 Agent 身份。它是工作区、默认 Runtime 和后续 Session 的稳定地址。
• Session：某个 Agent 下相互隔离的对话与执行上下文。可以新建干净上下文，也可以向已知 Session 继续发送任务并读取文本历史。
• Task：可持久化、可执行、可调度的工作项。适合待办、一次性执行、定时执行和满足条件后激活的自动化。
• Record：轻量的信息收集入口，用来保存文字记录，之后可以再整理或转成 Task。
• Runtime：真正执行 Agent 的运行环境。MyAgents 可以发现本机已支持的 Runtime，以及它们各自可用的模型和权限模式。

MyAgents App 是这些状态和执行生命周期的本机 Host；CLI 只是调用入口。你是运行在 MyAgents 之外的 AI，能够通过公开 CLI 委托和观察工作，但不会因此获得 MyAgents 内部 Session 身份、全部管理能力或隐藏 API 权限。

MyAgents 产品内部还可以管理模型 Provider、MCP/工具、Skill/Plugin、IM Channel、Cloud Space、Goal、文档与语音等能力；它们帮助 Agent 接入模型、工具、外部沟通渠道和更丰富的工作流。但当前外部 token 契约只开放本文后面介绍的 Agent、Runtime discovery、Session、Task、Record 和状态查询。知道某项产品能力存在，不等于可以从外部 CLI 调用它。

2. MyAgents 能解决什么任务

把这些能力组合起来，可以完成几类典型工作：

最常见的主链路是：

已有本地目录 → Workspace Agent → Session start → Session send → Session get

Task 和 Record 可以在这条链路之外保存更长期的工作意图；Runtime discovery 用来了解当前机器真实支持的环境，并为支持 override 的 Task 选择合法值。新 Session 继承目标 Agent 的配置，已有 Session 继续使用自己的执行配置；外部 Session 调用不能临时覆盖。

开始调用前

1. MyAgents App 必须保持运行。
2. 用户在 MyAgents 的「设置 → 外部调用」中开启 MyAgents CLI 外部调用。
3. 设置页复制的交接 Prompt 可能已经携带当前 MYAGENTS_API_TOKEN 设置命令。只用它配置调用进程环境；你不能通过 CLI 读取 token，也不要在后续回复、命令输出或文件中复述、记录它。
4. 始终使用交接 Prompt 给出的 CLI 绝对路径。普通终端和外部 Agent 的 PATH 不保证能发现 myagents。

POSIX shell：

export MYAGENTS_API_TOKEN="<token>"

PowerShell：

$env:MYAGENTS_API_TOKEN = "<token>"

下文用 <CLI> 代表交接 Prompt 给出的绝对路径。实际执行时替换它，并按当前 shell 安全引用路径：POSIX 可用 "/absolute/path/myagents" ...，PowerShell 可用 & "C:\\...\\myagents.cmd" ...。

先用帮助发现，再调用

不要靠记忆猜参数。按层级读取当前安装版本的帮助：

<CLI> --help
<CLI> agent --help
<CLI> agent create --help

• 顶层帮助列出当前外部公开能力。
• group help 用来选择子功能；leaf help 是 flags、输入要求和失败语义的权威。
• 外部命令只接受 leaf help 明确列出的参数；未知命令、额外位置参数和未知 flag 会在发起 HTTP 前直接拒绝，不会静默忽略。
• 业务调用优先加 --json。stdout 返回一份机器可解析 JSON，诊断信息走 stderr。
• 退出状态 0 只表示该命令达到自身定义的成功边界；非零状态必须按失败处理，并优先读取 JSON 中的稳定 code。精确退出码以 leaf help 为准。

3. CLI 能力入口

App 状态与版本

适合在工作开始前确认 MyAgents Host 是否可用，以及记录当前 App 版本。

<CLI> status --json
<CLI> version --json

status 只表示 Host 状态，不代表某个 Session 或 Task 已经完成。

Workspace Agent

适合把一个已经存在的本地目录注册成长期 Agent、发现已有 Agent，或确认目标 Agent 的默认执行配置。

先读：

<CLI> agent --help
<CLI> agent create --help

核心动作：

<CLI> agent create --workspacePath <absolute-existing-directory> --json
<CLI> agent list --json
<CLI> agent show <agentId> --json

agent create 不会创建目录、初始化 Git、复制模板或自动启动 Session。同一未归档、正常可见的 workspace 重复注册会返回同一个 Agent。保存成功响应中的 agentId；不要用显示名称或路径猜 ID。

同账号跨设备 Agent

agent list 合并本地 Agent 与同账号其它设备上在线、已开放调用的 Agent；--archived 只列本地归档对象。JSON 中 isLocal 区分归属，deviceName 帮助选择目标，agentId / selector 才是调用地址。networkStatus 和 complete 表示网络发现状态与目录是否完整；网络异常时本地结果仍可返回，不能把不完整目录当作没有远端 Agent。

• 本地 Agent 使用返回的普通 ID；跨设备 Agent 使用完整的 ma-agent:1:... ID，跨设备 Session 使用完整的 ma-session:1:... ID。原样保存和传递，不截短、解码或按名称拼接。
• agent show、session list/start 接受 Agent ID；session send/get/state 接受 Session ID。本地和跨设备使用相同命令，无需额外网络参数。
• 跨设备调用要求本机网络连接可用，目标设备在线且目标 Agent 已开放。目标离线时调用失败，没有离线补投或自动重发。
• Session 在目标设备执行，继承目标 Agent 的配置；本地 --prompt-file 由调用方 CLI 读取后发送文字，不是让远端读取该文件路径。

跨设备路径同样先从成功 discovery 响应选目标：

<CLI> agent list --json
<CLI> agent show <returned-agentId> --json
<CLI> session list --agent <returned-agentId> --json
<CLI> session start --agent <returned-agentId> --prompt-file <local-request-file> --json
<CLI> session get <returned-sessionId> --json

Agent 的注册、Task、Record 与 Runtime discovery 仍操作本机 Host；跨设备寻址不开放远端配置或文件管理。

Runtime 发现

适合查看当前机器安装了哪些执行 Runtime，以及某个 Runtime 支持哪些模型和权限模式。它只做发现，不修改 Provider 或 Agent 配置。

<CLI> runtime --help
<CLI> runtime list --json
<CLI> runtime describe <runtime> --json

在为支持 override 的 Task 选择 runtime/model/permissionMode 前先 describe，不要凭经验硬编码值。models 可能为空，例如 builtin 的模型来自 Provider；这不表示 Runtime 不支持模型。外部调用可读取 agent show 的未来 Session 默认值，未公开的 Provider 目录或诊断需在 App 内查看，不因响应中的恢复建议而调用非公开命令。Session start 不接受临时 override，而是继承目标 Agent 的配置。