Configuration

You can configure the artifacts 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.artifacts 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": {
    "artifacts": {
      "model": "claude-sonnet-5",
      "npm": "@ai-sdk/anthropic",
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    }
  }
}

The same file can carry an agents.impact block for the impact 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.

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. UIGRAPH_API_URL and UIGRAPH_TOKEN are required for every command, init included, and 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.
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_API_URL when you use hosted UIGraph, or --enterprise DEV for the development environment. The flag only sets the URL, so UIGRAPH_TOKEN is still required.

The artifacts agent works entirely from your repository, so it has no UIGraph connection settings beyond these.

Authoring rules (optional)

The agent follows a published set of UIGraph authoring rules, pinned to one fixed version so a run stays reproducible.

Variable	Required	Description
UIGRAPH_SKILL_REF	No	Pin the authoring rules to a different version. Must be a full 40-character commit SHA from the UIGraph skill repository.

Leave this unset unless you have been asked to test a specific version. Anything that is not a full commit SHA is rejected.

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 — house conventions the agent should follow.

What to check

Key	Type	Default	Description
uigraphConfig	string	.uigraph.yaml	Where your UIGraph config lives. This is also what decides which artifacts the agent may edit.
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" }.

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, so it beats both the file and UIGRAPH_API_URL.

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 — edits only ever go to your declared artifacts.

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.