Como fazer: implantar um Agente da UiPath

Estruture, atualize, valide e envie um agente da UiPath de pouco código para o Orchestrator usando as ferramentas "agente uip" e "solução uip".

Esta página orienta o ciclo de vida completo de um agente da UiPath de pouco código a partir da CLI: estruturar-lo no disco, mantê-lo sincronizado, validá-lo, revisá-lo e enviá-lo ao Orchestrator usando uip solution. Ele usa a ferramenta uip agent , que é distinta do uip codedagent (agentes codificados baseados em Python).

uip agent não tem um comando pack, publish ou deploy próprio — um projeto de agente é sempre enviado como parte de uma solução. uip agent init lida com isso automaticamente: ele registra automaticamente o novo projeto no .uipx de uma solução circundada, ou estrutura um <Name>Solution pai quando executado fora de um.

O ciclo de vida

init → refresh → validate → review → (uip solution) pack → publish/upload → deploy

Texto	Entrada	Saída	Logon Obrigatório
agent init	diretório de destino	árvore de projeto de agente, registrada em uma solução	Não
agent refresh	diretório do projeto	arquivos migrados + entry-points.json/bindings_v2.jsonregenerados	Não
agent validate	diretório do projeto	aprovado/reprovado — não grava nada	Não
agent review	diretório do projeto	pontuação, classificação, problemas	Não
solution pack	diretório da solução	.zip Pacote	Não
solution publish / solution upload	.zip compactado ou diretório de solução	versão do pacote publicada/solução do Studio Web	Sim
solution deploy run	pacote publicado	pasta implantada + versão	Sim

Verbos locais (agent init, agent refresh, agent validate, agent review, solution pack) não exigem uma sessão ativa. Tudo o que conversa com o Studio Web ou o 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-5.4 \
  --system-prompt "You are an invoice triage agent."

Execute de dentro de um diretório de solução existente para registrar o projeto nele ou execute-o de forma independente — um pai InvoiceAgentSolution/ é estruturado automaticamente e o projeto é aninhado dentro dele. Transmita --skip-solution-registration para recusar ambos os comportamentos.

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 — ele gera uma subpasta nomeada por UUID contendo apenas agent.json e flow-layout.json, sem registro automático da solução. Veja init --inline-in-flow.

2. Recursos do autor

Não há verbo de CLI dedicado para adicionar ferramentas, contextos, escalonamentos ou entradas de esquema de E/S — crie-os editando manualmente agent.json diretamente (e, para recursos de ferramentas baseadas em arquivos, resources/<name>/resource.json). uip agent tool list e uip agent memory são auxiliares de leitura/anexação, não editores gerais de recursos:

# See what tools are already configured
uip agent tool list --path ./invoice-agent

# Attach a memory space for retrieval-augmented recall
uip agent memory add InvoiceHistory \
  --memory-space invoice-recall --folder-path Shared --path ./invoice-agent

# Check available guardrails before wiring one into agent.json
uip agent guardrails list

Após qualquer edição manual em agent.json, passe para a etapa 3 — a atualização regenera os arquivos derivados dos quais essas edições dependem.

3. Atualizar e validar

Execute uip agent refresh após cada edição em agent.json: ele aplica migrações de esquema pendentes e regenera entry-points.json / bindings_v2.json. Esse é o único comando no ciclo de vida que grava arquivos.

uip agent refresh ./invoice-agent

Em seguida, execute uip agent validate — restrito e somente leitura — ele responderá "O Studio Web aceitaria este diretório como está?" sem escrever nada:

uip agent validate ./invoice-agent

Ambos são somente locais (sem necessidade de login). Execute refresh e então validate no CI como uma porta antes do empacotamento; juntos, eles capturam a classe de erros (modelo inválido, messages[].contentTokens quebrado, entradas required ausentes em esquemas, arquivos derivados obsoletos) que, de outra forma, apareceriam muito mais tarde como uma falha de upload opaca.

4. Revisão

uip agent review executa um conjunto de regras determinísticas para um veredicto de qualidade pontuado — distinto da aprovação/falha estrutural do validar:

uip agent review ./invoice-agent

Opcionalmente, registre a nota para rastreamento ao longo do tempo com uip agent review-history add:

uip agent review-history add A --path ./invoice-agent

5. Debug (opcional)

Antes do envio, execute o agente uma vez no Studio Web com entradas de amostra usando uip agent debug (requer login e um manifesto project.uiproj ):

uip agent debug ./invoice-agent -i '{"invoicePath":"/tmp/sample.pdf"}'

6. Enviar com solução uip

Um projeto de agente é enviado como parte da solução na qual foi registrado na etapa 1. Empacote e publique (ou carregue, para o Studio Web) exatamente como faria com qualquer outra solução:

# Pack the solution containing the agent project
uip solution pack ./InvoiceAgentSolution ./dist --version 1.0.0

# Publish the packed .zip to a tenant feed
uip solution publish ./dist/InvoiceAgentSolution_1.0.0.zip

Em seguida, implante em uma pasta do Orchestrator:

uip solution deploy run ./dist/InvoiceAgentSolution_1.0.0.zip \
  --folder-name invoice-agent-prod

Reimplantar a mesma solução no mesmo --folder-name não atualiza a implantação existente — deploy run sempre cria uma nova. Use uip solution deploy upgrade com a chave de implantação de uip solution deploy list para mover uma implantação existente para uma nova versão do pacote no local.

Script completo pronto para pipeline

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

AGENT_DIR="./invoice-agent"
SOLUTION_DIR="./InvoiceAgentSolution"
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. Refresh + validate locally - fail fast before packing
uip agent refresh "$AGENT_DIR"
uip agent validate "$AGENT_DIR"

# 3. Pack and publish the solution
uip solution pack "$SOLUTION_DIR" ./dist --version "$VERSION"
uip solution publish "./dist/InvoiceAgentSolution_${VERSION}.zip"

# 4. Deploy (or upgrade an existing deployment - see uip solution deploy upgrade)
uip solution deploy run "./dist/InvoiceAgentSolution_${VERSION}.zip" \
  --folder-name "invoice-agent-${ENVIRONMENT}"

Siga 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.
• uip solution visão geral — empacotamento, publicação e implantação da solução em que um projeto de agente reside.
• 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.