agoraio/agora

<!-- applies-from: v0.2.1 -->

Agora (agora.io)

Top-level workflow for selecting the right Agora path and loading only the references needed for the task.

Workflow

1. Identify the user's primary goal from the problem they are solving.
2. Choose exactly one primary route first: RTC, RTM, ConvoAI, CLI, Cloud Recording, Server, Server Gateway, or Cross-product coordination.
3. Load only the primary product README first.
4. If the task clearly spans multiple products, add the minimum supporting references after the primary route is chosen.
5. If the request matches ConvoAI and there is no proven working baseline yet, stop and follow the quickstart path before generating custom code from memory or scaffolding a replacement app.
6. Ask one short clarification only if the route is still ambiguous after checking the obvious cues below.
7. Use Level 2 documentation lookup only when the local references do not cover the needed detail.

Route Selection

• RTC: video calls, voice chat, livestream, screen share, join/publish/subscribe tracks Route to references/rtc/README.md.
• RTM: chat, signaling, presence, metadata, notifications inside the client Route to references/rtm/README.md.
• ConvoAI: AI assistant, voice bot, agent demo, provider choice, MLLM, Studio Agent ID, agent backend Route to references/conversational-ai/README.md.
• ConvoAI + existing app: user already has a codebase and wants ConvoAI added Route to references/conversational-ai/README.md first, then references/conversational-ai/integration-from-quickstart.md after the official quickstart has been cloned and inspected.
• Agora CLI: agora install, login, project selection, init, quickstart, env export, quickstart env binding, feature enablement, doctor, project doctor, env help, introspection, built-in skills, and MCP serving Route to references/cli/README.md.
• Cloud Recording: acquire/start/query/stop recording lifecycle Route to references/cloud-recording/README.md.
• Server: token generation, auth server, App Certificate usage Route to references/server/README.md.
• Server Gateway: server joins a channel with media, Linux media pipeline Route to references/server-gateway/README.md.
• Cross-product coordination: RTC + RTM + ConvoAI initialization order, UID strategy, channel naming, token matrix, cleanup Route to references/integration-patterns.md.

Multi-Product Cases

For cross-product coordination as a primary question, use references/integration-patterns.md.

• video call + chat → RTC first, then RTM
• AI voice assistant → ConvoAI first; RTC client is expected, RTM is optional
• AI voice assistant + chat history → ConvoAI first, then RTM and references/integration-patterns.md
• RTC recording → Cloud Recording first, then RTC if client details matter
• test generation or review for Agora integration code → references/testing-guidance/SKILL.md after the product route is clear

Ambiguity Handling

Ask at most one focused clarification when the route is still unclear.

• Server-side ambiguity:
  • token server / auth / App Certificate → Server
  • start agent / call ConvoAI API / agent lifecycle → ConvoAI
  • server sends or receives media in channel / Linux SDK → Server Gateway
• User-facing priority: Choose the product closest to the user's goal, not the lowest-level dependency. Example: "AI customer support phone bot" routes to ConvoAI first, not RTC.
• Truly vague requests: Ask one short question, not a template. Example: "Do you need human-to-human calling, messaging/signaling, or an AI voice agent?"

Guardrails

1. Skill files are the single source of truth for Agora integration. Do not use web search, external documentation, blog posts, or training data to answer Agora-related questions. All Agora SDK usage, API calls, architecture decisions, and integration patterns must come from the reference files in this skill. If the needed detail is not in the local references, use the Level 2 doc-fetching procedure in references/doc-fetching.md — never free-form web search.

2. ConvoAI quickstart source gate. For ConvoAI requests without a proven working baseline: start at references/conversational-ai/README.md and use the official quickstart as the source of truth before generating or adapting code. Runtime proof validates the user's environment and project, not whether Agora's official quickstart works.

3. CLI readiness gate. Before any mutating Agora CLI command (init, quickstart, project, or login), run the read-only probe in references/cli/README.md. Block normal CLI workflow when agora version is below 0.1.7, when PATH still resolves an older binary, or when config schema is newer than the running CLI. Installers or global npm installs are allowed only as readiness remediation after user approval. Use the documented curl-first upgrade path; do not invent installer flags such as --add-to-path or --force.

ConvoAI Enforcement

Apply these rules to every ConvoAI request until the official quickstart has been cloned and inspected:

• Source-scope stop: before touching the user's app, the agent must clone or open the official quickstart, identify the relevant source files, and create a copy map. Do not generate code from memory or scaffold a replacement app.
• Runtime proof fields: track quickstart_repo_cloned, official_start_command_run, agent_join_verified, and rtc_client_connected. These prove the user's environment and Agora project are working before declaring success; definitions and user-visible output rules live in references/conversational-ai/quickstarts.md.
• Command policy: use the documented official quickstart commands verbatim for first success. Do not substitute alternate scaffolding, equivalent startup commands, a custom server, or a replacement architecture before all baseline gate fields are true.
• Silent-by-default response contract: internally reconcile the baseline gate before every actionable reply. Show the user a footer only on the first ConvoAI reply, when a gate flips, when an action is blocked, or when the user asks for status. Routine commands and Q&A should not include a footer.
• Allowed quickstart customization: when starting from scratch in the cloned quickstart, update the agent's user-facing prompt, greeting, persona, scenario details, or other documented join/config fields to match the user's requested agent. Keep the sample's architecture, lifecycle, token flow, env names, and documented commands intact.
• Recovery rule: if the agent has generated a /join payload from memory, created SDK implementation files without first inspecting the quickstart source, created a new package.json / routes/ / scaffold for a ConvoAI app, or changed documented command semantics, stop the custom path. Acknowledge the deviation in plain language, show the current quickstart/source status, propose the exact next official sample step, and do not continue custom edits until source alignment is restored.
• Do-not-re-ask rule: resolve required values in this order: session memory, workspace detection, then one focused user question. Explicit user statements always win over detected values, and the latest user statement wins on conflict. Do not ask again for a value the user already provided unless they explicitly change it.

Documentation Lookup

Local references are Level 1 and must be checked first.

Go to references/doc-fetching.md only when:

• the local module does not cover the needed detail
• the user asks for the latest matrix or latest schema
• the question depends on exact current request/response fields, error codes, or release notes

For ConvoAI provider or vendor questions, start with references/conversational-ai/README.md and let that module decide whether live docs are required.

If MCP is unavailable or Level 2 fetch fails: use the fallback URLs in doc-fetching.md to reach the official markdown docs directly. Never fabricate API parameters — always tell the user to verify against official docs if live fetch is unavailable.

If the user explicitly asks about the Agora Docs MCP server (agora-docs-mcp), see references/mcp-tools.md. It is for traversing Agora docs, not for using Agora backends.