智能体、会话与自动化

使用 moi-cli agent 与 moi-cli conversation 发现并调用智能体、处理图片与交互式 A2A 请求、在本地构建智能体包、管理已加载版本与定时自动化任务,以及维护工作区持久化会话记录。除离线智能体包构建命令外,其余命令执行前请先完成 配置与身份认证。

发现智能体、发送文本与跟踪任务

列出工作区或系统目录中的智能体,读取智能体卡片,并通过便捷入口 agent send 提交纯文本请求:

# 列出可用智能体并读取智能体卡片
moi-cli -auth pat -o agent list --workspace-id "$WORKSPACE_ID"
moi-cli -auth pat -o agent card --workspace-id "$WORKSPACE_ID" --agent-id "$AGENT_ID"

# 发送纯文本消息并查询或取消任务
moi-cli -auth pat -o agent send \
  --workspace-id "$WORKSPACE_ID" \
  --agent-id "$AGENT_ID" \
  --text '请汇总本周订单异常原因。'

moi-cli -auth pat -o agent get-task \
  --workspace-id "$WORKSPACE_ID" \
  --agent-id "$AGENT_ID" \
  --task-id "$AGENT_TASK_ID"

moi-cli -auth pat -o agent cancel-task \
  --workspace-id "$WORKSPACE_ID" \
  --agent-id "$AGENT_ID" \
  --task-id "$AGENT_TASK_ID"

agent send、get-task 和 cancel-task 支持通过 --agent-id 或 --agent-code 指定目标智能体。智能体 A2A 任务 ID(字符串)、持久化会话 conversation 的数值型 session_id 与工作流 execution_id 分属不同服务体系,调用时按各自命令组要求传入对应标识。

发送图片、重新生成与提交交互答复

发送图片附件、基于原任务重新生成回答或答复挂起交互时,使用 agent a2a(或流式输出命令 agent a2a-stream --output)提交完整 A2A JSON 请求。可先运行 moi-cli schema agent a2a 查看 CLI 输入顶层字段(agent_id / agent_code、jsonrpc、id、method、params):

操作场景

请求文件示例

关键输入要素

发送 Catalog 卷中的图片

image-request.json

目标 agent_id、视觉模型名称,以及同一图片对应的 moi://files/<file_id> 与 catalog_file(workspace_id、正整数 volume_id、file_id)。

重新生成已完成回答

regenerate-request.json

已完成原任务的 taskId 与 contextId、预先保存的唯一 controlId 及 moi.run.control(action: "regenerate")。

答复工具问题请求

input-request.json

method: "matrixflow/input.submit"、处于 input-required 状态的 taskId、当前 inputRequestId 及按问题 ID 组织的 answers。

答复供应商交互请求

provider-request.json

原交互 requestId、目标 target 及 moi.provider_interaction.respond 要求的 payload(取消时设 cancelled: true 并省略 payload)。

例如,将已上传到当前工作区 Catalog 卷的 PNG 图片请求保存为 image-request.json(完整四种协议请求模板见 发送图片、重新生成与提交交互答复):

{
  "agent_id": "<agent-id>",
  "jsonrpc": "2.0",
  "id": "req-image-001",
  "method": "message/send",
  "params": {
    "model": "<vision-model-name>",
    "message": {
      "kind": "message",
      "role": "user",
      "messageId": "msg-image-001",
      "parts": [
        {
          "kind": "text",
          "text": "请描述图中的标签和数值。"
        },
        {
          "kind": "file",
          "file": {
            "uri": "moi://files/<image-file-id>",
            "mimeType": "image/png",
            "name": "chart.png"
          },
          "metadata": {
            "file_id": "<image-file-id>"
          }
        }
      ]
    },
    "metadata": {
      "files": [
        {
          "catalog_file": {
            "workspace_id": "<workspace-id>",
            "volume_id": 123,
            "file_id": "<image-file-id>"
          }
        }
      ]
    }
  }
}

