> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# agent

> Manage agent deployments

The `agent` command provides sub-commands for managing your deployed agents. These commands allow you to view status, start agents, see logs, and manage deployments.

## start

Start a deployed agent instance, creating an active session.

**Usage:**

```shell theme={null}
pipecat cloud agent start [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--api-key / -k" type="string">
  Public API key to authenticate the agent deployment. Will default to any key
  set in your config.

  For more information, see [API keys](/pipecat-cloud/fundamentals/accounts-and-organizations#api-keys).
</ParamField>

<ParamField path="--data / -d" type="string">
  Stringified JSON object to pass to the agent deployment. This data will be
  available to the agent as a `data` parameter in your `bot()` method.

  More information [here](/pipecat-cloud/fundamentals/active-sessions#running-an-agent).
</ParamField>

<ParamField path="--force / -f" type="boolean" default="false">
  Skip summary confirmation before issuing start request.
</ParamField>

<ParamField path="--use-daily / -D" type="boolean" default="false">
  Create a Daily WebRTC session for the agent.
</ParamField>

<ParamField path="--daily-properties / -p" type="string">
  Stringified JSON object with Daily room properties to customize the WebRTC
  session. Only used when `--use-daily` is set to true.

  See [Daily API
  documentation](https://docs.daily.co/reference/rest-api/rooms/config) for
  available properties.
</ParamField>

<ParamField path="--organization / -o" type="str">
  Organization to start the agent for. If not provided, uses the current
  organization from your configuration.
</ParamField>

## stop

Stop an active agent session and clean up its resources.

**Usage:**

```shell theme={null}
pcc agent stop [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--session-id / -s" type="string" required>
  ID of the session to stop.
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization which the agent belongs to. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--force / -f" type="boolean" default="false">
  Bypass prompt for confirmation before stopping the session.
</ParamField>

## status

Shows the current status of an agent deployment, including health and conditions.

**Usage:**

```shell theme={null}
pipecat cloud agent status [ARGS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

## deployments

Lists deployment history for an agent, including image versions and timestamps.

**Usage:**

```shell theme={null}
pipecat cloud agent deployments [ARGS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

## logs

Displays combined logs from all agent instances, useful for debugging issues.

**Usage:**

```shell theme={null}
pipecat cloud agent logs [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--level / -l" type="string" default="ALL">
  Filter logs by severity: `ALL`, `DEBUG`, `INFO`, `WARNING`, `ERROR`,
  `CRITICAL`.
</ParamField>

<ParamField path="--limit / -n" type="int" default="100">
  Limit the number of log lines to display.
</ParamField>

<ParamField path="--deployment / -d" type="str">
  Filter results for specific agent deployment ID (obtainable from `pipecat
      cloud agent deployments [agent-name]`).
</ParamField>

<ParamField path="--session-id / -s" type="str">
  Filter results for specific session ID (obtainable from `pipecat cloud agent
      sessions [agent-name]`).
</ParamField>

## list

Lists all agents in an organization with their details.

**Usage:**

```shell theme={null}
pipecat cloud agent list [OPTIONS]
```

**Options:**

<ParamField path="--organization / -o" type="string">
  Organization to list agents for. If not provided, uses the current
  organization from your configuration.
</ParamField>

<ParamField path="--region / -r" type="string">
  Filter agents by region. Only agents deployed in the specified region will be
  shown. If not provided, agents from all regions are listed.
</ParamField>

## sessions

Lists active sessions for a specified agent. When there are no active sessions, it suggests how to start a new session.

When used with the `--id` option, displays detailed information about a specific session including CPU and memory usage with sparkline visualizations and percentile summaries.

**Usage:**

```shell theme={null}
pipecat cloud agent sessions [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Name of the agent to list active sessions for.
</ParamField>

**Options:**

<ParamField path="--config-file" type="string">
  Path to an alternate deploy config file. Defaults to `pcc-deploy.toml`.
</ParamField>

<ParamField path="--id / -i" type="string">
  Session ID to view detailed metrics for. When provided, displays CPU and
  memory usage statistics including sparkline visualizations and percentile
  summaries (p50, p90, p99).
</ParamField>

<ParamField path="--organization / -o" type="string">
  Organization to list sessions for. If not provided, uses the current
  organization from your configuration.
</ParamField>

## delete

Deletes an agent deployment. This will prevent starting new agents and remove all associated data.

<Warning>This action is irreversible. All data will be lost.</Warning>

**Usage:**

```shell theme={null}
pipecat cloud agent delete [ARGS] [OPTIONS]
```

**Arguments:**

<ParamField path="agent-name" type="string" required>
  Unique string identifier for the agent deployment. Must not contain spaces.
</ParamField>

**Options:**

<ParamField path="--force / -f" type="string">
  Do not prompt for confirmation before deleting the agent.
</ParamField>