feat(cli): add `lk agent session` for headless text-mode agent runs by toubatbrian · Pull Request #857 · livekit/livekit-cli

toubatbrian · 2026-06-03T01:11:53Z

Summary

Adds lk agent session start|say|end — a headless, text-mode way to drive a LiveKit agent (Python or JS) straight from the terminal, with no audio/CGO dependency (it lives under the default tag-free build, not the console audio build).

It uses a three-process model that mirrors the existing lk agent console plumbing:

Ephemeral CLI command (start/say/end) — short-lived, talks to the daemon and exits.
Detached singleton daemon — the lk binary re-exec'd into a hidden daemon mode (gated by an env var, never exposed as a subcommand). It binds a fixed loopback TCP port to enforce a single active session, spawns the agent, and applies text mode.
Agent subprocess — the user's agent, connected over the lk.agent.session protobuf protocol.

The CLI↔daemon control protocol reuses pkg/ipc length-prefixed framing on the same TCP port, disambiguated from agent connections by a 4-byte magic preamble. The headless renderer (session_render.go) prints user turns, agent replies, tool calls/outputs, and handoffs.

Command running / IO example

$ lk agent session start examples/voice_agents/basic_agent.py
Detected Python agent (basic_agent.py in .../examples/voice_agents)
Session started. Use `lk agent session say "..."` to talk, `lk agent session end` to stop.

$ lk agent session say "what's the weather in San Francisco?"

  ● You
    what's the weather in San Francisco?

  ● function_tool: lookup_weather
    ✓ sunny with a temperature of 70 degrees.

  ● Agent
    The weather in San Francisco is sunny with a temperature of 70 degrees. Want to know the forecast for any other city?

$ lk agent session say "thanks, that's all"

  ● You
    thanks, that's all

  ● function_tool: end_call
    ✓ say goodbye to the user

  ● Agent
    Goodbye! Have a great day!

$ lk agent session end
Session ended.

Notes

Singleton enforcement: a second start while a session is live is rejected (a session is already running on 127.0.0.1:<port>).
No CGO/audio: builds in the default tag-free binary; the audio pipeline stays behind the console tag. This drops the temporary //lint:file-ignore U1000 directives that were added while the shared spawn/detect helpers were unused.
TODO(node) / TODO(audio) placeholders mark the follow-up surfaces (JS agent detection, audio mode).

Test plan

go build ./... (default) and CGO_ENABLED=1 go build -tags console ./...
go vet -tags console ./cmd/lk/, gofmt clean
End-to-end start → say (tool call) → say (handoff/end_call) → end against basic_agent.py (see IO example above)
JS agent run (pending TODO(node))

Introduces a three-process model (ephemeral CLI command, detached singleton daemon, agent subprocess) that drives a Python/JS agent over TCP using the lk.agent.session protobuf protocol, with no audio/CGO dependency: - `lk agent session start <file>`: re-execs the lk binary as a detached daemon bound to a fixed loopback port (singleton), which spawns the agent and applies text mode; rejects start if a session already runs. - `lk agent session say "..."`: streams a user turn and renders the agent reply, tool calls/outputs, and handoffs to the terminal. - `lk agent session end`: tears down the daemon and agent. The CLI<->daemon control protocol reuses pkg/ipc length-prefixed framing over the same TCP port, disambiguated from agent connections by a magic preamble. The headless renderer covers all ChatItem variants plus the FunctionToolsExecuted event. Drops the now-unnecessary U1000 file-ignore directives added while the helpers were unused. Co-authored-by: Cursor <cursoragent@cursor.com>

Tools that return no string (e.g. handoff tools returning an Agent) produced a bare "✓ " line. Suppress the output line when the summarized output is empty for successful calls; error outputs still render. Co-authored-by: Cursor <cursoragent@cursor.com>

theomonnom

uh stamped the wrong PR

theomonnom · 2026-06-03T20:51:53Z

