通过官方 Skill szagent-cli，让第三方 AI Agent 调用实在智能体。

1. 您可以如何使用

实在 Agent CLI 为实在智能体提供命令行调用入口。配合官方 Skill szagent-cli，您可以在具备本机命令执行能力的第三方 AI Agent 中，通过自然语言查找和运行实在智能体，并查询执行情况。

例如，您可以向 AI Agent 提出：

使用官方 Skill szagent-cli，帮我找到“销售数据分析”智能体，先查看需要哪些输入，缺少的信息请向我询问。

准备好输入后，继续提出：

使用我刚才确认的参数运行这个智能体，查询执行状态，完成后把结果整理给我。

上述智能体名称仅作示例，请替换为您账号下的实际名称。

您也可以直接在终端或脚本中调用 CLI。两种方式使用同一套调用入口：通过 Skill 使用时，由 AI Agent 根据指引组织命令；直接使用命令行时，由您填写参数并处理返回结果。

2. 使用前准备

开始前，请完成以下准备：

在执行任务的 Windows 电脑上安装 7.3.9 及以上版本的实在 Agent 客户端。
启动客户端，登录您的账号，并保持客户端运行。
确认目标智能体位于当前账号的“我的智能体->我创建的”中，并且账号具备使用权限。
获取与当前 CLI 版本配套的官方 Skill szagent-cli。客户端安装包及 Skill 获取方式，请联系实在交付或技术支持人员。
选择支持加载 Skill、并可在上述电脑上执行本地命令的 AI Agent。

AI Agent 的命令执行环境需要能够访问这台电脑上的 CLI 和客户端。 仅在远程云端运行、无法访问本机环境的聊天工具，不能直接完成调用。

3. 推荐方式：通过官方 Skill `szagent-cli` 使用

第一步：加载 `szagent-cli`

按照 AI Agent 的 Skill 安装说明，导入实在提供的 szagent-cli Skill 文件或目录，并在该工具中启用。部分工具需要重新加载 Skill 或新建对话后才能生效，请以所用工具的说明为准。

如果工具没有 Skill 导入或加载能力，请先确认其是否支持此使用方式。

第二步：检查连接情况

在 AI Agent 中输入：

使用官方 Skill szagent-cli，检查 CLI 版本、客户端登录状态，并列出我的智能体。

首次使用时，如果第三方 AI Agent 要求授权执行本机命令，请按该工具的提示完成授权。成功后，应能获取版本信息、当前账号状态和智能体列表。

第三步：选择智能体并准备输入

告诉 AI Agent 您想使用哪个智能体，以及要完成的工作：

找到我的“销售数据分析”智能体，查看它需要的输入参数，先告诉我需要提供哪些信息。

AI Agent 可根据入参定义准备调用参数。出现多个同名智能体时，请补充信息或指定目标 ID；缺少必填信息时，请先补齐再运行。

第四步：运行并获取结果

确认目标与输入后，向 AI Agent 下达运行指令：

使用已确认的参数运行这个智能体。请保留执行 ID，查询状态，完成后展示结果。

运行受理后会返回执行 ID。任务已受理不代表执行已完成，需要继续查询状态和结果。若 AI Agent 没有持续查询，您可以补充：

查询刚才执行 ID 对应的任务状态；如果已经完成，请获取并整理结果。

第三方 AI Agent 是否自动持续跟踪，取决于其自身的工具调用与会话机制。

第五步：处理交互或查看执行情况

您的需要	可向 AI Agent 提出的指令
任务需要填写表单	查看当前任务需要补充的表单内容，向我确认后提交。
查询执行状态	查询这个执行 ID 对应的任务状态。
停止任务	停止刚才通过 CLI 发起的任务，并查询停止后的状态。
查看日志	查询这个任务的执行日志，帮我定位报错信息。
查看历史	查询这个智能体的运行历史，展示返回的记录。

表单提交适用于任务实际出现交互表单的情况；停止请求发出后，请继续查询状态，确认任务是否已经停止。

4. 传统方式：直接使用命令行

您也可以在 Windows PowerShell 中执行命令，适用于手动调试或脚本集成。

