Skip to main content

Agents

This page covers all commands related to agent management in the Nestbox AI CLI. Agents are at the core of the platform and represent deployable AI logic. This section includes commands for generating, creating, deploying, listing, removing agents, and monitoring their runtime events.

Generate Agent Structure​

Scaffold a new agent directory structure with optional language and template parameters:

nestbox agent generate <folder> --lang=ts --template=basic

You can also specify the Node.js version and the project:

nestbox agent generate <folder> --lang=js --version=20 --project <project-id>

Create an Agent​

Create from YAML (recommended) or with CLI overrides. The command accepts --agent or --all:

nestbox agent create --agent <agent-name> --instance <machine-name>

Create with CLI overrides (bypasses YAML fields):

nestbox agent create --agent <agent-name> --instance <machine-name> --description "My agent goal" --inputSchema '{"type":"object","properties":{"prompt":{"type":"string"}}}'

Create all agents defined in nestbox-agents.yaml:

nestbox agent create --all --instance <machine-name>

Optional flags:

  • --project <project-id> – target project (otherwise resolved automatically if possible)
  • --prefix <prefix> – prepends to the agent name (e.g., prefix-agent-name)
  • --type <REGULAR|CHATBOT|WORKFLOW> – overrides YAML type

List Agents​

List all agents running on a given compute instance:

nestbox agent list --instance <instance-id>

To list agents in another project:

nestbox agent list --instance <instance-id> --project <project-id>

Deploy an Agent​

Deploy uses the same YAML (and flag) semantics as create. It zips your project root (running any configured predeploy scripts), uploads the code, and updates metadata.

Deploy a single agent (YAML-backed, with optional overrides):

nestbox agent deploy --agent <agent-name> --instance <machine-name> --entryFunction myAgent --description "Override goal (optional)" --inputSchema '{"type":"object","properties":{"prompt":{"type":"string"}}}'

Deploy all agents from nestbox-agents.yaml:

nestbox agent deploy --all --instance <machine-name>

Behavior:

  • If the agent does not exist, you’ll be prompted to create it (skip prompt with --silent).
  • --entryFunction overrides the YAML entry for this deploy.
  • --prefix applies during deploy as well (names become prefix-<agent>).
  • Use --log for verbose deployment output.

Remove an Agent​

Remove an agent from an instance:

nestbox agent remove --instance <instance-id> <agent-id>

The CLI will prompt for confirmation before removing the agent.

Monitor Agent Events​

Stream recent logs or events emitted by an agent:

nestbox agent events <agent-id>

To view only the latest N entries:

nestbox agent events <agent-id> --tail 100