[u9g]

Why

Simulation runs are filtered and grouped by agent_name in the cloud dashboard, but when lk agent simulate spawns the agent locally it sends the throwaway simulation-<random> dispatch name in that field. Every run gets a unique name, so filtering by agent groups nothing. The random name itself is required: the local worker must not collide with the deployed agent's dispatch name.

Depends on livekit/protocol#1793 (already pinned in go.mod at its branch SHA; re-pin once merged).

What

Commit 1: [agent] name in livekit.toml. lk agent create and lk agent config write the agent's name next to its id. The prebuilt-image create path now calls CreateAgent directly because the SDK's RegisterAgent wrapper drops the name from the response.

Commit 2: simulate uses it.

• The run's agent_name is [agent] name from livekit.toml, stable across runs.
• The random local-worker name travels separately as dispatch_agent_name; the spawned worker still registers under it via LIVEKIT_AGENT_NAME_OVERRIDE.
• Simulate refuses to spawn without a livekit.toml that names the agent. Cloud users run lk agent config; self-hosted users add:

  [agent]
  name = "my-agent"

• With --agent-name (already-running agent), jobs dispatch to that name; a livekit.toml in the working directory still supplies the identity when present.

Old runs keep their random names for their 30-day life.

Verification

go build ./cmd/lk, go vet ./cmd/lk, go test ./cmd/lk pass.

[u9g]

Demo of the change: without a livekit.toml naming the agent, simulate refuses to spawn; with [agent] name = "frontdesk", the local worker still registers under a throwaway simulation-* name while the run itself is stored as agent_name = "frontdesk" (shown via --export).

toml-agent-name-fixed.mp4

[u9g]

Follow-up to the demo: the missing-toml error now scans the project's Python/JS source for the literal name the agent registers under (agent_name="..." / agentName: "...") and suggests that instead of a placeholder. With @server.rtc_session(agent_name="frontdesk-bot", ...) in agent.py:

Output

$ lk agent simulate --scenarios scenarios.yaml
Using project [jasons-staging-development-proj]
livekit.toml must name the agent under test so its runs can be grouped in the dashboard: run `lk agent config` for a cloud agent, or add

[agent]
name = "frontdesk-bot"

for a self-hosted one

Falls back to my-agent when no literal is found (for example a name read from a variable or env).

[u9g]

Animated walkthrough of how this PR fits with protocol#1793, agents-private#446 and web#6131: agent_name comes from livekit.toml, and the throwaway local-worker name is sent as dispatch_agent_name.

dispatch-agent-name.mp4

[theomonnom]

Can we really move this to a file called "legacy" etc.

That's super hacky and should be temporary until we have v2

[theomonnom]

lg!