Agent commands | Helix docs

List the agents the local dev server loaded with helix agent list, and talk to one from the terminal with helix agent chat, approvals included.

helix agent talks to the agents a running helix dev server loaded from functions/_agents/. list shows what is loaded; chat opens a terminal conversation with one agent, pausing for approval when a tool needs it. Both commands need helix dev running in another terminal.

helix agent list

helix agent list

Prints one line per loaded agent: name, model, and description.

Flag	What it does
`--url <url>`	Dev server base URL. Default `http://localhost:3000`

  support-agent   claude-sonnet-4-5     Resolves order and refund questions for a signed-in customer.
  shipping-agent  claude-haiku-4-5      Tracks shipments and estimates delivery dates.

With nothing loaded it says so and reminds you to add files under functions/_agents/ and restart helix dev.

helix agent chat

helix agent chat <name>

Starts an interactive conversation with the named agent. Each message you type at the ? you: prompt is one generate() call; the chat keeps one session for its whole run, so the agent remembers earlier turns.

There are two ways out, and they differ:

Exit	What happens
Send an empty message	Prints `Session: <id>`, so you can resume later with `--session`, and exits 0
Press `Ctrl+C`	Exits with code 130 and prints nothing. The session id is not shown

Flag	What it does
`--url <url>`	Dev server base URL. Default `http://localhost:3000`
`--session <id>`	Continue an existing session instead of starting a new one
`--user <id>`	Act as this user. Required for agents with `memory.scope: 'user'`, which otherwise fail with a 400

helix agent chat support-agent
helix agent chat assistant --user u_123
helix agent chat assistant --user u_123 --session ses_7f3a…

When the agent pauses on a needsApproval tool, the chat shows the tool name and its input and asks for a decision, defaulting to no:


Chatting with support-agent — empty message to exit.

? you: refund order 1042, it arrived broken
? Run issue_refund({"orderId":"1042","amount":180,"reason":"Item arrived broken"})? (y/N) y

support-agent: Done. I've refunded 180.00 to the original payment method.

? you:
Session: ses_7f3a…

y resumes with the tool approved; anything else denies it. Several pending tools are asked about one after another, then the run resumes with all the decisions. The agent’s reply after the decision prints as a normal turn. A pause that lists nothing to approve ends the chat with an error rather than looping.

Errors

A failure prints one line, prefixed Agent chat failed: or Agent list failed:, and exits with code 1. The text after the prefix is one of:

Message	Cause
`Could not reach the dev server at http://localhost:3000. Is helix dev running?`	No server on the URL. Start `helix dev`, or pass `--url`
`Unexpected non-JSON response from …`	The server on that URL is not a Helix dev server with agent support, or is an older CLI version
A message saying the agent is user-scoped and needs a user	Pass `--user <id>`
`Unknown agent "<name>". Registered agents: …`	No loaded agent has that name. Check `helix agent list`, and restart `helix dev` after adding a file

What the dev server prints

On startup, after the function routes:

  Agents (2): support-agent, shipping-agent
    chat: helix agent chat support-agent

During a chat, with pretty logs on, each turn shows an AGENT line when the run starts, a TOOL line per tool call, and a closing AGENT line with the outcome, step count, and duration. See local development commands for the dev server’s flags.