Configuration

You can configure the impact agent three ways, and they stack. A CLI flag beats an environment variable, which beats the config file. That order is what decides the outcome when a CI job and a checked-in config disagree.

Config file

The agent looks for these two paths and uses the first one it finds:

1. uigraph-agents.json
2. .github/uigraph-agents.json

Point at a different file with --config <path>. If the file is not valid JSON, the agent stops and tells you — it will not quietly ignore it.

Settings for one agent only

Settings at the top level apply to both agents. Put a setting under agents.impact and it applies to this agent alone, overriding the top level:

{
  "model": "gpt-4o",
  "apiUrl": "https://api.openai.com/v1",
  "apiKeyEnv": "OPENAI_API_KEY",

  "agents": {
    "impact": {
      "model": "claude-sonnet-5",
      "npm": "@ai-sdk/anthropic",
      "apiKeyEnv": "ANTHROPIC_API_KEY",
      "mcp": {
        "url": "https://mcp.uigraph.app"
      }
    }
  }
}

The same file can carry an agents.artifacts block for the artifacts agent; this agent ignores it.

Environment variables

AI model

Variable	Required	Default	Description
AI_PROVIDER_MODEL	Yes	—	The model to use. The agent will not start without one.
AI_PROVIDER_API_KEY	Yes	—	Your provider API key. See apiKeyEnv below for the alternative.
AI_PROVIDER_NPM	No	@ai-sdk/openai-compatible	Provider package.
AI_PROVIDER_API_URL	No*	—	Provider base URL.

* Required when you use the default OpenAI-compatible provider.

UIGraph connection

The impact agent reads your architecture graph from UIGraph, so it will not start without a connection it can reach. See Setup.

Variable	Required	Default	Description
UIGRAPH_MCP_URL	Yes	—	Your UIGraph MCP server. --enterprise fills this in for you.
UIGRAPH_TOKEN	Yes	—	Your access token.
UIGRAPH_MCP_AUTH_TYPE	No	service_account	service_account or user. Use a service account in CI.
UIGRAPH_ORG_ID	No*	—	* Required when you sign in as a user, since a user can belong to several organizations.

Updating artifacts

Variable	Required	Default	Description
UIGRAPH_IMPACT_ARTIFACTS	No	false	Set true to let the agent update the artifacts the change made wrong. Same as --artifacts. Only true or false are accepted.

Recording runs in UIGraph

Every run is recorded in UIGraph as an agent session, so you can look back at what the agent did and what it cost. This is separate from the MCP connection above, so it needs its own URL. A run that cannot create its session stops before the model is called.

Variable	Required	Description
UIGRAPH_API_URL	Yes	Base URL of your UIGraph API. --enterprise fills this in for you.
UIGRAPH_TOKEN	Yes	Service-account token (uig_…) or a user token. The same token as above.
UIGRAPH_ORG_ID	No*	Organization the run belongs to.
UIGRAPH_ORG_NAME	No*	Organization name, used when you have no id.

* A service-account token already belongs to one organization, so you can leave both unset. Set one of them when you use a user token that can see more than one organization, otherwise the run cannot tell which one to record into.

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

Pass --enterprise instead of setting UIGRAPH_MCP_URL and UIGRAPH_API_URL when you use hosted UIGraph, or --enterprise DEV for the development environment. The flag only sets those URLs, so UIGRAPH_TOKEN is still required.

Config file settings

Model and provider

Key	Type	Default	Description
model	string	—	Required. The model to use.
npm	string	@ai-sdk/openai-compatible	Provider package.
apiUrl	string	—	Provider base URL.
apiKey	string	—	Your provider API key. Prefer apiKeyEnv so no secret is committed.
apiKeyEnv	string | string[]	—	Name of the environment variable holding the key. Give several and the first one that is set wins.

Behaviour

Key	Type	Description
temperature	number 0–1	How much the model varies its answers. Lower is more predictable.
timeout	integer	How long to wait on the model before giving up, in milliseconds.
steps	integer 5 to 2000	How many steps one run may take before it stops. Defaults to 1000. Raise it for large changes, lower it to cap the cost of a run.
instructions	string	Extra instructions for the run — what you want the report to focus on.

What to analyse

Key	Type	Default	Description
uigraphConfig	string	.uigraph.yaml	Where your UIGraph config lives.
target	object	—	What to compare against, if you would rather set it here than pass --target or --previous each time. One of { "commit": "…" }, { "tag": "…" }, or { "previous": "commit" }.

UIGraph connection

Key	Type	Default	Description
mcp.url	string	—	Required. Your UIGraph MCP server.
mcp.accessToken	string	—	Required. Your access token. Prefer leaving this to UIGRAPH_TOKEN so no token is committed.
mcp.authType	service_account | user	service_account	How to sign in.
mcp.orgId	string	—	Which organization, when signing in as a user.

--enterprise writes mcp.url, so it beats both the file and UIGRAPH_MCP_URL.

Recording runs

The session object holds the same four values as the UIGRAPH_* variables above — url, apiKey, orgId, and orgName — for when you would rather keep them in the file than in the environment. Never commit a token.

--enterprise writes session.url as well, so it beats both the file and UIGRAPH_API_URL.

Updating artifacts

Key	Type	Default	Description
artifacts.enabled	boolean	false	Let the agent update the artifacts the change made wrong. Same as --artifacts.

Commands the agent runs

While it works out what changed, the agent runs read-only commands like git log and git diff. It cannot use them to change a file. With artifacts.enabled off, the agent writes nothing at all.

Key	Type	Default	Description
shell.enabled	boolean	true	Set false to stop the agent running commands at all.
shell.timeout	integer	60000	How long any one command may take, in milliseconds.