Como fazer: implantar um Agente da UiPath

Esta página orienta o ciclo de vida completo de um agente da UiPath de pouco código a partir da CLI: estruturar-o no disco, validar, empacotar, publicar e implantá-lo no Orchestrator — pronto para ser executado como um trabalho. Ele usa a ferramenta uip agent , que é distinta do uip codedagent (agentes codificados baseados em Python).

Se você já estiver confortável com a implantação do uip solution , a principal coisa a saber é que os Agentes podem implantar sem um wrapper da solução. O comando uip agent publish executa seu próprio pacote → migrar → pacote de solução → fazer upload do pipeline internamente e uip agent deploy instala o resultado diretamente. Você nunca precisa criar um manifesto de solução .uipx para um projeto de agente único.

O ciclo de vida

init → validate → pack → publish → deploy → run

Cada verbo produz o que o próximo consome:

Texto	Entrada	Saída	Logon Obrigatório
init	diretório de destino	agent.json + árvore do projeto	Não
validate	diretório do projeto	arquivos migrados no disco	Não
pack	diretório do projeto	.uis Arquivar	Não
publish	diretório do projeto ou .uis	PackageVersionKey No Orchestrator	Sim
deploy	PackageVersionKey	pasta implantada + versão	Sim

Verbos locais (init, validate, pack) não exigem uma sessão ativa e podem ser executados em qualquer estágio de compilação. Tudo o que grava no Orchestrator precisa de uip login primeiro.

1. Estrutura

Crie um novo projeto de agente com uip agent init:

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

Isso escreve uma árvore de projeto independente completa:

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/

O nome do diretório se torna o nome do agente; ele deve corresponder a [a-zA-Z0-9_ -]+. Transmita --force para substituir um diretório não vazio.

Para agentes que residem dentro de um fluxo do Maestro, use --inline-in-flow em vez disso — ele gera uma subpasta nomeada por UUID contendo apenas agent.json e flow-layout.json. Veja init --inline-in-flow.

2. Recursos do autor

Um agente real geralmente precisa de três tipos de recursos. Edite agent.json diretamente ou use os comandos de edição estruturados:

• Entradas e saídas — uip agent input add / uip agent output add para parâmetros de esquema.
• Ferramentas — uip agent tool add para conectores do Integration Service, processos do Orchestrator, outros agentes, fluxos de trabalho de API, fluxos do Process Orchestration e habilidades de IXP.
• Contextos — uip agent context add para associações de índice de RAG.
• Escalonamentos — uip agent escalation add para entregas com intervenção humana.

# 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

Consulte as respectivas páginas de referência para o conjunto de sinalizadores completo. Cada edição mantém agent.json e entry-points.json sincronizados.

3. Validar

Após qualquer edição manual em agent.json — ou após uma série de edições estruturadas — execute uip agent validate:

uip agent validate ./invoice-agent

Validar é somente local (sem necessidade de logon) e executa uma aprovação de verificação estática mais o pipeline de migração de esquema. Em caso de sucesso, os conteúdos do arquivo migrado são gravados de volta no disco e o esqueleto de .agent-builder/ é regenerado. Em caso de falha, você obtém uma lista de erros com caminhos de arquivo e código de saída 1 — nada é escrito.

Execute isso no CI como um gateway antes da etapa de publicação; ele captura a classe de erros (modelo inválido, messages[].contentTokens, entradas required ausentes em esquemas) que, de outra forma, falhariam na publicação lenta.

4. Empacotar (opcional)

uip agent pack agrupa o projeto em um arquivo .uis . Você só precisa disso se:

• Você deseja um artefato para inspecionar manualmente ou arquivar.
• Você planeja enviar por push para o Studio Web com uip agent push para edição interativa.
• Seu pipeline usa um agente de compilação separado e um agente de implantação separados, e você deseja passar um único arquivo entre eles.

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

