# 智能体、会话与自动化

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

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

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

```bash
# 列出可用智能体并读取智能体卡片
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` 分属不同服务体系，调用时按各自命令组要求传入对应标识。

(cli-agent-message-inputs)=

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

发送图片附件、基于原任务重新生成回答或答复挂起交互时，使用 `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`（完整四种协议请求模板见 [发送图片、重新生成与提交交互答复](../../api/ai-studio/agents/message-inputs.md)）：

```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`：

```bash
# --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"
```

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

```bash
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
```

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

### 配置智能体固定输出语言

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

```bash
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 连接的本地智能体包生命周期命令（若您的安装包未包含该组子命令，可向部署管理员获取与目标部署匹配的安装包）：

```bash
# 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` 调整）。 |

(cli-agent-versions)=

## 管理智能体版本

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

```bash
# 读取 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` 后再执行删除：

```bash
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"
```

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

(cli-agent-automations)=

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

准备自动化任务定义 `automation.json`（客户端预先生成唯一任务 `id`；即使初始状态设为 `disabled`，服务端仍会立即校验 Cron 表达式）：

```json
{
  "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`）：

```bash
# 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 任务、查询运行历史以及停用或归档任务：

```bash
# 查询单任务运行历史或工作区级运行记录（支持 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`）：

```bash
# 分页查询会话列表（可附加 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`）。

(cli-conversation-update)=

### 更新会话标题与维护消息

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

```json
{
  "title": "归档后的讨论",
  "expected_title": "<详情中当前标题>"
}
```

```bash
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"
```

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

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

## 限制和注意事项

- 工作区级运行列表 `agent-automation-runs` 不解析 `automation_task_id` 查询参数；按单个自动化任务筛选运行记录请使用 `agent-automation-tasks --tail-path "/$AUTOMATION_TASK_ID/runs"`。
- `created_from` 与 `created_to` 采用 RFC 3339 时间格式（左闭右开区间）；并发新增运行记录时偏移分页可能出现重复项，脚本处理时请按运行 `id` 去重。
- 请勿在聊天文本、A2A JSON 或公开日志中写入个人访问令牌、连接器密钥或第三方平台凭据。