+	// When re-exec'd as the detached session daemon, run that and never reach
+	// the CLI framework (the daemon is not an exposed subcommand).
+	if os.Getenv(envSessionDaemon) == "1" {
+		runSessionDaemon()
+		return
+	}
+


Should we create a separate entrypoint instead?

Good call — moved it to a dedicated hidden subcommand entrypoint (lk agent session daemon) instead of the env gate in main().

Done in 5f0ca88 (entrypoint) + 0a32ba0 (guard).

What I mean is can't this be it's own binary?

If no then it's prob OK

Is there a hard reason we need two binaries? One works fine for us today. Re-exec'ing os.Executable() guarantees the daemon is the exact same version as the CLI (no skew), it reuses the console/ipc/detection code directly, and it's a hidden impl detail — nobody installs or runs it on its own. A second binary would also double our release/build matrix. Happy to split it out if there's a concrete need though.

Replace the env-gated branch at the top of main() with a dedicated, hidden `lk agent session daemon` subcommand (mirroring the existing hidden `generate-fish-completion` command). `start` now re-execs the binary into that subcommand instead of setting LK_SESSION_DAEMON=1, so the daemon has its own entrypoint dispatched by the CLI framework rather than special-casing main(). Re-exec of the same binary is retained (a separate binary can't be located reliably after `go install`); runtime params still flow through the LK_SESSION_* env vars. Co-authored-by: Cursor <cursoragent@cursor.com>

A registered subcommand is always invokable (Hidden only drops it from help), so a stray `lk agent session daemon` previously spawned a half-configured daemon (random port, empty project dir) that exited silently. Guard the entrypoint on the inherited readiness pipe that `start` always provides: without it, return a clear error directing the user to `lk agent session start`. Co-authored-by: Cursor <cursoragent@cursor.com>

rektdeckard · 2026-06-11T00:09:42Z

Sorry for late question, but now that console feature is compiled by default on all platforms, how different is this from just using console in text mode?

toubatbrian · 2026-06-11T00:14:37Z

From my understanding, lk agent session gives users/agents a way to send multiple independent commands to a session.

With console, you don’t really get that separation, since it starts an interactive terminal UI. There isn’t a command-line-friendly way to distinguish between starting a session and sending input to that session, which is especially important for AI agents using a bash tool.

cc @theomonnom in case you have more thoughts on the goal/scope of this feature.

toubatbrian requested review from rektdeckard and theomonnom June 3, 2026 01:13

theomonnom approved these changes Jun 3, 2026 •

edited

Loading

View reviewed changes

theomonnom requested changes Jun 3, 2026

View reviewed changes

theomonnom reviewed Jun 3, 2026

View reviewed changes

toubatbrian and others added 2 commits June 3, 2026 15:46

toubatbrian requested a review from theomonnom June 3, 2026 22:52

Update session.go

7514534

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(cli): add `lk agent session` for headless text-mode agent runs#857

feat(cli): add `lk agent session` for headless text-mode agent runs#857
toubatbrian wants to merge 5 commits into
mainfrom
feat/agent-session-daemon

toubatbrian commented Jun 3, 2026 •

edited

Loading

Uh oh!

theomonnom left a comment

Uh oh!

theomonnom Jun 3, 2026

Uh oh!

toubatbrian Jun 3, 2026 •

edited

Loading

Uh oh!

theomonnom Jun 4, 2026

Uh oh!

theomonnom Jun 4, 2026

Uh oh!

toubatbrian Jun 4, 2026

Uh oh!

rektdeckard commented Jun 11, 2026

Uh oh!

toubatbrian commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

toubatbrian commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Command running / IO example

Notes

Test plan

Uh oh!

Uh oh!

theomonnom left a comment

Choose a reason for hiding this comment

Uh oh!

theomonnom Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

toubatbrian Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

theomonnom Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

theomonnom Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

toubatbrian Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

rektdeckard commented Jun 11, 2026

Uh oh!

toubatbrian commented Jun 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

toubatbrian commented Jun 3, 2026 •

edited

Loading

toubatbrian Jun 3, 2026 •

edited

Loading