publish seu próprio pipeline de pacote interno; portanto, para um fluxo direto de "criação e implantação", você pode ignorar essa etapa totalmente e passar o diretório do projeto para publish diretamente.

5. Publique no Orchestrator

uip agent publish empacota o projeto, migra-o para o esperado storageVersion, produz uma solução .zip e a carrega para o feed de solução do tenant. Requer uip login.

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

Saída:

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

O PackageVersionKey é o que deploy consome. Capture-o nos scripts:

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

Quando usar --direct

Por padrão, publish é carregado por meio da API de Soluções. O sinalizador --direct ignora Soluções e carrega cada .nupkg diretamente no feed de pacote do Orchestrator, criando um Release por pacote. Use isso quando:

• O caminho de implantação de Soluções está falhando por um motivo de plataforma e você precisa desbloquear.
• Você deseja que uma versão seja criada imediatamente em uma pasta específica (passa --folder-id).

No modo --direct a resposta não tem PackageVersionKey; o equivalente é o Key por versão em Releases[], que é diretamente utilizável com uip agent run start.

6. Implantar

uip agent deploy instala e ativa o pacote publicado em uma pasta do Orchestrator. Ele direciona o pipeline de implantação de Soluções completo (configurar → implantar → instalar → provisionar → ativar) e pesquisa cada fase no terminal.

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

Sem --folder-key, a implantação cria automaticamente uma pasta (nomeada por --name) e também:

1. Atribui um modelo de máquina sem servidor no nível do tenant à pasta.
2. Concede a um usuário atribuível a função Automation User na pasta.

As falhas de provisionamento aparecem como avisos — a implantação ainda é bem-sucedida; atribua a máquina e o usuário manualmente posteriormente.

Para implantar em uma pasta existente:

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

Localizar chaves de pasta com uip or folders list --all.

Somente instalar e forçar ativação

• --skip-activate interrompida após a instalação; útil se você quiser revisar a implantação no Orchestrator antes de lançar o agente para o tráfego. Chame uip solution deploy activate mais tarde para concluí-la.
• --force-activate reativa em uma implantação existente na mesma chave de configuração. Use isso para substituir uma implantação em execução por uma nova versão sem desinstalar primeiro.

Comportamento do tempo limite

--timeout (padrão: 120 segundos) limita cada fase de pesquisa. No tempo limite, deploy sai 2 — o Orchestrator ainda pode concluir a implantação em segundo plano; execute novamente com um tempo limite mais longo ou verifique o status na interface gráfica do Orchestrator. O código de saída 2 em deploy é uma reutilização específica do domínio do slot de erro de autenticação, análogo a uip tm wait — consulte os códigos de saídadeploy .

Comparar com implantação da Solução

Os agentes podem enviar dentro de uma Solução .uipx ao lado de outros projetos (fluxos de trabalho, casos de teste), mas para um projeto de agente único o caminho direto é mais curto e mais simples:

Agente único	Solução de vários projetos
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 …
Pasta criada automaticamente + provisionado	Pasta criada por --folder-name; provisionando via deploy config
Um artefato .uis	Um .zip contendo vários .nupkg

Escolha o caminho do agente quando ele for uma unidade independente; escolha o caminho da solução quando precisar enviar um agente junto com fluxos de trabalho de RPA, bibliotecas ou casos de teste que compartilham recursos. Consulte uip solution.

Script completo pronto para pipeline

#!/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

Siga com uip agent run start para iniciar um trabalho ou com uma execução de avaliação — uip agent eval run start — para validar o comportamento em relação a um conjunto de avaliação antes que a implantação seja considerada verde.

Veja também

• uip agent visão geral — cada verbo na ferramenta do agente.
• Visão geral douip solution — Implantação baseada em solução para projetos de vários projetos.
• uip or jobs — o modelo de trabalho subjacente com o qual os agentes são executados.
• Autenticação — sessões, tenants e o prefixo env. .
• Como fazer: implantar no Orchestrator a partir do CI — autenticação específica do CI, cache, atribuição de versão.