Skip to main content

Setup

1. Install​

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

npx @uigraph/agents artifacts init --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. Generate your first artifacts​

If the repository has no .uigraph.yaml yet, init creates one along with the artifacts under .uigraph/:

uigraph-agents artifacts init --verbose

--verbose shows what the agent looked at as it works. Like every command, init needs a UIGraph token. See step 6.

Already have a minimal config holding your service name, repository, and owning team? Keep those values as written with --seeded:

uigraph-agents artifacts init --seeded

Check what it produced before you commit it:

uigraph-cli sync --dry-run

If the dry run reports errors, pass its output straight back:

uigraph-agents artifacts fix "$(uigraph-cli sync --dry-run 2>&1)"

The UIGraph skill is the alternative to init when you would rather drive onboarding from your own coding agent.

4. Keep it up to date​

From then on, sync is the command you run. Compare the working tree against the previous commit and report drift without writing anything:

uigraph-agents artifacts sync --previous commit --dryRun --verbose

Read a few dry-run reports before you let it write. Drop --dryRun to apply the updates:

uigraph-agents artifacts sync --previous commit

Changed files are printed as write: <path> or edit: <path>, and the report goes to stdout unless you pass --report.

sync and fix read .uigraph.yaml from the repository root and will not run without it. That file is the list of artifacts they check, and the only files they are allowed to edit. Point at a different path with --uigraphConfig when the file is not at the root.

Every command needs version: 1 in the file. init writes it for you. Keep it in place when you edit the config by hand.

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

Never commit an API key. Use apiKeyEnv to name the environment variable holding it, as above.

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

6. Connect the agent to UIGraph​

Every run is recorded in UIGraph, so you can look back at what the agent did and what it cost. On self-hosted UIGraph, set both:

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

On hosted UIGraph, pass --enterprise instead and the agent resolves the URL itself, so only the token is left to set:

export UIGRAPH_TOKEN="uig_…"

uigraph-agents artifacts sync --enterprise

Add DEV to reach the development environment instead, as in --enterprise DEV.

A URL and a token are required either way. 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​