This is the external Skill entry point, responsible for identifying user intent and the run stage, then loading the references/ corresponding topic knowledge. API fields, configuration details, error codes, and complete troubleshooting steps are all placed in references.
Trigger Conditions
- Integration requests such as "build a voice agent that can converse / a voice Demo" and "get Volcano RTC voice conversation working."
- Asking about product support status, capability lists, how a certain capability works, or applicable boundaries.
- Asking about currently supported models, API versions, billing, public beta status, or recently added capabilities, requiring verification against the latest official documentation.
- Generating, modifying, or validating StartVoiceChat / AibotCreate / AibotUpdate configurations using natural language.
- Failures during operation such as "the AI didn't answer," "the Agent didn't join the room," "it can join the room but there's no sound," or "there are no subtitles."
- Needing to explain a certain RTC / VoiceChat error code.
Working Modes and CLI Availability
First distinguish whether the user needs consultation or actual execution, because this Skill's knowledge content can be used independently; only automated operations depend on the CLI:
- Consultation Mode: Documentation/API queries, concept explanations, integration plans, and manual troubleshooting based on logs and symptoms provided by the user. Answer directly and read as needed
references/; do not ask the user to install just because the CLI is not installed. - Execution Mode: Creating projects, login authentication, obtaining App/Bot configurations, starting the Demo, running automatic diagnostics, or invoking CLI offline error code queries. Before the first CLI execution of the current task, first run
vertc version --format jsonto check availability; there is no need to repeat the check at every subsequent step.
Every vertc command actually executed by this Skill must have the process-level Skill identifier injected when calling the execution tool; the value must be composed of the current SKILL.md frontmatter's name and version , and no @is allowed. It must not be exported, persisted, or written into configuration. This is internal invocation metadata: do not expand this prefix in user-facing commands, explanations, or final replies.
VE_SKILL_ID=<name>/<version> vertc <command>
If the command does not exist or the environment cannot find vertc:
- Clearly state that the current environment does not have the CLI installed or cannot access it, and point out which operations therefore cannot be performed for the time being.
- At the same time, tell the user that they can still continue documentation consultation, solution discussion, and manual troubleshooting based on existing evidence; do not judge the Skill as a whole to be unavailable, and do not interpret the missing CLI as an RTC, VoiceChat, or project failure.
- If the user wishes to continue actual execution, provide
npm install -g @volcengine/rtc-cli, and after installation usevertc version --format jsonto verify. When the upper-layer Runtime provides automatic initialization, the upper-layer script installs it; other environments require obtaining the user's consent first.
Shortest Runnable Path (Public Commands)
vertc init --scene voice-agent --platform web --name my-agent
cd my-agent
vertc auth login
vertc dev
When the user needs to choose from a limited set of candidates, you must prioritize calling the structured questioning tool already provided by the current environment (such as
request_user_input or AskUserQuestion), and wait for the user's choice before continuing. When no structured questioning tool is available, fall back to brief numbered text options; do not call tools not provided by the current environment.
vertc auth login: When authorization is required, first ask about the browser/manual login method, and by default save refreshable Signin credentials to a protected user-level file, without reading or modifying the current project. Agent/non-TTY must first obtain the user's consent, then explicitly use--browser=open; if the browser is not on the device where the CLI is located, in the first round runvertc auth login --browser=manual --startand return theauthorization_urlto the user. After the user returns the authorization code, in the second round pass that code via stdin tovertc auth login --resume. When receiving the authorization code, must notre-run--browser=manualor--start, otherwise a different state will be generated and the old authorization code will inevitably fail. Only after the user selects--store=keyringaccess the system credential store.vertc dev: When RTC configuration is missing, the only App is selected automatically; when a Bot exists, require the user to select one and write it into the scenario JSON; when zero Bots are confirmed, use the built-in default Scene, then start Web and Server in one go. If non-TTY receivesvertc.dev.selection_required, only read the public candidates fromerror.details, then use--app-idor a repeatable--bot-idto retry. When the Bot candidates exceed the option limit of the structured question tool, do not truncate or display them in pages; inform the user of the total number of candidates and providehttps://console.volcengine.com/conversational-ai/agentManagefor the user to view, then resolve the Bot name or ID returned by the user fromerror.details.botsinto a unique Bot ID; when the name is not unique, display only candidates with the same name. When re-selection is needed, use--reconfigure. After startup, click on the page Start to enter the room and converse. Ifdevfinds no available RTC application, directly have the user openhttps://console.volcengine.com/rtc?from=docto complete real-name verification and activate the RTC service.- If it fails, first run
vertc doctor(read-only diagnosis), then handle it according to the routing table below.
Intent / Stage → references routing
| User intent / Symptom | Run stage | Route |
|---|---|---|
| Product capability overview / whether supported / latest capabilities | Consultation | references/capabilities.md(for fast-changing facts, check the current official documentation) |
| RTC documentation search / exact body verification | Consultation | references/topic-doc-catalog.md → documentation-retrieval.md(exact list → fetch; if no route, then search) |
| VoiceChat API fields / invocation method | Configuration | references/voicechat-api.md(official links preferred) |
| Generate / modify / validate VoiceChat configuration | Configuration | references/voice-agent-config.md → load model / validation / output as needed |
| Failed to enter room / no media / audio present but cannot play | Join room · capture · publish · playback | references/web-sdk-diagnosis.md |
| Agent did not join room / no subtitles / ASR·LLM·TTS abnormal | After StartVoiceChat | references/voice-agent-runtime.md |
| What a single event can prove / current evidence boundary | Quick assessment | references/integration-flow.md |
| "AI did not answer" (vague symptom) | Full chain | references/integration-flow.md; if it cannot converge, then read integration-stages.md |
| The CLI command itself reports an error | — | Read error.code + vertc doctor |
Use vertc skills read byted-interactai-guide/references/integration-flow.md to directly read any reference.
For configuration requests, first read voice-agent-config.md, then load the reference it points to. Field ranges, enums, and Provider/Model/Resource compatibility change with the product; before determining conclusions, verify the official text of the current product, interface, and API version. Console configuration validation follows the voice-agent-config-validation.md limited in
docs search → fetch Process: for the same partition, reuse the original query; when evidence is insufficient, keep unknown。
When the inquiry involves current RTC documentation, first follow references/documentation-retrieval.md use public read-only
commands to retrieve and obtain the original text; do not treat search summaries as the body text, and do not silently switch to outdated materials when the service is unavailable.
Capability answer boundaries
Must distinguish:Product support、Limited by model/version/configuration、Not currently covered by Demo/CLI、Not yet verified.
Not implemented in Demo, not covered by local reference, or unable to connect to the network cannot be inferred as the product not supporting it; a definitive "not supported" must
have a basis in current official documentation. Fast-changing facts such as current capabilities, exact APIs, model compatibility, billing, quotas, and public beta status should be handled according to
references/capabilities.md first check the official body text; when unable to query, explain the local verified_at and unverified boundaries.
Run-stage identification
End-to-end chain: authentication → Demo configuration → Web SDK initialization → user joins room → microphone capture and publish →
StartVoiceChat → Agent joins room → Agent subscribes to user audio → ASR/VAD → LLM → TTS →
user subscribes to and plays Agent audio. For quick-judgment evidence, see references/integration-flow.md; for complete stages and deep-dive routing, see
references/integration-stages.md。
For "AI did not answer", do not give a generalized checklist
First read integration-flow.md, confirm the previous step succeeded before moving on, and stop as soon as the first failure/insufficient-evidence stage is hit. Only when quick judgment
cannot converge and the user requests complete localization should you read integration-stages.md and one related domain reference.
Diagnostic tools
vertc doctor:Read-onlytwo-level health check (CLI self-check + project readiness), item by item PASS/WARN/SKIP/UNKNOWN/FAIL. Itdoes not write credentials, does not modify configuration, and does not connect to the network to complete the project; login state is fixed byvertc auth login, and when RTC App/Bot configuration is missing, runvertc devorvertc dev --reconfigure。vertc explain-error <code>: offline lookup of the meaning of RTC/VoiceChat error codes and repair suggestions, with output markeddomain(web-sdk/voice-agent)、sourceandverifiedtrust status. VoiceChat runtime states and OpenAPI public codes have been verified against the official "Events and Error Codes" and "Public Error Codes" (verified); items for login credential and signature troubleshooting that lack item-by-item public sources are marked ascurated-seed, and will explicitly prompt that the official source prevails; do not treat them as established facts.vertc docs search/fetch/list: read-only query of RTC documentation, no project or login required; first search to get the exactresults[].id, then fetch the original text for verification; use list only for directory browsing. For parameter templates and stop conditions, seereferences/documentation-retrieval.md。
Security boundaries and reminders
- Secrets such as AppKey go only through environment variables and must never be written to configuration or logs; do not paste real secrets into documentation/commands.
- When encountering
vertc.dev.selection_requiredor missing credentials,it is forbidden to ask the user for, repeat, or record the AppKey; only let the user select a public App/Bot ID fromerror.details. When it is confirmed that there is no Bot, use the built-in default Scene, and you may guide the user to visithttps://console.volcengine.com/conversational-ai/agentManageto customize. Manual fallback only points to the local editor or the secret management workflow. - The Voice Agent error knowledge has been verified against Volcengine official "Events and Error Codes" and "Public Error Codes" as
verified; items for login credential and signature troubleshooting that lack item-by-item public sources are marked ascurated-seed, and the output will explicitly prompt that the official source prevails. - Each time you read
vertc --format jsonthe success or failure output, check the top-level_noticeWhen the user asks about Runtime, CLI installation, version, or updates, prompt_notice.update/_notice.skillsand the corresponding commands. Product consultation, configuration, and diagnostic scenarios ignore these lifecycle notices. Updates or synchronization still require explicit user authorization. - Lifecycle notices come from a 24-hour local cache and must not interrupt the current task or add synchronous network waiting to normal commands.
A cold cache may have no notice on the first call and only trigger a background refresh; this does not mean it is already the latest version. Do not poll or retry just to wait for a notice; continue checking each subsequent
vertcJSON output for this task. Controlled automation can separately setVERTC_NO_UPDATE_NOTIFIER=1、VERTC_NO_SKILLS_NOTIFIER=1。 agent/env/tokenetc. as internal/legacy commands (hidden by default), non-default fast paths; prefer using public commandsinit/auth login/dev/doctor/docs/explain-error/skills。
Authoritative source
- Product boundaries:AI Audio/Video Interaction Solution Product Overview
- Latest changes:AI Audio/Video Interaction Solution Release Notes
- Full documentation tree:AI Audio/Video Interaction Solution