智能体、会话与自动化¶
使用 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 卷中的图片 |
|
目标 |
重新生成已完成回答 |
|
已完成原任务的 |
答复工具问题请求 |
|
|
答复供应商交互请求 |
|
原交互 |
例如,将已上传到当前工作区 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 与已编译自定义工具产物。
将智能体包或技能包导入工作区时,使用以下需要身份认证的子命令:
场景 |
子命令 |
说明 |
|---|---|---|
加载或导出智能体包 |
|
将 |
检查、导入与读取技能包 |
|
上传前先运行 |
上传工作区附加文件 |
|
上传智能体关联的工作区文件(默认单文件上限 64 MiB,可通过 |
管理智能体版本¶
查看智能体已加载的版本列表与当前默认版本(查询系统目录只读智能体时可附加 --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 或公开日志中写入个人访问令牌、连接器密钥或第三方平台凭据。