Skip to main content

Setup

1. Install​

The package ships a uigraph-agents binary. Run it without installing:

npx @uigraph/agents impact --help

Or install it globally:

npm i -g @uigraph/agents
uigraph-agents --help

In CI, prefer pinning a version rather than tracking latest. Either way, the machine running the agent needs internet access.

2. Configure a model​

The agent needs an AI model. The quickest path is environment variables:

export AI_PROVIDER_MODEL="gpt-4o"
export AI_PROVIDER_API_KEY="sk-…"
export AI_PROVIDER_API_URL="https://api.openai.com/v1"

By default the agent talks to any OpenAI-compatible endpoint, which is why AI_PROVIDER_API_URL is set above. To use a provider package directly instead, set AI_PROVIDER_NPM:

export AI_PROVIDER_NPM="@ai-sdk/anthropic"
export AI_PROVIDER_MODEL="claude-sonnet-5"
export AI_PROVIDER_API_KEY="sk-ant-…"

The provider list, model examples, and optional tuning settings are on the shared AI Providers page.

3. Check your .uigraph.yaml​

The agent reads .uigraph.yaml from the repository root and will not run without it.

If the repository is not onboarded yet, start with UIGraph CLI, or let the UIGraph skill generate the artifacts for you.

Point at a different path with --uigraphConfig when the file is not at the root.

4. Connect UIGraph MCP​

This step is what separates the impact agent from the artifacts agent. It reasons over your architecture graph, not just your repository, so it needs a live connection to UIGraph MCP and will not start without one.

On a self-hosted MCP server, two values are enough:

export UIGRAPH_MCP_URL="https://mcp.your-org.com"
export UIGRAPH_TOKEN="uig_…"                       # service-account token

On hosted UIGraph, pass --enterprise instead and the agent resolves the URL itself:

uigraph-agents impact --enterprise

Add DEV to reach the development environment instead, as in --enterprise DEV. --mcpUrl and --enterprise set the same thing, so pass one or the other, not both.

Signing in as a user instead​

By default the agent treats your token as a service account, which is what you want in CI. To sign in as a user instead, set UIGRAPH_MCP_AUTH_TYPE to user — and because a user can belong to several organizations, also tell it which one with UIGRAPH_ORG_ID.

5. Run it​

Analyse everything on your branch since it diverged from the default branch:

uigraph-agents impact --target "$(git merge-base origin/main HEAD)"

The report goes to your terminal unless you pass --report <path>. Add --verbose to watch what the agent is doing — the quickest way to confirm the UIGraph connection is healthy.

Without --artifacts the agent writes no files, so it is safe to point at any repository.

6. Optional: a config file​

Anything you would pass as a flag can live in uigraph-agents.json at the repository root instead:

{
  "model": "gpt-4o",
  "apiUrl": "https://api.openai.com/v1",
  "apiKeyEnv": "OPENAI_API_KEY",
  "agents": {
    "impact": {
      "mcp": { "url": "https://mcp.uigraph.app" }
    }
  }
}

Never commit an API key or an access token. Use apiKeyEnv to name the environment variable holding the model key, and leave mcp.accessToken to UIGRAPH_TOKEN.

See Configuration for the settings you can put there, and how the file, environment variables, and flags override one another.

7. Point the agent at your UIGraph API​

Every run is recorded in UIGraph, so you can look back at what the agent did and what it cost. This is separate from the MCP connection in step 4, so it needs its own URL:

export UIGRAPH_API_URL="https://uigraph.your-org.com"
export UIGRAPH_TOKEN="uig_…"                       # the same token as step 4

--enterprise covers this URL as well as the MCP one, so on hosted UIGraph the token is all you set.

Both are required. Without them the run stops before the model is called. If your token can see more than one organization, name the one to record into with UIGRAPH_ORG_ID or UIGRAPH_ORG_NAME.

Once a run is recorded, a step that fails to reach UIGraph is reported and the run carries on.

Next steps​