`helix agent`¶

Sub-dispatcher for agent management. Two subcommands today: list prints the agents defined in a YAML file; test reifies one agent's workflow as a static check (validates that it will load, without running it).

Usage¶

helix agent <subcommand> [arguments]

Sub-commands¶

Sub-command	Description
`helix agent list <file>`	List every agent declared in the YAML (or every workflow that contains an inline agent step).
`helix agent test <file> --agent <id> --input "message"`	Verify that the named agent can be reified. Does NOT execute.

`agent list`¶

Extracts agents from a YAML using dsl.ExtractAgents. Prints a table with columns ID, TYPE, MODEL, TRIGGER. Defaults: TYPE is react if unspecified; TRIGGER falls back to direct://<id>.

If the file declares no top-level agents: block, agent list falls back to scanning every workflow for agent: steps and prints a line per match (Workflow "X" contains inline agent step (type: Y)).

`agent test`¶

Verifies the named agent without launching the engine:

Loads the YAML via the standard loader.
Finds the workflow whose ID equals --agent or whose first inline agent step has that ID.
Reifies the workflow with the full default component set.
Reports trigger URI, step count, and the validated input string.

If anything fails (file not found, agent not found, reification error) the command exits non-zero with the underlying error.

This is a static check — useful in CI to assert that an agent definition is well-formed. To actually drive an agent interactively, use helix chat or helix code; to expose it over a network, use a agui://, a2a-server://, or http-server:// trigger and run with helix run.

Flags¶

The agent dispatcher takes no flags directly. Sub-command flags:

Sub-command	Flag	Description
`agent test`	`--agent ID`	(required) ID of the agent to reify.
`agent test`	`--input STRING`	(required) Input to record in the validation report. Not actually sent — `test` is static.

Behavior notes¶

Requires $HELIX_LICENSE. Verified at process start.
agent test calls engine.New("helix-agent-test") and registers the full default component set, so a successful test means "this agent will reify in helix run too".
Both subcommands use the full YAML loader (imports:, ${file:...} includes resolve normally).

Examples¶

List agents in a project:

$ helix agent list app.yaml
Agents in app.yaml:
ID                   TYPE         MODEL                     TRIGGER
----                 ------       -------                   ---------
chat-agent           react        gpt-4o-mini               agui://0.0.0.0:4200/agent
rag-agent            react        gpt-4o-mini               agui://0.0.0.0:4201/agent

Total: 2 agent(s)

Smoke-test an agent without launching the engine:

$ helix agent test app.yaml --agent chat-agent --input "Hello"
Agent "chat-agent" validated successfully
  Workflow: chat-agent
  Trigger: agui://0.0.0.0:4200/agent
  Steps: 1
  Input: "Hello"

To run this agent interactively, use:
  helix run app.yaml

Then send input to the agent's endpoint (e.g., via HTTP or direct:// workflow).

Source¶

cmd/helix/main.go lines 2506-2522 (cmdAgent dispatcher), 2524-2577 (cmdAgentList), 2579-2659 (cmdAgentTest).

helix agent¶