Skip to main content

ureport-agent

ureport-agent is a lightweight Node.js process that runs on your machine (or CI server). It connects to UReport over WebSocket, receives heal and rerun jobs, executes them in your local repository, and streams progress and results back.

Requirements​

  • Node.js 18+
  • Git configured with push access to your repository (SSH key or HTTPS credentials) — required for Auto-Heal checkout stage
  • ANTHROPIC_API_KEY environment variable — required if any playbook uses an AI Fix or Agent Delegation stage with Anthropic/Claude CLI
  • The auto-heal plugin must be installed on the UReport server

Download and Install​

  1. Go to My Agent (/agent) in UReport.
  2. Click Download .tar.gz (macOS/Linux) or Download .zip (Windows).
  3. Extract the archive:
tar -xzf ureport-agent.tar.gz
cd ureport-agent

No npm install needed — production dependencies are bundled.

Configuration​

Copy ureport-agent.yml.example to ureport-agent.yml and fill in your values:

# ── Required ──────────────────────────────────────────────────────────────────
ureport_url: https://your-ureport-server
agent_token: YOUR_TOKEN_HERE

# Root workspace — agent stores per-lane repos here
repo_path: /tmp/ureport-agent-workspace

# ── Optional ──────────────────────────────────────────────────────────────────
# Claude model for AI fix and agent delegation (default: claude-sonnet-4-6)
# ai_model: claude-sonnet-4-6

# Max minutes to wait for Claude CLI to finish (default: 30)
# claude_cli_timeout_minutes: 30

Configuration Reference​

FieldRequiredDefaultDescription
ureport_urlYes—Full URL to your UReport server (no trailing slash). HTTP and HTTPS both supported.
agent_tokenYes—Agent token generated from the UReport UI.
repo_pathNo./workspaceRoot directory where the agent clones repositories. One subdirectory per product lane.
ai_modelNoclaude-sonnet-4-6Claude model used for AI Fix (Anthropic provider) and Agent Delegation. Overridden per-playbook if the playbook specifies a model.
claude_cli_timeout_minutesNo30Maximum minutes to wait for a single claude --print invocation to complete.

Environment Variables​

VariableWhen Required
ANTHROPIC_API_KEYAny playbook using Anthropic provider, Claude CLI provider, or Agent Delegation mode
OPENAI_API_KEYAny playbook using OpenAI provider
GEMINI_API_KEYAny playbook using Google Gemini provider

Set these in your shell environment before starting the agent, or use a process manager that injects them.

Token Types​

There are two types of agent tokens, each for a different purpose:

Personal Agent Token​

Generated by any user from the My Agent page (/agent). Used for:

  • Rerun — when you trigger a rerun on a test, the job is sent exclusively to your own agent.
  • Auto-Heal fallback — if no global agent is connected, Auto-Heal falls back to your personal agent.

Each user can have one personal agent token at a time. Regenerating replaces the previous token and disconnects the existing agent.

Global Agent Token​

Generated by admins from the Global Agents tab on the Auto-Heal page. Used for:

  • Auto-Heal — the plugin routes heal jobs to any connected global agent first.

Multiple global tokens can exist simultaneously (e.g. one per CI runner or machine). The plugin picks a connected one at dispatch time.

Generating a Token​

Personal token:

  1. Go to My Agent (/agent).
  2. Click Generate Agent Token.
  3. Give it a name (e.g. My MacBook, CI Runner).
  4. Copy the token — shown only once. Store it in ureport-agent.yml.

Global token (admin only):

  1. Go to Tests → Auto-Heal → Global Agents tab.
  2. Click Generate Token.
  3. Copy and configure on the agent machine.

Running the Agent​

cd ureport-agent
node agent.js

To use a config file at a custom path:

node agent.js /path/to/ureport-agent.yml

On startup, the agent logs its version, server URL, and workspace path:

