UIGraph Agents

@uigraph/agents is a small CLI of self-contained AI agents you run inside a repository. Where UIGraph CLI syncs what is already in .uigraph.yaml, the agents look at your code and tell you when those artifacts have fallen behind it.

There are two, and the artifacts agent has three commands:

Agent	Command	What it does	Writes files?
Artifacts	uigraph-agents artifacts init	Inspects the whole repository and generates your first .uigraph.yaml and artifacts.	Yes
Artifacts	uigraph-agents artifacts sync	Finds where your code and your artifacts no longer match, and updates the artifacts.	Yes
Artifacts	uigraph-agents artifacts fix "<context>"	Repairs exactly what a chunk of text says is wrong, such as a failed dry run.	Yes
Impact	uigraph-agents impact	Analyses a range of commits and reports how the change affects your services and artifacts.	Only with --artifacts

uigraph-agents artifacts on its own prints its help and stops. Pick a command.

Both agents read the same .uigraph.yaml the CLI syncs, so the three tools describe one shared picture of your repository.

How the pieces fit together

a new repository                      your code changes
   ↓                                     ↓
uigraph-agents artifacts init         uigraph-agents artifacts sync
   ↓                                     ↓
      both write .uigraph.yaml and .uigraph/**
   ↓
uigraph-cli sync           →  pushes those artifacts to UIGraph
   ↓
uigraph-agents impact      →  reads UIGraph via MCP, reports the blast radius

The artifacts commands run before sync, because they produce the files sync uploads. impact runs against data already in UIGraph, so it reaches your instance through UIGraph MCP.

Which one do you want?

• Onboard a new repository. Use artifacts init once. It reads the whole repository and writes your first config and artifacts. See Setup.
• Keep docs and diagrams honest. Use artifacts sync, on every push. It notices that you added an endpoint, changed a schema, or introduced a dependency, and edits the corresponding artifact. See Artifacts agent.
• Clear an error the CLI reported. Use artifacts fix, passing the text of the failure. See Repairing a failed run.
• Review a change before shipping it. Use impact, in a pull request. It answers "what does this touch?" using your real architecture graph rather than the diff alone. See Impact agent.

Running both agents is the common case. Put artifacts sync in a push job that commits its updates, and impact in a PR job that comments the report. Each agent's own CI/CD page has a working workflow.

What you need

• Node.js and a way to run the package (npx, or a global install).
• An AI model provider, any supported provider, configured through AI_PROVIDER_*.
• A .uigraph.yaml in the repository for artifacts sync, artifacts fix, and impact. They have no artifacts to reason about without one. artifacts init is the command that creates it, so it is the exception.
• A reachable UIGraph API in UIGRAPH_API_URL and an access token in UIGRAPH_TOKEN. Every run of either agent is recorded in UIGraph as an agent session, so every command needs them.
• For impact only: a reachable UIGraph MCP server as well, in UIGRAPH_MCP_URL. The same token covers both.

On hosted UIGraph, pass --enterprise and both agents resolve those URLs themselves, so UIGRAPH_TOKEN is the only variable left to set. Add DEV to reach the development environment instead.

What they can and cannot touch

Worth knowing before you point an agent at a repository:

• The artifacts agent only touches your documentation. It can write the artifacts listed in .uigraph.yaml, plus the config file itself, and nothing else. Your source code is off limits.
• impact reads and reports. It writes nothing unless you add --artifacts, which lets it update the artifacts the change made wrong.
• Neither agent can change anything by running a command. While they investigate, they can only run read-only commands like git log.
• --dryRun lets artifacts sync tell you what it would change without changing it.

Next steps

Each agent is documented on its own, from install through to a CI workflow — pick the one you need:

• Artifacts agent — Setup, Configuration, CI/CD.
• Impact agent — Setup, Configuration, CI/CD.

Both are installed the same way, from the same @uigraph/agents package, so if you are running both you only need to do the install and model setup once.