One row per environment
A connected agent registers with a name and an environment. Each pair is its own row on the Agents page and its own target, sosupport-agent in production and support-agent in development are two things you can run the same test suite against.
The agents list groups the rows under the name, so the page reads as one agent with its environments under it. The target label includes the environment: support-agent · production, support-agent · development (Alex).
How the environment is resolved
The SDK reads the first of these that has a value:- The
environmentargument on the decorator. LANGWATCH_AGENT_ENVIRONMENT.APP_ENV, thenENVIRONMENT, thenNODE_ENV.development, when none of the above is set.
production in production and as development on a laptop with no argument at all.
Environment names use lower-case letters, digits, dashes and underscores, up to 32 characters.
Personal agents
development makes an agent personal, because a developer machine is one person’s and not the team’s.
The platform refuses a run against a teammate’s personal agent with
agent_owner_only, and the message includes the owner’s name. The rule applies at every door: the run dialog, the CLI, the REST API and the MCP server.
The run dialog shows teammates’ personal agents disabled. The tooltip on the card gives the owner’s name and says only they can run it.
For a development machine the whole team runs suites against, give it its own environment name and it is shared like any other:
The local loop
The process on your machine reaches out to LangWatch, so there is no tunnel, no public URL and no configuration to restore afterwards.- Start your agent with
LANGWATCH_API_KEYset. It appears on the Agents page as Online, underdevelopment. - Run the test suite, from Agent Testing > Scenarios or with
langwatch test-suite run <name> --target connected:support-agent@development --wait. - Read the results, change your code, restart the process, and run again. The agent reconnects under the same row and the run history stays together.
- Stop the process when you are done. The row reads Offline with the time it was last seen.
An HTTP agent that runs on your machine is a different case: the platform calls it, so it needs a reachable URL.
langwatch agent dev covers that, see Other ways to connect.Compare production against your machine
Two targets in one run is a comparison. The results page shows one column per target, each with its own pass rate, duration and cost.staging against production, or one environment against another model:
? and & itself. A value after ? is a run parameter for that target alone.
Every target of the run must be online when the run starts. The platform refuses a run with an offline target before it schedules any scenario, with agent_offline.
What each environment costs to keep
A connected process holds one outbound connection and answers a keepalive. It receives work only while a run is executing, so an environment that runs no suites costs one idle connection. The list hides an agent not seen for 30 days. It comes back when the process connects again, with the same row and its history. Deleting an agent also hides it only until the process connects again.Turning the connection off
Turn the connection off for a deployment without a code change:enabled=False on the decorator does the same in code, and the SDK defaults it to false when CI is set, because a CI job is not a service anyone runs suites against. Pass enabled=True when a CI job is deliberately the target.
Next steps
Connect your agent
Decorate the function that runs your agent
Run parameters
Values a run supplies, declared by the scenario or by the agent
Run from CI
Start a test suite from a CI job and wait for the batch
Other ways to connect
HTTP agents, the local tunnel, and code agents