SuperAPI AI Directory

byted-interactai-guide

General & other

View repository

Updated 10-16 10:10

About this skill

InteractAI Guide — Capabilities, Configuration, Integration, and Troubleshooting Thin Router

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 json to 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:

  1. 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.
  2. 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.
  3. If the user wishes to continue actual execution, provide npm install -g @volcengine/rtc-cli, and after installation use vertc version --format json to 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 run vertc auth login --browser=manual --start and return the authorization_url to the user. After the user returns the authorization code, in the second round pass that code via stdin to vertc auth login --resume. When receiving the authorization code, must notre-run --browser=manual or --start, otherwise a different state will be generated and the old authorization code will inevitably fail. Only after the user selects --store=keyring access 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 receives vertc.dev.selection_required, only read the public candidates from error.details , then use --app-id or a repeatable --bot-id to 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 provide https://console.volcengine.com/conversational-ai/agentManage for the user to view, then resolve the Bot name or ID returned by the user from error.details.bots into 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. If dev finds no available RTC application, directly have the user open https://console.volcengine.com/rtc?from=doc to 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 by vertc auth login , and when RTC App/Bot configuration is missing, run vertc dev or vertc dev --reconfigure。
  • vertc explain-error <code>: offline lookup of the meaning of RTC/VoiceChat error codes and repair suggestions, with output marked domain(web-sdk/voice-agent)、source and verified trust 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 as curated-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 exact results[].id, then fetch the original text for verification; use list only for directory browsing. For parameter templates and stop conditions, see references/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_required or 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 from error.details . When it is confirmed that there is no Bot, use the built-in default Scene, and you may guide the user to visit https://console.volcengine.com/conversational-ai/agentManage to 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 as curated-seed, and the output will explicitly prompt that the official source prevails.
  • Each time you read vertc --format json the success or failure output, check the top-level _noticeWhen the user asks about Runtime, CLI installation, version, or updates, prompt _notice.update / _notice.skills and 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 vertc JSON output for this task. Controlled automation can separately set VERTC_NO_UPDATE_NOTIFIER=1、VERTC_NO_SKILLS_NOTIFIER=1。
  • agent / env / token etc. as internal/legacy commands (hidden by default), non-default fast paths; prefer using public commands init / auth login / dev / doctor / docs / explain-error / skills。

Authoritative source