Skip to main content

Retrieval service commands

The kscli service group — create, configure, publish, copy, and delete retrieval and Q&A services

A retrieval service (also called an agent) is the retrieval entry point for Knowledge Bases. It holds the model, policy, and rerank settings, and you reference it with --agent-id in the search and chat commands. Services come in two scenes: search (retrieval) and chat (Q&A). This group has 7 commands. Shared conventions for authentication, workspace ID, global flags, output formats, confirmation prompts, and dry-run mode are covered in the CLI overview. The examples below assume the workspace ID is already set in the config file.

Version model

Configuration changes follow a draft-then-publish flow:
StatusDescription
draftNewly created; only a beta draft exists and nothing is published yet
deployedAt least one version is published; production calls use the latest published version
editedPublished, then the beta draft was modified; production calls still use the published version
deletedDeleted
Configuration changes apply to the beta draft only. Validate the draft with search or chat plus --agent-version beta, then publish it with service deploy. Version numbers increment automatically.

kscli service list

List retrieval or Q&A services in the workspace. 
kscli service list --scene <chat|search> [flags]
Parameters
ParameterTypeRequiredDescription
--scene <chat｜search>stringYesService scene, chat (Q&A) or search (retrieval)
--status <status>stringNoFilter by status, draft, deployed (includes edited), or deleted
--name <text>stringNoFuzzy filter by service name
--agent-id <id>stringNoFilter by exact service ID
--index-id <id>stringNoFilter by linked Knowledge Base ID
--page-number <n>numberNoPage number, default 1
--page-size <n>numberNoItems per page, default 10, range 1–100
Output 
aid-xxx  deployed  2  my-qa  (kb: my-kb)
total: 1
Use an agent_id above with the chat command.
The last line automatically suggests whether to consume the service with search or chat, based on --scene. quiet mode prints one service ID per line. json mode returns the full result. --scene is required, so listing both scenes takes two calls. Examples 
# List Q&A services
kscli service list --scene chat

# Only published retrieval services
kscli service list --scene search --status deployed

kscli service get

Show service details including per-version configuration. 
kscli service get --agent-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--agent-id <id>stringYesService ID
--agent-version <version>stringNoA specific version to inspect, beta or a published number. Omit for all versions
Output 
Basic:
  id: aid-xxx
  name: my-qa
  desc: product Q&A
  scene: chat
  status: deployed
Version beta:
  desc: draft
  policy: turbo
  model: qwen-max
  temperature: 0.7
  kb: idx-xxx (my-kb)
Version 1:
  published: 2026-01-01
Both quiet and json modes return the full JSON result. Combined with --output json, this exports the current configuration so you can edit it and write it back with service update --config-file. Examples 
# All versions
kscli service get --agent-id aid-xxx

# Only the beta draft
kscli service get --agent-id aid-xxx --agent-version beta

kscli service create

Create a retrieval or Q&A service. It starts in draft status with a beta version. 
kscli service create --name <text> --scene <chat|search> [flags]
Parameters
ParameterTypeRequiredDescription
--name <text>stringYesService name, up to 200 chars, unique per scene in the workspace
--scene <chat｜search>stringYesService scene, chat (Q&A) or search (retrieval)
--description <text>stringNoService description, up to 1000 chars
--index-id <id>stringNoBind this Knowledge Base; other settings use server defaults
Output 
created: aid-xxx  (status: draft, version: beta)
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
quiet mode prints the service ID. json mode returns the full result. Notes
  • Without --index-id the service is created with default settings; you can bind a Knowledge Base later with service update --config-file.
  • A new service has only a beta draft, so regular search and chat calls cannot reach it until it is published — test it with --agent-version beta.
  • Requires Knowledge Base create permission in the workspace.
Examples 
# Create a Q&A service
kscli service create --name my-qa --scene chat

# Create a retrieval service bound to a Knowledge Base
kscli service create --name my-search --scene search --index-id idx-xxx

kscli service update

