操作方法：部署 UiPath 智能体

本页将介绍 CLI 中低代码 UiPath 智能体的完整生命周期：将其搭建在磁盘上，然后进行验证、打包、发布和部署到 Orchestrator — 准备将其作为作业运行。它使用uip agent工具，这与uip codedagent （基于 Python 的编码智能体）不同。

如果您已经熟悉uip solution部署，那么您需要了解的关键是智能体可以在没有解决方案包装器的情况下进行部署。uip agent publish命令在内部运行自己的包 → 迁移 → 解决方案包 → 上传管道，而uip agent deploy直接安装结果。您永远不需要为单智能体项目创作.uipx解决方案清单。

生命周期

init → validate → pack → publish → deploy → run

每个动词产生的消耗量由下一个动词消耗：

动词	输入	输出	需要登录
init	目标目录	agent.json + 项目树	否
validate	项目目录	磁盘上已迁移的文件	否
pack	项目目录	.uis 归档	否
publish	项目目录或.uis	PackageVersionKey 在 Orchestrator 中	是
deploy	PackageVersionKey	已部署文件夹 + 版本	是

局部动词（ init 、 validate和pack ）不需要活动会话，并且可以在任何构建阶段运行。要写入 Orchestrator，所有内容都首先需要uip login 。

1. 框架

使用uip agent init创建新的智能体项目：

uip agent init ./invoice-agent \
  --model gpt-4o-2024-11-20 \
  --system-prompt "You are an invoice triage agent."

这将写入一个完整的独立项目树：

invoice-agent/
  agent.json
  project.uiproj
  entry-points.json
  flow-layout.json
  evals/
    evaluators/<semantic>.json
    evaluators/<trajectory>.json
    eval-sets/evaluation-set-default.json
  features/
  resources/

目录名称将成为智能体名称；它必须匹配[a-zA-Z0-9_ -]+ 。传递--force以覆盖非空目录。

对于驻留在 Maestro 流中的智能体，请改用--inline-in-flow — 它将生成一个以 UUID 命名的子文件夹，仅包含agent.json和flow-layout.json 。请参阅init --inline-in-flow 。

2. 作者资源

真实智能体通常需要三种资源。直接编辑agent.json ，或使用结构化编辑命令：

• 输入和输出— 对于架构参数，为uip agent input add / uip agent output add 。
• 工具— uip agent tool add ，适用于 Integration Service 连接器、Orchestrator 流程、其他智能体、API 工作流、流程编排流和 IXP 技能。
• 上下文— uip agent context add表示 RAG 索引绑定。
• 升级— uip agent escalation add表示人机回圈交接。

# Add an input parameter
uip agent input add invoicePath --type string \
  --description "Path to the invoice PDF"

# Add an output parameter
uip agent output add verdict --type string

# Add a RAG context bound to an index
uip agent context add invoiceKnowledge --index invoices-kb

# Add a Slack integration tool
uip agent tool add notify --type integration \
  --connector uipath-slack --object-name message

有关完整标志设置，请参阅相应的参考页面。每次编辑都会使agent.json和entry-points.json保持同步。

3. 验证

在对agent.json进行任何手动编辑后（或在进行一轮结构化编辑后），运行uip agent validate ：

uip agent validate ./invoice-agent

验证仅在本地进行（无需登录），并运行静态检查通道和架构迁移管道。成功后，迁移的文件内容将写回磁盘，并重新生成.agent-builder/框架。失败时，您将获得带有文件路径的错误列表和退出代码1 — 未写入任何内容。

在发布步骤之前，在 CI 中将其作为入口运行；它会捕获会缓慢发布的错误类别（模型无效、 messages[].contentTokens损坏、架构中缺少required条目）。

4. 打包（可选）

uip agent pack将项目捆绑到.uis存档中。仅在以下情况下，您才需要此选项：

• 您想要一个工件以进行手动检查或存档。
• 您计划使用uip agent push推送到 Studio Web 进行交互式编辑。
• 您的管道使用单独的构建智能体和部署智能体，您希望在它们之间传递单个文件。

uip agent pack ./invoice-agent -d ./dist
# → ./dist/invoice-agent.uis

publish运行其自己的内部包管道，因此，对于直接的“构建和部署”流程，您可以完全跳过此步骤，并将项目目录直接传递给publish 。

5. 发布到 Orchestrator

uip agent publish打包项目，将其迁移到预期storageVersion ，生成解决方案.zip ，并将其上传到租户的解决方案订阅源。需要uip login 。