提交请求并解码外层 json 字符串字段以提取真实任务 id:

# --no-wait 在服务端受理后立即返回响应
moi-cli -auth pat -o agent a2a --no-wait --json-file image-request.json > image-response.json

# 解码内嵌 JSON-RPC 响应并提取 kind == "task" 时的任务 id
jq '.json | fromjson | (.result // .)' image-response.json

export AGENT_TASK_ID="$(jq -r '.json | fromjson | (.result // .) | select(.kind == "task") | .id' image-response.json)"
moi-cli -auth pat -o agent get-task --agent-id "$AGENT_ID" --task-id "$AGENT_TASK_ID"

执行重新生成或答复挂起交互时,分别提交对应请求文件:

moi-cli -auth pat -o agent a2a --no-wait --json-file regenerate-request.json
moi-cli -auth pat -o agent a2a --json-file input-request.json
moi-cli -auth pat -o agent a2a --json-file provider-request.json

警告

重新生成回答可能再次触发外部工具写入操作;若响应为 moi.run.control.result 确认消息,需从相同 controlId 对应的数据中读取新 taskId 进行跟踪,而工具问题与供应商交互答复则继续轮询原任务。请求超时后请保留原 JSON 文件与控制标识先回查任务状态,避免重复提交。

配置智能体固定输出语言

读取目标智能体当前元数据并合并 metadata.output_language(设为空字符串 "" 可清除固定语言;存在并发编辑时请先刷新读取再合并,以免覆盖其他元数据键):

moi-cli -auth pat -o agent resource-get --resource agents --tail-path "/$AGENT_ID" > agent-before.json
jq '{metadata: ((.metadata // {}) + {output_language: "zh-CN"})}' agent-before.json > language-update.json
moi-cli -auth pat -o agent resource-patch --resource agents --tail-path "/$AGENT_ID" --json-file language-update.json
moi-cli -auth pat -o agent resource-get --resource agents --tail-path "/$AGENT_ID"

本地构建智能体包与管理工作区技能包

moi-cli 提供四个无需登录、无需工作区或远端 API 连接的本地智能体包生命周期命令(若您的安装包未包含该组子命令,可向部署管理员获取与目标部署匹配的安装包):

# 1. 初始化智能体包源码目录(目标目录须尚不存在)
moi-cli agent init --output ./assistant-package --agent-id com.example.assistant

# 2. 离线校验源码目录并构建确定性 .moiagent 包
moi-cli agent verify --source ./assistant-package
moi-cli agent build --source ./assistant-package --output assistant.moiagent --overwrite

# 3. 离线校验构建产物或解包还原为可编辑源码目录
moi-cli agent verify --file assistant.moiagent
moi-cli agent unpack --file assistant.moiagent --output ./editable-assistant

当 agent.yaml 声明 minMOIVersion 时,build、verify 和 unpack 可通过 --running-moi-version <version> 显式指定目标运行版本进行兼容性校验;unpack 会自动移除构建生成的 checksums.txt 与已编译自定义工具产物。

将智能体包或技能包导入工作区时,使用以下需要身份认证的子命令:

场景

子命令

说明

加载或导出智能体包

load-agent-package --file-path <file>、export-agent-package

将 .moiagent 包加载到目标工作区,或导出已有智能体包。

检查、导入与读取技能包

inspect-skill-package --file-path <file>、import-skill-package --file-path <file>、get-skill-file、download-skill-files、polish-skill-stream

上传前先运行 inspect-skill-package 校验结构并确认不含敏感凭据;沙箱任务内 download-skill-files --skill-id <id> --output-dir <new-dir> 仅解包绑定技能文件,不自动执行脚本。

上传工作区附加文件

upload-workspace-file --file-path <file>

上传智能体关联的工作区文件(默认单文件上限 64 MiB,可通过 --max-upload-bytes 调整)。

管理智能体版本