检查环境与查找智能体

# 查看 CLI 与客户端版本信息。
szagent version

# 查询当前客户端账号状态，确认登录环境可用。
szagent account current

# 列出我的智能体；名称搜索可帮助缩小选择范围。
szagent agent list --search "销售数据分析"

# 查看当前安装版本支持的命令与参数。
szagent --help

查询参数并发起运行

# 将占位文字替换为列表返回的真实 agent_id。
$agentId = "替换为真实智能体ID"

# 先读取目标智能体的输入定义，再准备运行参数。
szagent agent schema --id $agentId

# 以下仅演示输入中包含 query 的情况；字段须按实际 schema 调整。
# ConvertTo-Json 用于构造合法 JSON，避免手工拼接输入内容。
$inputJson = @{ query = "请分析本月销售情况" } | ConvertTo-Json -Compress
szagent agent run --id $agentId --input-json $inputJson

请保存运行返回的 execution_id，用于后续查询和控制任务。示例中的 query 不是所有智能体通用的固定参数。

查询状态、日志与历史

# 将占位文字替换为 run 返回的真实 execution_id。
$executionId = "替换为真实执行ID"

# 查询执行状态与可用结果；命令返回成功不等于任务已执行成功。
szagent agent status --execution-id $executionId

# 查看该次执行的日志。
szagent agent logs --execution-id $executionId

# 使用前一步设置的 agentId 查询目标智能体的历史记录。
szagent agent history --id $agentId

# 同时指定智能体 ID 和执行 ID，查询对应历史详情。
szagent agent history --id $agentId --execution-id $executionId

如需停止任务，可单独执行：

# 仅在需要停止时执行；执行后应再次查询状态确认结果。
szagent agent stop --execution-id $executionId

交互表单的提交参数请查看当前安装版本的帮助：

# 按实际表单与本机帮助准备提交参数。
szagent agent form submit --help

理解返回结果

CLI 业务命令使用 JSON 返回结果，常见字段含义如下：

字段	含义
`ok`	本次命令请求是否成功。
`code`	本次请求的业务结果码，可辅助判断错误原因。
`message`	本次请求的说明信息。
`data`	业务数据，例如智能体列表、执行 ID、状态或结果。
`request_id`	本次命令请求标识，便于排查问题。

脚本集成时，应分别判断“命令请求是否成功”和“任务是否执行完成”，并保存真实的智能体 ID、执行 ID，避免通过名称猜测或混用标识。

5. 常见问题

问题	处理方式
AI Agent 没有使用官方 Skill	检查 Skill 是否加载成功，并在指令中明确“使用官方 Skill `szagent-cli`”。
AI Agent 无法执行命令	确认其具备本机命令执行能力，执行环境可访问 CLI，并已按工具要求授权。
客户端或本地服务不可用	打开实在 Agent 客户端，确认其正常运行后重试。
提示未登录或本地鉴权凭证缺失	在客户端确认登录状态，并核对 CLI 与当前运行客户端是否来自配套安装环境。
找不到目标智能体	核对账号、智能体名称和权限，并确认目标位于“我的智能体->我创建的”中。
提示参数缺失或不合法	重新查询目标智能体的入参定义，补齐必填项并检查类型。
运行已受理但没有结果	使用执行 ID 查询状态；若失败，再查询日志。不要仅因暂时没有结果而重复发起任务。
提示不支持某个参数	查看本机 `--help`，并确认 `szagent-cli` 与当前 CLI 版本配套，客户端版本为 7.3.9 及以上。

6. 使用范围

本文围绕当前 CLI 的“我的智能体->我创建的”调用流程，介绍查找、入参查询、运行、状态与结果查询，以及表单提交、停止、日志和历史查询入口。具体命令参数以您安装版本的 --help 为准。

使用期间请保持 7.3.9 及以上版本的客户端运行和账号登录。CLI 复用客户端登录状态，您无需在第三方 AI Agent 对话中提供账号密码。通过 Skill 调用时，任务输入和返回内容可能进入第三方 AI Agent 的处理流程，请按贵公司的数据使用要求选择输入内容。

实在 Agent CLI 使用说明