uip agent publish ./invoice-agent --package-version 1.0.0

输出:

{
  "Code": "AgentPublish",
  "Data": {
    "Status": "Published successfully",
    "Name": "invoice-agent",
    "Version": "1.0.0",
    "PackageVersionKey": "a1b2c3d4-0000-0000-0000-000000000050"
  }
}

PackageVersionKey使用deploy 。在脚本中捕获该数据集：

PVK=$(uip agent publish ./invoice-agent \
  --package-version 1.0.0 \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

何时使用--direct

默认情况下， publish通过 Solutions API 上传。--direct标志会绕过解决方案，并将每个.nupkg直接上传到 Orchestrator 的包订阅源，从而为每个包创建一个Release 。此功能适用于以下情况：

• 由于平台原因，解决方案部署路径发生故障，您需要解除限制。
• 您希望立即在特定文件夹中创建版本（传递--folder-id ）。

在--direct模式下，响应没有PackageVersionKey ；等效的是Releases[]中基于版本的Key ，可直接与uip agent run start一起使用。

6. 部署

uip agent deploy在 Orchestrator 文件夹中安装并激活已发布的包。它驱动完整的解决方案部署管道（配置→部署→安装→配置→激活），并轮询每个阶段到终端。

uip agent deploy "$PVK" --name invoice-agent

如果没有--folder-key ，部署将自动创建一个文件夹（以--name命名），并且：

1. 将租户级别的无服务器计算机模板分配给文件夹。
2. 向可分配用户授予文件夹的Automation User角色。

配置失败显示为警告，部署仍会成功；之后手动分配计算机和用户。

要部署到现有文件夹中，请执行以下操作：

uip agent deploy "$PVK" --folder-key <folder-guid> --name invoice-agent

查找包含uip or folders list --all文件夹密钥。

仅安装和强制激活

• --skip-activate安装后停止；如果要在将智能体发布到流量之前查看 Orchestrator 中的部署，此指南非常有用稍后调用uip solution deploy activate以完成它。
• --force-activate使用相同的配置密钥在现有部署上重新激活。用于将正在运行的部署替换为新版本，而无需先卸载。

超时行为

--timeout （默认为120秒）限制每个轮询阶段。超时时， deploy退出2 — Orchestrator 仍可能在后台完成部署；使用更长的超时时间重新运行，或在 Orchestrator 用户界面中检查状态。2的退出代码“ deploy是指特定于域的身份验证错误槽重用，类似于uip tm wait — 请参阅deploy退出代码。

与解决方案部署对比

智能体可以与其他项目（工作流、测试用例）一起在.uipx解决方案中发布，但对于单智能体项目，直接路径更短、更简单：

单个智能体	多项目解决方案
uip agent publish ./my-agent --package-version 1.0.0	uip solution pack ./my-solution ./dist --version 1.0.0
uip agent deploy <PackageVersionKey>	uip solution publish ./dist/my-solution.1.0.0.zip Then uip solution deploy run …
已自动创建并配置文件夹	每--folder-name创建的文件夹；通过deploy config配置
一个.uis工件	一个.zip包含多个.nupkg

当智能体是独立单元时，选择智能体路径；当您需要将智能体与共享资源的 RPA 工作流、库或测试用例一起交付时，请选择“解决方案路径”。请参阅uip solution 。

完整的管道就绪脚本

#!/usr/bin/env bash
set -euo pipefail

AGENT_DIR="./invoice-agent"
VERSION="${AGENT_VERSION:-1.0.0}"

# 1. Auth (External App in CI)
uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

# 2. Validate locally — fail fast before uploading
uip agent validate "$AGENT_DIR"

# 3. Publish
PVK=$(uip agent publish "$AGENT_DIR" \
  --package-version "$VERSION" \
  --output-filter "Data.PackageVersionKey" \
  --output plain)

# 4. Deploy
uip agent deploy "$PVK" \
  --name "invoice-agent-${ENVIRONMENT}" \
  --timeout 300

然后，使用uip agent run start开始作业，或使用评估运行uip agent eval run start ，根据评估集验证行为，之后部署才会被视为绿色。

另请参阅

• uip agent概述— 智能体工具中的每个动词。
• uip solution概述— 基于解决方案的部署，适用于多项目项目。
• uip or jobs — 智能体运行的基础作业模型。
• 身份验证— 会话、租户和env.前缀。
• 操作方法：从 CI 部署到 Orchestrator — CI 特定的身份验证、缓存、版本固定。