# Agent commands

> 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.

:::note{title="Version"}
Needs `@trayai/helix-sdk` and `@trayai/helix-cli` newer than 1.6.0.
:::

## helix agent list

```bash
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

```bash
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 |

```bash
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](/documentation/reference/cli/dev/) for the dev server's flags.

---

Canonical: https://helix.tray.ai/documentation/reference/cli/agent/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt