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.