uip agent refresh

Apply pending schema migrations and regenerate derived files with `uip agent refresh`.

uip agent refresh applies pending schema migrations and regenerates the derived files (entry-points.json, bindings_v2.json) from agent.json. It always regenerates these artifacts, even when the storage schema is already at the latest version. Run it after every edit to agent.json, before uip agent validate.

Unlike validate, refresh writes files: it repairs drifted contentTokens, bumps an outdated agent.version, applies the migration pipeline in-memory then writes the migrated files back, regenerates entry-points.json / bindings_v2.json, and — for --inline-in-flow agents — generates resources/<id>/resource.json for any wired Integration Service connector tools and strips this agent's stale embedded config out of the parent .flow file (best-effort; never fails the command).

Synopsis

uip agent refresh [path] [--path <path>] [--bindings-target <path>] [--inline-in-flow]

[path] and --path are mutually exclusive — passing both throws AgentRefreshConflictingPath.

All invocations honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

Arguments

• [path] (optional, default .) — Agent project directory. Cannot be combined with --path.

Options

Flag	Default	Purpose
--path <path>	—	Alternative to the positional [path] argument. Cannot be combined with it.
--bindings-target <path>	<projectDir>/bindings_v2.json; for --inline-in-flow, the immediate parent directory's bindings_v2.json when it contains a .flow file	Path to write/merge agent tool bindings into.
--inline-in-flow	off	Refresh an inline agent inside a flow project. Skips entry-points.json / project.uiproj checks; bindings are merged into the parent flow project's bindings_v2.json.

Examples

# Refresh the current directory after editing agent.json
uip agent refresh

# Refresh a specific standalone project
uip agent refresh ./my-agent

# Refresh an inline agent, merging bindings into the parent flow
uip agent refresh ./my-flow/<uuid> --inline-in-flow

Data shape (--output json)

{
  "Code": "AgentRefresh",
  "Data": {
    "Status": "Refreshed — storage schema migrated to 47.0.0; artifacts regenerated",
    "ProjectDir": "/abs/path/my-agent",
    "Model": "gpt-5.4",
    "StorageVersion": "47.0.0",
    "MigrationApplied": true,
    "Validated": { "agent": true, "resources": 2, "evalSets": 0, "evaluators": 0 },
    "AgentVersionBumped": true,
    "MigratedFiles": 1,
    "ConnectorToolsGenerated": [
      { "nodeId": "n1", "name": "SlackSender", "connectorKey": "uipath-slack", "resourceId": "a1b2c3d4-0000-0000-0000-000000000605" }
    ],
    "DerivedFilesGenerated": true,
    "DerivedFiles": 2,
    "FlowShellified": true,
    "FlowResourceNodesStripped": 1,
    "Warnings": ["..."]
  }
}

Status reads "already at <version>" instead of "migrated to" when no migration was applied. Every field after Validated is optional and present only when that step produced something: AgentVersionBumped only if agent.version itself was bumped; MigratedFiles only when MigrationApplied is true; ConnectorToolsGenerated only for --inline-in-flow runs that generated new connector-tool resource files; FlowShellified/FlowResourceNodesStripped only for --inline-in-flow runs where the parent .flow's embedded config was stripped; Warnings only when non-fatal warnings occurred. InlineInFlow: true is added for --inline-in-flow runs.

Failure uses Code: "AgentRefreshFailed" with the same Data.Errors array shape as uip agent validate.

Related

• uip agent validate — the strict, read-only check to run after refresh.
• uip agent init — scaffolds the project refresh operates on.

See also

• Global options, Exit codes.