[agent] ureport-agent v0.2.0
[agent] server:    https://your-ureport-server
[agent] workspace: /tmp/ureport-agent-workspace
[agent] connecting to wss://your-ureport-server/ws/agent
[agent] connected
[agent] registered as: My MacBook

How It Works​

WebSocket Connection​

The agent opens a persistent WebSocket connection to {ureport_url}/ws/agent using its token as a Bearer header. On connect, it sends a hello message with its version. The server registers it and sends back registered.

The agent sends a ping every 30 seconds to keep the connection alive. If the connection drops for any reason, the agent waits 5 seconds and automatically reconnects — no manual restart needed.

Job Dispatch Routing​

Auto-Heal jobs (heal_job):

  1. Plugin looks for a connected global agent on the worker that handled the HTTP request.
  2. If none found locally, broadcasts via cluster IPC — other workers check their connected global agents.
  3. If still no global agent, falls back to the triggering user's own personal agent (same two-step process).
  4. Jobs are never sent to another user's personal agent.

Rerun jobs (rerun_job):

  • Always sent exclusively to the triggering user's personal agent.
  • Global agents never receive rerun jobs.
  • If the user has no connected agent, the rerun signal is created with status no_agent.

Job Execution​

The agent executes one job at a time — a single global flag, not per lane. If a second job arrives while one is running, the agent drops it; the signal stays queued and is dispatched again when the current job finishes. Progress messages are streamed back in real time and visible in the signal detail view.

Workspace Layout​

The agent creates one subdirectory per product lane inside repo_path:

/tmp/ureport-agent-workspace/
  myapp__e2e/          ← workspace for myapp / e2e
  myapp__regression/   ← workspace for myapp / regression
  api__smoke/

On first run for a lane, the repository is cloned from the playbook's Git Remote URL. On subsequent runs, the existing clone is fetched, reset to HEAD, and a new branch is created.

Agent Status in UReport​

The My Agent page (/agent) shows the connection status of your agent:

StatusMeaning
ConnectedAgent is connected and ready to receive jobs
DisconnectedAgent has connected before but is not currently connected
Never ConnectedToken exists but the agent has never connected

Admins see a Global Agents tab (all global tokens and their status) and a User Agents tab (all user-owned agents).

Running as a Service​

To keep the agent running in the background and restart on failure, use a process manager.

pm2:

npm install -g pm2
pm2 start agent.js --name ureport-agent
pm2 save
pm2 startup

systemd (Linux):

[Unit]
Description=ureport-agent
After=network.target

[Service]
WorkingDirectory=/opt/ureport-agent
ExecStart=/usr/bin/node agent.js
Restart=always
Environment=ANTHROPIC_API_KEY=sk-ant-xxx

[Install]
WantedBy=multi-user.target

Troubleshooting​

config not found: ureport-agent.yml Copy ureport-agent.yml.example to ureport-agent.yml and fill in ureport_url and agent_token.

replace PASTE_YOUR_TOKEN_HERE with a real token Generate a token from the UReport My Agent page and paste it into ureport-agent.yml.

Auto-Heal signal stays no_agent No connected agent was available at dispatch time. Either connect a global agent (Admin → Auto-Heal → Global Agents) or connect your personal agent. Global agents are preferred; your own personal agent is used as fallback.

Rerun signal stays no_agent Rerun jobs are sent only to your personal agent. Go to My Agent (/agent), generate a token, and start the agent with it.

ANTHROPIC_API_KEY env var not set Set ANTHROPIC_API_KEY in the shell environment before starting the agent.

checkout.remote is not set in the playbook Add a Git Remote URL to the Checkout stage in the playbook configuration.

PR creation fails with GitHub API 422 The fix branch may already exist remotely from a previous run. Delete the stale branch from GitHub or change the branch prefix in the playbook.

Agent did not call finish() within turn limit Agent Delegation hit the 20-turn limit without completing. Use a more specific prompt, or switch to Guided mode for predictable pipelines.

Next: Administration →