查看智能体已加载的版本列表与当前默认版本(查询系统目录只读智能体时可附加 --query-param agent_workspace_id=system):

# 读取 items[].version、status、diagnostics 与 lineage.default_version
moi-cli -auth pat -o agent resource-get \
  --resource agents \
  --tail-path "/$AGENT_ID/versions" > versions.json

# 将已就绪的目标版本切换为默认版本并回读确认
moi-cli -auth pat -o agent resource-post \
  --resource agents \
  --tail-path "/$AGENT_ID/versions/$TARGET_AGENT_VERSION/default" \
  --json '{}'
moi-cli -auth pat -o agent resource-get --resource agents --tail-path "/$AGENT_ID/versions"

清理不再使用的非默认历史版本时,先停用该版本,确认 status 变为 disabled 后再执行删除:

moi-cli -auth pat -o agent resource-post \
  --resource agents \
  --tail-path "/$AGENT_ID/versions/$OLD_AGENT_VERSION/disable" \
  --json '{}'

moi-cli -auth pat -o agent resource-delete \
  --resource agents \
  --tail-path "/$AGENT_ID/versions/$OLD_AGENT_VERSION"

警告

当前默认版本无法直接停用或删除,且处于启用状态的版本必须先完成 disable 才能删除。存在配置缺失的版本请先根据 diagnostics 修复并生成新版本,再切换默认版本。

管理定时与触发式自动化任务

准备自动化任务定义 automation.json(客户端预先生成唯一任务 id;即使初始状态设为 disabled,服务端仍会立即校验 Cron 表达式):

{
  "id": "<new-task-id>",
  "name": "每日摘要",
  "agent_id": "<agent-id>",
  "model": "<available-model>",
  "instruction_text": "汇总当日已授权的数据。",
  "trigger": {
    "mode": "cron",
    "cron_expression": "TZ=UTC 0 9 * * *"
  },
  "status": "disabled"
}

创建任务、更新调度时间并启用(更新请求中省略服务端生成的只读字段 service_name):

# 1. 创建任务并回读配置(若超时,先用预先生成的 id 回查详情)
moi-cli -auth pat -o agent resource-post \
  --resource agent-automation-tasks \
  --json-file automation.json > created.json

export AUTOMATION_TASK_ID="$(jq -r '.id' created.json)"
moi-cli -auth pat -o agent resource-get \
  --resource agent-automation-tasks \
  --tail-path "/$AUTOMATION_TASK_ID" > task.json

# 2. 更新 Cron 计划并激活任务,随后核对 status、version 与含时区偏移的 next_trigger_at
cat > schedule.json <<'EOF'
{"trigger":{"mode":"cron","cron_expression":"TZ=UTC 0 10 * * *"},"status":"active"}
EOF

moi-cli -auth pat -o agent resource-patch \
  --resource agent-automation-tasks \
  --tail-path "/$AUTOMATION_TASK_ID" \
  --json-file schedule.json
moi-cli -auth pat -o agent resource-get \
  --resource agent-automation-tasks \
  --tail-path "/$AUTOMATION_TASK_ID"

手动触发已启用的 Cron 任务、查询运行历史以及停用或归档任务:

# 查询单任务运行历史或工作区级运行记录(支持 status、RFC 3339 created_from/created_to,limit 最大 200)
moi-cli -auth pat -o agent resource-get \
  --resource agent-automation-tasks \
  --tail-path "/$AUTOMATION_TASK_ID/runs" \
  --query-param limit=50 --query-param offset=0

moi-cli -auth pat -o agent resource-get \
  --resource agent-automation-runs \
  --query-param status=succeeded --query-param limit=50 --query-param offset=0

# 手动触发一次已启用的 Cron 任务,并跟踪运行详情、事件与最终结果
moi-cli -auth pat -o agent resource-post \
  --resource agent-automation-tasks \
  --tail-path "/$AUTOMATION_TASK_ID/runs" \
  --json '{"payload":{}}' > run.json

