byted-contextsearch-operator

name	byted-contextsearch-operator
description	Manages Volcano Engine ContextSearch control-plane operations, and searches/chats with configured Context Search data-plane endpoints. Use when the user mentions ContextSearch on Volcano Engine, console operations, AgenticSearch setup, or context-aware search/chat.
version	1.0.0
metadata	{"openclaw":{"requires":{"env":["VOLCENGINE_AK","VOLCENGINE_SK"]},"optional":{"env":["VOLCENGINE_REGION","VOLCENGINE_SCHEMA","CTX_SEARCH_API_KEY"]}}}
license	Apache-2.0

Volcano Engine ContextSearch

Manage ContextSearch on Volcano Engine — application control-plane operations plus runtime data-plane search/chat against configured context endpoints.

Quick Start

Use the bundled CLIs (always run via the skill venv):

{baseDir}/venv/bin/python {baseDir}/scripts/control.py <command>
{baseDir}/venv/bin/python {baseDir}/scripts/data.py <command>
{baseDir}/venv/bin/python {baseDir}/scripts/context_search.py <command>

If {baseDir}/venv does not exist:

python3 -m venv {baseDir}/venv
{baseDir}/venv/bin/pip install -r {baseDir}/requirements.txt

See references/control_plane.md and references/data_plane.md for workflows and examples.

Low-level fallback (use only when goal-based commands do not cover the task):

{baseDir}/venv/bin/python {baseDir}/scripts/contextsearch_cli.py <namespace> <command>

See references/control_tools.md and references/control_coverage.md.

Available operations

Control Plane (application console operations): Use goal-based workflows and console action commands to create AgenticSearch, manage scenes, data sources, indexers, search configs, Agentic tools/skills/variables/chats/users, models, deployments, PSR resources, network, specs, and API keys. → See references/control_plane.md.

Data Plane (runtime search/chat): Use the bundled data-plane scripts to list configured contexts, search context-aware indexes, and chat with RAG-backed knowledge bases. → See references/data_plane.md.

Low-level tools: Use scripts/contextsearch_cli.py console or openapi only when control.py does not cover a specific console action. → See references/control_tools.md.

Out of scope

• Operating non-Volcano-Engine ContextSearch deployments.
• Designing full application-level RAG/AgenticSearch architecture beyond the fields needed to run the provided commands.
• Guessing unknown request bodies, context endpoints, API keys, IDs, or credentials. If a body shape is not clear, inspect the relevant console request shape or ask the user for required fields.

Rules

Common

• Execution environment: Always use {baseDir}/venv/bin/python to run scripts.
• Control-plane authentication: Console operations require VOLCENGINE_AK and VOLCENGINE_SK. Use VOLCENGINE_REGION only when the default cn-beijing is not correct.
• Data-plane authentication: Runtime search/chat requires CTX_SEARCH_API_KEY plus {baseDir}/config.json created from {baseDir}/config.json.template.
• Script usage: Use scripts/control.py for console operations. Use scripts/data.py or scripts/context_search.py for runtime search/chat. Use scripts/contextsearch_cli.py only as a last resort when control.py does not cover the console action.
• Console parity: For AgenticSearch creation, use control.py create-agentic-search; it follows the console chain ListAgenticSceneTemplate -> CheckBuiltinDeployment -> DeployBuiltinDeployment -> CreateAgenticScene.
• Output handling: Commands return JSON. Make decisions from status, goal, data, and steps_completed.
• Language (strict): Always reply in the user's language. If the user's message contains Chinese characters, reply in Chinese. Keep commands/flags/code in English.

Control plane

• Console boundary: Treat ContextSearch console operations as control-plane operations, including Agentic data source/indexer/search-config setup.
• Destructive actions (strict): Never run delete operations until:
  1. You first fetch and show what will be deleted.
  2. The user replies with an explicit confirmation phrase that includes the exact target identifier.
  3. You pass that exact target identifier into the CLI --confirm argument when the goal-based command supports it.
• Missing parameters: Never fail silently. Inspect available resources or ask one concise question.
• Mutation retry safety: If a mutation may have been submitted but the result is unclear, observe with a get/list command before retrying.

Data plane

• Context config: Never invent base_url, context names, or CTX_SEARCH_API_KEY.
• Context types: knowledge_base supports search and chat; image and video support search only.
• Modes and size: For data-plane search/chat, omit --mode and --size unless the user explicitly asks for them. For image/video search, only quick is valid when a mode is specified.
• Image/video search: The data-plane script automatically requests download info and chooses public download URLs only for .volces.com hosts.