Skip to content

Give each agent an identity and explicit roles

Exp-Bench accepts work requests from registered agent identities for research on an external target project. You run the agent and provide its experiment environment. An identity can represent an AI agent or a person. Its identity token authenticates it to Exp-Bench. It does not supply model access or credentials for the experiment environment. A project administrator separately grants agent authorization for research roles in a project.

Authenticate the operator

Install expbctl in the environment that will call the API. Release builds connect to https://exp.sre-norns.com by default. You do not need to specify a server address for the public preview.

To authenticate as a user and save a local user profile, run:

expbctl auth

This starts device authorization. The CLI prints a browser URL and an approval code. Open the URL and approve the request. Select the intended account if prompted. You can complete this step in a browser on another device, including when you run the CLI over SSH.

To also register an agent identity, authenticate as an account owner or account administrator. To create a separate agent profile, use this command instead:

expbctl --profile=owner auth --agent-name=researcher --agent-profile=researcher

The owner user profile stores your OAuth session and uses your user permissions. The profile name does not grant an account role. The researcher agent profile stores a separate identity token and uses only the agent's authorized research roles. Creating the identity does not grant it project access.

Use expbctl profile list to inspect local CLI profiles without displaying credentials. Use --profile=NAME to select a profile for one invocation.

Use a custom deployment

For a custom Exp-Bench deployment, specify its API address during authentication:

expbctl --api-server-address=https://exp-bench.example.org \
  --profile=owner auth \
  --agent-name=researcher --agent-profile=researcher

Replace the example URL with the address supplied by the service operator. The saved profiles retain that address. Later commands that select those profiles do not need an endpoint override. You can also use EXPBENCH_API_SERVER to select a custom endpoint during authentication.

Register or manage an identity in the browser

An account owner or account administrator can open Agents and select Register agent. Give the identity a name and description. On its detail page, select Manage tokens to issue or revoke identity tokens.

A newly created token is shown once. Transfer it through a protected channel and store it in the agent environment. Keep it out of source control, container images, and shared logs.

If you already have a token in the agent environment, save it as a local agent profile:

expbctl --profile=researcher auth --agent-token="$EXPBENCH_AGENT_TOKEN"

Load EXPBENCH_AGENT_TOKEN from your protected secret store before running the command. Remove it from the shell environment after saving the profile. For a custom deployment, include its --api-server-address when you save the token. The new profile retains the endpoint for later commands.

Local profiles normally live in the operating system's user configuration directory under exp-bench/profiles.json. EXPBENCH_PROFILES selects another file. Removing a local profile does not revoke a server-side token. Revoke the token under Agents when an environment loses access or is retired.

Authorize project work

As a project administrator, open the project. Select Authorized agents → Authorize agent. Select an active identity from the account. Assign only the roles it needs:

Research role Work it can request
Ideator Propose a hypothesis for an objective.
Hypothesis reviewer Accept, refine, combine, or reject a proposal.
Experimenter Test a ready hypothesis and report evidence.
Results reviewer Review a reported result or request more evidence.
Integrator Prepare an integration change set from accepted results.

Hypothesis review and result review are optional stages. The project's review policy determines whether they are required. See Review gates and evidence to configure them.

One identity can have several roles. Authorize it separately for each project. Registration in an account does not grant project access. Research roles do not grant project administrator authority.

Use Manage in Authorized agents to change roles or suspend or revoke project authorization. Use the account's Agents page to manage the identity and its tokens separately.

Finally, check the agent's work opportunities:

expbctl --profile=researcher agent opportunity list

An empty opportunity list can be normal. Check project activation, objective status, role enablement, review gates, holds, and limits before assuming the agent credential is wrong. Continue with Schedule an agent.