---
title: Register an agent
description: Register an agent in the web app so your SDK integration has
  somewhere to report.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

Your SDK integration reports every run against an [agent](/platform/concepts/agent), so the agent has to exist in Prefactor first. Register it yourself when you want to choose its name, risk profile, team, and owner up front.

By the end you'll have a new agent with its own Agent page, ready for the token your integration will use.

## Before you start

- You have the **Full access** role on the account. Read-only users still see **Register agent**, but Prefactor refuses the change with an error.
- Anything you want to assign already exists: a [risk profile](/platform/concepts/risk-profile) to score the agent's runs, a team from the [Teams page](/web-app/teams), and an owner from the [People page](/web-app/people). All three are optional, and you can set them later from **Edit** on the Agent page.

## Register the agent

1. Go to **Agents** and select **Register agent** at the top right.

   The **Register agent** dialog opens.

   ![The Register agent dialog with Name and Description (optional) filled in, and a risk profile, team and owner chosen.](../../../assets/screenshots/guides/register-agent-dialog.png)

2. Enter a **Name**.

   This is how the agent appears on the [Agents page](/web-app/agents), on Home, and in alerts. Use something a teammate will recognise, such as the product or workflow it serves.

3. Optionally, fill in **Description (optional)** with what the agent does.

   The description shows on the agent's card and on its Agent page.

4. Choose a **Risk profile**, **Team**, and **Owner**, or leave any of them at **None (not assigned)**.

   Without a risk profile, the agent's runs aren't scored for risk. If you opened the dialog from a team's agent list, **Team** starts on that team.

5. Select **Register agent**.

   Prefactor confirms with "Agent registered successfully" and opens the new [Agent page](/web-app/agent). The agent's status is **Pending** until its first run arrives. Until then, the Overview tab shows **Nothing set up yet** with a **Setup agent** button, which opens a setup prompt you can paste into your coding tool.

## Connect your integration

6. Create a token for the agent on its **Deployments** tab.

   A deployment token belongs to this agent and one environment, so your integration doesn't need the agent ID. [Create a deployment token](/guides/create-a-deployment-token) walks through it.

7. Run your agent with the token set as `PREFACTOR_API_TOKEN`.

   See [Configuration and environment variables](/sdks/configuration) for the other settings.

## Verify

Open the agent's Agent page again after your agent has run once. Its status has changed from **Pending** to **Active**, and the run is listed on the [History tab](/web-app/agent/history).

## If it didn't work

- **Prefactor shows an error when you select Register agent.** Your role is Read only. Ask a Full access user to register the agent or to change your role on the [Account › Admin users tab](/web-app/account/admin-users).
- **The Risk profile, Team, or Owner list has nothing to choose.** None exist in the account yet. Register the agent without it, create the profile, team, or person, then assign it from **Edit** on the Agent page.
- **The status stays Pending after your agent ran.** The run was recorded against a different agent. Check that the token your integration uses is listed on this agent's [Deployments tab](/web-app/agent/deployments), or, with an account-wide token, that `PREFACTOR_AGENT_ID` is this agent's ID.

## Other ways to do this

To register an agent from a script or CI, call [POST /api/v1/agent](/api/platform/operations/actionagentcreate).

## Related

- [Agent](/platform/concepts/agent) — what an agent is and how its status changes.
- [Agents page](/web-app/agents) — every agent in the account and the **Register agent** dialog.
- [Agent page](/web-app/agent) — what the page shows above the tabs, including **Edit**.
- [Create a deployment token](/guides/create-a-deployment-token) — the next step for a new agent.
- [Assign a risk profile](/guides/assign-a-risk-profile) — score the agent's runs if you skipped it here.
- [Organise agents by team](/guides/organise-agents-by-team) — group agents and give them owners.