Skip to main content
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.
I