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

# Manage Agents

> Use snctl to update, control, and inspect Orca Agents running on StreamNative Cloud.

Use the `snctl agents` command group to manage Orca Agents after they are deployed. The commands cover day-two operations such as listing agents, rolling out new artifacts, restarting runtimes, and deleting resources when they are no longer needed.

## Prerequisites

* Complete the [environment setup guide](/agent-engine/agents-setup) so `snctl` is authenticated against the correct organization, cluster, tenant, and namespace.
* Ensure your service account has permissions to read, update, and delete agents in the target namespace.
* Package the agent artifact (ZIP archive) you plan to deploy, as described in the framework-specific guides under **Develop Agents**.

## List agents in a namespace

Run `snctl agents list` with the tenant and namespace that scope your deployment. The command prints a table of agents.

```bash theme={null}
snctl agents list \
  --tenant public \
  --namespace operations
```

## Inspect an agent configuration

Fetch the stored configuration to confirm topics, framework, and runtime options. Use either the tenant/namespace pair or the fully qualified agent name.

```bash theme={null}
snctl agents get \
  --tenant public \
  --namespace operations \
  --name support-agent
```

Example output (trimmed for brevity):

```json theme={null}
{
  "name": "support-agent",
  "framework": "openai",
  "inputs": [
    "persistent://public/operations/support-requests"
  ],
  "output": "persistent://public/operations/support-responses",
  "parallelism": 1,
  "secrets": {
    "OPENAI_API_KEY": {
      "path": "llm-secrets",
      "key": "openai"
    }
  }
}
```

## Update an agent

Use `snctl agents update` to apply new code artifacts or adjust runtime settings. Reuse the same flags you passed when creating the agent.

### Deploy a new artifact

Provide the new ZIP archive with `--agent-file`. Include any other fields that changed (for example, updated topic bindings or secrets).

```bash theme={null}
snctl agents update \
  --tenant public \
  --namespace operations \
  --name support-agent \
  --agent-framework openai \
  --directory openai_multi_tool \
  --agent-file openai_multi_tool.zip \
  --inputs persistent://public/operations/support-requests \
  --output persistent://public/operations/support-responses \
  --secrets '{"OPENAI_API_KEY":{"path":"llm-secrets","key":"openai"}}'
```

### Adjust runtime settings

Pass the setting you want to change. The example below increases parallelism to scale out processing.

```bash theme={null}
snctl agents update \
  --tenant public \
  --namespace operations \
  --name support-agent \
  --parallelism 2
```

If the update command reports **Update contains no change**, verify that at least one flag carries a new value.

## Control agent lifecycle

Pause or resume the agent when you need to stop processing without deleting the deployment.

```bash theme={null}
# Gracefully stop all running instances
snctl agents stop \
  --tenant public \
  --namespace operations \
  --name support-agent

# Restart the agent after applying fixes
snctl agents restart \
  --tenant public \
  --namespace operations \
  --name support-agent

# Start the agent if it is currently stopped
snctl agents start \
  --tenant public \
  --namespace operations \
  --name support-agent
```

## Check runtime status

Retrieve the live status to confirm instance health, restart counts, and recent processing activity.

```bash theme={null}
snctl agents status \
  --tenant public \
  --namespace operations \
  --name support-agent
```

The output includes metrics for each instance. See [Monitor agents](/agent-engine/agents-monitoring) for guidance on interpreting the fields.

## Trigger a test request

If the agent deployed and running healthy, you can deliver an ad-hoc payload with `snctl agents trigger`. Supply the input topic name along with the payload that should be delivered to the agent.

```bash theme={null}
snctl agents trigger \
  --tenant public \
  --namespace operations \
  --name support-agent \
  --topic persistent://public/operations/support-requests \
  --payload 'how to reset the API token'
```

## Delete an agent

When the deployment is no longer required, remove it with `snctl agents delete`. The command supports both tenant/namespace pairs and fully qualified agent names.

```bash theme={null}
snctl agents delete \
  --tenant public \
  --namespace operations \
  --name support-agent
```

Run `snctl agents list` again to confirm the agent no longer appears. If the delete command reports that the agent does not exist, double-check the tenant, namespace, and name values.