export AUTOMATION_RUN_ID="$(jq -r '.id' run.json)"
moi-cli -auth pat -o agent resource-get --resource agent-automation-runs --tail-path "/$AUTOMATION_RUN_ID"
moi-cli -auth pat -o agent resource-get --resource agent-automation-runs --tail-path "/$AUTOMATION_RUN_ID/events" --query-param limit=20 --query-param offset=0
moi-cli -auth pat -o agent resource-get --resource agent-automation-runs --tail-path "/$AUTOMATION_RUN_ID/result"

# 停用后续调度(已启动的运行继续按原 AUTOMATION_RUN_ID 查询)与归档任务
moi-cli -auth pat -o agent resource-patch --resource agent-automation-tasks --tail-path "/$AUTOMATION_TASK_ID" --json '{"status":"disabled"}'
moi-cli -auth pat -o agent resource-delete --resource agent-automation-tasks --tail-path "/$AUTOMATION_TASK_ID"

API 触发型自动化任务使用其返回的 api_summary 入口调用,回调触发型任务走对应回调链路。对 agent-automation-tasks 执行 resource-delete 会将任务置为 status: archived,任务定义与历史运行记录仍保留可读;新建同名任务时请使用新的任务 id。

管理持久化会话与消息

使用 conversation 命令组查询和维护当前身份可见的工作区持久化会话(使用数值型 session_id):

# 分页查询会话列表(可附加 source、keyword 或 tag 筛选参数)
moi-cli -auth pat -o conversation list-sessions \
  --workspace-id "$WORKSPACE_ID" \
  --query-param page=1 \
  --query-param page_size=20

# 读取会话详情与消息列表(消息翻页使用 after=<上一页末条消息ID> 与 limit=50,直至返回空数组)
moi-cli -auth pat -o conversation get-session --workspace-id "$WORKSPACE_ID" --session-id "$SESSION_ID"
moi-cli -auth pat -o conversation list-messages \
  --workspace-id "$WORKSPACE_ID" \
  --session-id "$SESSION_ID" \
  --query-param limit=50

list-messages 返回的 total 统计会话总消息数,不会随游标 after 递减;JSON 输出可能省略零值字段(例如用户消息的 role=0)。

更新会话标题与维护消息

更新会话标题时,可在 session-update.json 中填入当前标题作为 expected_title 进行乐观并发校验:

{
  "title": "归档后的讨论",
  "expected_title": "<详情中当前标题>"
}
moi-cli -auth pat -o conversation update-session \
  --workspace-id "$WORKSPACE_ID" \
  --session-id "$SESSION_ID" \
  --json-file session-update.json

# 删除不再保留的会话
moi-cli -auth pat -o conversation delete-session \
  --workspace-id "$WORKSPACE_ID" \
  --session-id "$SESSION_ID"

警告

当 expected_title 与服务端当前标题不一致时,conversation update-session 仍可能以退出码 0 正常返回当前会话对象而不应用新标题。提交后请比对响应中的 title 或运行 get-session 复核(空 title 或空 config 不会清空原值)。

conversation modify-response 与 append-modified-response 仅修改持久化存储中的回答文本,不会触发模型重新推理。入站 IM 连接与外部插件账号授权见 消息通道与插件连接。

限制和注意事项

  • 工作区级运行列表 agent-automation-runs 不解析 automation_task_id 查询参数;按单个自动化任务筛选运行记录请使用 agent-automation-tasks --tail-path "/$AUTOMATION_TASK_ID/runs"。

  • created_from 与 created_to 采用 RFC 3339 时间格式(左闭右开区间);并发新增运行记录时偏移分页可能出现重复项,脚本处理时请按运行 id 去重。

  • 请勿在聊天文本、A2A JSON 或公开日志中写入个人访问令牌、连接器密钥或第三方平台凭据。

最后更新于