---
title: Agents
sidebar_position: 4
---

import config from "../../../siteConfig"

This page covers all commands related to agent management in the <SiteName /> CLI. Agents are at the core of the platform and represent deployable AI logic. This section includes commands for listing, creating, deploying, and removing agents.

## List Agents

List all agents in the project:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent list`}
  </code>
</pre>

To list agents in another project:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent list --project <project-id>`}
  </code>
</pre>

**Options:**
- `--project <projectId>` – Project ID or name (defaults to the current project)

## Create an Agent

Create a single agent or all agents defined in `nestbox-agents.yaml`:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent create --agent <agent-name> --instance <machine-name>`}
  </code>
</pre>

Create with additional options:

<pre>
  <code className="language-bash">
{`${config.cliCommand} agent create \\
  --agent <agent-name> \\
  --instance <machine-name> \\
  --type REGULAR \\
  --description "My agent goal" \\
  --inputSchema '{"type":"object","properties":{"prompt":{"type":"string"}}}'`}
  </code>
</pre>

Create all agents defined in `nestbox-agents.yaml`:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent create --all --instance <machine-name>`}
  </code>
</pre>

**Options:**
- `--agent <agent>` – Agent name to create
- `--all` – Create all agents defined in `nestbox-agents.yaml`
- `--project <project>` – Project ID (defaults to current project)
- `--type <type>` – Agent type (e.g. `CHAT`, `AGENT`, `REGULAR`)
- `--description <description>` – Description of the agent
- `--instance <instance>` – Machine name
- `--inputSchema <inputSchema>` – Agent input schema

## Deploy an Agent

Deploy an AI agent to the <SiteName /> platform. Deploy uses the same YAML (and flag) semantics as create. It zips your project root, uploads the code, and updates metadata.

Deploy a single agent:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent deploy --agent <agent-name> --instance <machine-name>`}
  </code>
</pre>

Deploy all agents from `nestbox-agents.yaml`:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent deploy --all --instance <machine-name>`}
  </code>
</pre>

Deploy with verbose logging:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent deploy --all --instance <machine-name> --log`}
  </code>
</pre>

Deploy with a custom prefix:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent deploy --agent <agent-name> --instance <machine-name> --prefix "v2-"`}
  </code>
</pre>

**Options:**
- `--agent <agent>` – Agent name to deploy
- `--all` – Deploy all agents defined in `nestbox-agents.yaml`
- `--prefix <prefix>` – A prefix added to beginning of the agent name
- `--description <description>` – Goal/description of the agent
- `--inputSchema <inputSchema>` – Agent input schema
- `--project <project>` – Project ID (defaults to current project)
- `--type <type>` – Agent type (e.g. `CHAT`, `AGENT`, `REGULAR`)
- `--entryFunction <entryFunction>` – Entry function name
- `--instance <instance>` – Machine name
- `--log` – Show detailed logs during deployment
- `--silent` – Disable automatic agent creation

**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>`).

## Remove an Agent

Remove an agent from the platform:

<pre>
  <code className="language-bash">
    {`${config.cliCommand} agent remove <agent-name>`}
  </code>
</pre>

**Parameters:**
- `<agent-name>` – Name of the agent to remove

**Options:**
- `--project <projectId>` – Project ID or name (defaults to the current project)