Manage Agents

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 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.

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.

snctl agents get \
  --tenant public \
  --namespace operations \
  --name support-agent

Example output (trimmed for brevity):

{
  "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).

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.

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.

# 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.

snctl agents status \
  --tenant public \
  --namespace operations \
  --name support-agent

The output includes metrics for each instance. See Monitor agents 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.

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.

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.

Overview

Get Started

Develop Agents

Operations

Integrations

MCP

Prerequisites

List agents in a namespace

Inspect an agent configuration

Update an agent

Deploy a new artifact

Adjust runtime settings

Control agent lifecycle

Check runtime status

Trigger a test request

Delete an agent

​Prerequisites

​List agents in a namespace

​Inspect an agent configuration

​Update an agent

​Deploy a new artifact

​Adjust runtime settings

​Control agent lifecycle

​Check runtime status

​Trigger a test request

​Delete an agent

Prerequisites

List agents in a namespace

Inspect an agent configuration

Update an agent

Deploy a new artifact

Adjust runtime settings

Control agent lifecycle

Check runtime status

Trigger a test request

Delete an agent