Update the service name, description, or draft configuration. 
kscli service update --agent-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--agent-id <id>stringYesService ID
--name <text>stringNoNew name, up to 200 chars
--description <text>stringNoNew description, up to 1000 chars
--agent-version <version>stringNoTarget version, defaults to the beta draft. Published versions accept --version-desc only
--version-desc <text>stringNoVersion description
--policy <policy>stringNoService policy, turbo (fast) or agentic (multi-turn)
--model <name>stringNoGeneration model name, must be on the platform allowlist
--temperature <n>numberNoSampling temperature, range 0–2
--max-llm-calls <n>numberNoMaximum model calls per request, range 1–30
--enable-session-file <bool>stringNoEnable session files, true or false
--enable-refusal <bool>stringNoEnable refusal answers, true or false
--enable-anti-leak <bool>stringNoEnable anti prompt-leak, true or false
--enable-rich-text <bool>stringNoEnable rich text output, true or false
--enable-citation <bool>stringNoEnable citations, true or false
--config-file <path>stringNoReplace the whole service configuration with a JSON file, which can set nested fields such as Knowledge Base bindings; mutually exclusive with the scalar config flags above
Constraints
  • At least one update field is required, otherwise the command reports Nothing to update
  • --config-file is mutually exclusive with the scalar config flags (--policy, --model, --temperature, and so on)
  • Published versions accept --version-desc only, not configuration changes
  • Boolean flags accept only true or false
Output 
updated: aid-xxx
Draft config changed — verify with --agent-version beta, then deploy.
quiet mode prints nothing. json mode returns the full result. Notes
  • Configuration changes affect the beta draft only and do not reach production calls until service deploy runs.
  • When using scalar config flags, any setting you do not pass stays unchanged.
  • --config-file replaces the configuration wholesale — fields absent from the JSON are reset to defaults. Export the current configuration with service get --output json first and edit from there.
Examples 
# Adjust the temperature
kscli service update --agent-id aid-xxx --temperature 0.7

# Replace the whole configuration from a JSON file
kscli service update --agent-id aid-xxx --config-file ./agent-config.json

# Add a description to published version 1
kscli service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"

kscli service deploy

Publish the beta draft as a new version. 
kscli service deploy --agent-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--agent-id <id>stringYesService ID
--version-desc <text>stringNoDescription for the newly published version
--yesswitchNoSkip the confirmation prompt
Output 
deployed: aid-xxx  version 2
quiet mode prints the new version number. json mode returns the full result.
Publishing changes behavior for production callers immediately. If the service is currently in edited status (published, then the draft was modified), the confirmation prompt additionally warns that publishing will override production behavior. Validate with --agent-version beta before publishing.
The version number increments automatically and the service status becomes deployed. Requires Knowledge Base update permission in the workspace. Examples 
# Publish with an interactive confirmation
kscli service deploy --agent-id aid-xxx

# Publish with a description, skipping confirmation
kscli service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes

kscli service delete

Delete a retrieval or Q&A service. 
kscli service delete --agent-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--agent-id <id>stringYesService ID
--yesswitchNoSkip the confirmation prompt
Output 
deleted: aid-xxx  (status: deleted)
quiet mode prints nothing. json mode returns the full result.
Deletion cannot be undone. The agent_id stops working for search and chat, so every application referencing it fails immediately. If the service is in deployed or edited status, the confirmation prompt additionally warns that the service is live.
Deleting an already deleted service does not raise an error. Requires Knowledge Base delete permission in the workspace. Examples 
# Delete with an interactive confirmation
kscli service delete --agent-id aid-xxx

# Skip confirmation
kscli service delete --agent-id aid-xxx --yes

kscli service copy

Copy a service into a new draft; the name gets a copy_ prefix. 
kscli service copy --agent-id <id> [flags]
Parameters
ParameterTypeRequiredDescription
--agent-id <id>stringYesSource service ID
Output 
new agent_id: aid-new  (name: copy_my-qa, status: draft)
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
quiet mode prints the new service ID. json mode returns the full result. The copy starts as a draft with a beta version, and needs service deploy before it affects production calls. This is the safe way to experiment with a new configuration without touching a live service. Requires Knowledge Base create permission in the workspace. Examples 
kscli service copy --agent-id aid-source
Getting Started
Playground
Data Ingestion
Knowledge Service
Cookbook
Integration
Settings, Billing & Limits
Retrieval service commands - Knowledge Studio