dsh-agora 0.2.0

package/assets/agora/references/conversational-ai/server-custom-llm.md

@@ -0,0 +1,45 @@
+# Custom LLM Server
+
+OpenAI-compatible LLM proxy for Agora Conversational AI. Intercepts LLM requests for RAG, tool calling, and conversation memory.
+
+**Repo:** <https://github.com/AgoraIO-Conversational-AI/server-custom-llm>
+
+## Implementations
+
+| Language | Framework | Port | Notes |
+|----------|-----------|------|-------|
+| Python | FastAPI | 8100 | |
+| Node.js | Express | 8101 | Advanced — exclusive features below |
+| Go | Gin | 8102 | |
+
+## Endpoints
+
+- `/chat/completions` — LLM proxy with server-side tool execution (up to 5 passes)
+- `/rag/chat/completions` — RAG-enhanced with retrieval step
+- `/audio/chat/completions` — Multimodal audio responses
+
+> **[README — Endpoints](https://github.com/AgoraIO-Conversational-AI/server-custom-llm#endpoints)**
+
+## Integration with ConvoAI
+
+Set `LLM_URL` to your server endpoint, `LLM_VENDOR=custom` in agent-samples `.env`.
+
+> **[README — Integration](https://github.com/AgoraIO-Conversational-AI/server-custom-llm#integration-with-agora-conversational-ai)**
+
+## Features
+
+- Server-side tool execution (get_weather, calculate examples)
+- Conversation memory (per appId:userId:channel, 100 message limit, 24h cleanup)
+- RTM integration for text messaging (Node.js)
+- Streaming SSE responses
+
+> **[README — Features](https://github.com/AgoraIO-Conversational-AI/server-custom-llm#features)**
+
+## Node.js-Exclusive Features
+
+- `/register-agent` and `/unregister-agent` endpoints — agent lifecycle hooks
+- Pluggable module system: `init()`, `getToolDefinitions()`, `onRequest`/`onResponse` hooks
+- Dynamic RTM initialization via request headers (`X-Agora-Customllm-*`)
+- Go audio subscriber for RTC audio capture (spawned as child process)
+
+> **[node/integrations/README.md](https://github.com/AgoraIO-Conversational-AI/server-custom-llm/blob/main/node/integrations/README.md)** — Module system and integrations

package/assets/agora/references/conversational-ai/server-mcp.md

@@ -0,0 +1,40 @@
+# MCP Memory Server
+
+Multi-user MCP server with persistent memory and full-text search for Agora Conversational AI agents.
+
+**Repo:** <https://github.com/AgoraIO-Conversational-AI/server-mcp-memory>
+
+## Implementations
+
+All 3 implementations are production-ready with feature parity. Test suite: `test/run_all.sh` (comprehensive happy + failure path tests).
+
+| Language | Framework | Port | Notes |
+|----------|-----------|------|-------|
+| Python | Starlette | 8090 | |
+| Node.js | Express | 8091 | |
+| Go | Gin | 8092 | Requires `CGO_ENABLED=1` build flag (SQLite) |
+
+## MCP Tools
+
+- `save_memory` — store a memory with category and tags
+- `search_memory` — BM25 full-text search
+- `list_memories` — list by category
+- `delete_memory` — delete by ID
+- `compact_memories` — merge related memories
+- `log_message` — append to conversation log
+
+> **[README — Tools](https://github.com/AgoraIO-Conversational-AI/server-mcp-memory#mcp-tools)**
+
+## Integration with ConvoAI
+
+Configure `MCP_SERVERS` JSON array in agent-samples `.env`. Uses `build_mcp_servers` function.
+
+> **[README — Integration](https://github.com/AgoraIO-Conversational-AI/server-mcp-memory#integration-with-agora-conversational-ai)**
+
+## Architecture
+
+- SQLite with FTS5 full-text search
+- Per-user memory isolation via URL path (`/mcp/{user_id}`)
+- MCP Streamable HTTP protocol
+
+> **[README — Architecture](https://github.com/AgoraIO-Conversational-AI/server-mcp-memory#architecture)**

package/assets/agora/references/conversational-ai/server-sdk-rename.md

@@ -0,0 +1,78 @@
+---
+name: agora-server-sdk-rename
+description: |
+  Opt-in only. Load when the user's project uses outdated ConvoAI server SDK package or
+  module names and they need to migrate to current names. Do not load for greenfield work.
+  Triggers on: agora-agent-server-sdk, agora-agent (PyPI), agora-agent-server-sdk-go,
+  AgoraIO-Community/agora-agent-server-sdk-go, migrate agora sdk, upgrade server sdk package.
+license: MIT
+metadata:
+  author: agora
+  version: '1.0.0'
+---
+
+# ConvoAI Server SDK — package rename migration
+
+> **Opt-in only.** Load this file when workspace detection or the user shows outdated server SDK names. Default ConvoAI routing uses [server-sdks.md](server-sdks.md), [python-sdk.md](python-sdk.md), and [go-sdk.md](go-sdk.md) with current names.
+
+Apply the renames below in dependency manifests and import statements. The public API is unchanged — only install paths and import strings move.
+
+## Detection signals
+
+Scan the user's project (read-only) for any of:
+
+| Signal | Where to look |
+|--------|----------------|
+| `agora-agent-server-sdk` | `package.json`, lockfiles, `import` / `require` strings |
+| `agora-agent` (not `agora-agents`) | `pyproject.toml`, `requirements.txt`, `Pipfile`, `poetry.lock` |
+| `github.com/AgoraIO-Community/agora-agent-server-sdk-go` | `go.mod`, Go import paths |
+| `agent-server-sdk-go` repo URL | README, CI config, docs |
+
+If none match, do not load this file.
+
+## Rename map
+
+### TypeScript / npm
+
+| Update | From | To |
+|--------|------|-----|
+| Dependency | `agora-agent-server-sdk` | `agora-agents` |
+| Import | `from 'agora-agent-server-sdk'` | `from 'agora-agents'` |
+
+The npm package `agora-agent-server-sdk` still resolves via a compat shim, but new projects and migrations should use `agora-agents`.
+
+### Python / PyPI
+
+| Update | From | To |
+|--------|------|-----|
+| Dependency | `agora-agent` or `agora-agent-server-sdk` | `agora-agents` |
+| Import | `from agora_agent import ...` | **No change** |
+
+Only the PyPI install name changes. Python import paths stay `agora_agent`.
+
+### Go
+
+| Update | From | To |
+|--------|------|-----|
+| Module | `github.com/AgoraIO-Community/agora-agent-server-sdk-go` | `github.com/AgoraIO/agora-agents-go` |
+| Imports | `.../agora-agent-server-sdk-go/...` | `github.com/AgoraIO/agora-agents-go/...` |
+| Repo | `AgoraIO-Conversational-AI/agent-server-sdk-go` | `AgoraIO/agora-agents-go` |
+
+Go has no module alias — update `go.mod` and all import paths together, then `go mod tidy`.
+
+## Migration steps
+
+1. Update the manifest (`package.json`, `pyproject.toml` / `requirements.txt`, or `go.mod`).
+2. Replace import strings in source files per the table above.
+3. Reinstall / tidy (`npm install`, `pip install -r ...`, or `go mod tidy`).
+4. Run the project's test suite or a minimal start/stop agent smoke test.
+
+Do not change application logic, env var names, or AgentKit builder code — the API surface is the same.
+
+## After migration
+
+Route back to the current SDK references for ongoing work:
+
+- TypeScript: [server-sdks.md](server-sdks.md)
+- Python: [python-sdk.md](python-sdk.md)
+- Go: [go-sdk.md](go-sdk.md)

package/assets/agora/references/conversational-ai/server-sdks.md

@@ -0,0 +1,128 @@
+---
+name: agora-convoai-server-sdks
+description: |
+  Server-side SDKs for Agora Conversational AI: TypeScript, Python, and Go wrappers around the
+  ConvoAI REST API. Use when the user is building a backend to start/stop/manage ConvoAI agents.
+  Triggers on: agora-agents, AgoraClient, AgentSession, session.start, session.stop,
+  agent server SDK, ConvoAI backend, ConvoAI server, withStt, withLlm, withTts.
+license: MIT
+metadata:
+  author: agora
+  version: '1.0.0'
+---
+
+# ConvoAI Server SDKs
+
+> **Architecture first:** For call sequence and lifecycle overview before SDK details, read [architecture.md](architecture.md).
+
+TypeScript, Go, and Python SDKs — convenience wrappers around the ConvoAI REST API. For any other backend language, call the REST API directly. Fetch the live OpenAPI spec for the full schema: `https://docs-md.agora.io/api/conversational-ai-api-v2.x.yaml`
+
+## TypeScript — `agora-agents`
+
+```bash
+npm install agora-agents
+```
+
+Builder pattern — configure the AI pipeline then create sessions:
+
+```typescript
+import { AgoraClient, Agent, Area } from 'agora-agents';
+
+const client = new AgoraClient({
+  area: Area.US,
+  appId: process.env.AGORA_APP_ID,
+  appCertificate: process.env.AGORA_APP_CERTIFICATE,
+});
+
+const agent = new Agent({
+  name: `agent_${crypto.randomUUID().slice(0, 8)}`, // must be unique per project
+  instructions: 'You are a helpful voice assistant.',
+  greeting: 'Hello! How can I help you today?',
+})
+  .withStt(new DeepgramSTT({ apiKey: process.env.DEEPGRAM_API_KEY }))
+  .withLlm(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }))
+  .withTts(new ElevenLabsTTS({ apiKey: process.env.ELEVENLABS_API_KEY }));
+
+// Start a session (joins the agent to a channel)
+const session = agent.createSession({ channel: 'my-channel', agentUid: 0 });
+const sessionId = await session.start();
+
+// Stop from the same process
+await session.stop();
+
+// Stop from a stateless server (e.g. a different request handler)
+await client.stopAgent(sessionId);
+```
+
+Token auth is handled automatically when `appCertificate` is provided. For vendor-specific STT/LLM/TTS import paths and MLLM (OpenAI Realtime, Gemini Live) config, see the [SDK README](https://github.com/AgoraIO-Conversational-AI/agent-server-sdk-ts).
+
+## Auth Modes
+
+Three modes, in order of recommendation:
+
+- **App Credentials** (`appId` + `appCertificate`): SDK generates a fresh ConvoAI token per REST call. No token management needed. The App Certificate never leaves your server. Recommended for production.
+- **Token Auth** (`authToken`): A pre-built combined RTC+RTM token you supply. This token is **reused for every request** until you replace the SDK instance — the SDK does not refresh it. You are responsible for refreshing before expiry. Max token validity is 24 hours.
+- **Basic Auth** (`customerId` + `customerSecret`): Credentials never expire but are long-lived secrets that grant access to every project on your account. Use for local testing only; do not ship to production.
+
+## Session State Machine
+
+Sessions follow a strict state sequence. Calling methods outside the valid states throws an error:
+
+| State | `start()` | `stop()` | `say()` / `interrupt()` / `update()` |
+|-------|-----------|----------|---------------------------------------|
+| `idle` | ✅ | ❌ | ❌ |
+| `starting` | ❌ | ❌ | ❌ |
+| `running` | ❌ | ✅ | ✅ |
+| `stopping` | ❌ | ❌ | ❌ |
+| `stopped` | ✅ | ❌ | ❌ |
+| `error` | ✅ | ❌ | ❌ |
+
+`stop()` on a 404 (agent already stopped on the platform) resolves without throwing — the SDK treats it as already stopped.
+
+## In-Process Events (TypeScript)
+
+`AgentSession` emits events within your Node.js process — these are not HTTP webhooks:
+
+```typescript
+session.on('started', () => {
+  // Agent has connected to the RTC channel and is ready
+  // session.id is now set; session.status === 'running'
+});
+
+session.on('stopped', () => {
+  // Agent has left the channel
+});
+
+session.on('error', (err) => {
+  // Non-recoverable error; session.status === 'error'
+  // Safe to call session.start() again from this state
+});
+```
+
+## Avatar + TTS Sample Rate
+
+HeyGen and Akool avatars require a specific TTS sample rate. The SDK validates this at `session.start()` and throws if mismatched. The error message identifies the avatar config as the problem — the root cause is actually the TTS sample rate.
+
+| Avatar vendor | Required TTS sample rate |
+|--------------|--------------------------|
+| HeyGen | **24000 Hz** |
+| Akool | **16000 Hz** |
+
+Whenever an avatar vendor is set, explicitly configure the TTS sample rate to match. Do not rely on defaults.
+
+```typescript
+// HeyGen — must pair with 24 kHz TTS
+const agent = new Agent({ ... })
+  .withAvatar(new HeyGen({ ... }))
+  .withTts(new ElevenLabsTTS({ sampleRate: 24000, ... }));
+
+// Akool — must pair with 16 kHz TTS
+const agent = new Agent({ ... })
+  .withAvatar(new Akool({ ... }))
+  .withTts(new ElevenLabsTTS({ sampleRate: 16000, ... }));
+```
+
+## Python and Go SDKs
+
+- **[python-sdk.md](python-sdk.md)** — Python SDK: sync vs async, deprecation warnings, debug logging.
+- **[go-sdk.md](go-sdk.md)** — Go SDK: context.Context pattern, builder syntax, SessionStatus constants, token helpers.

package/assets/agora/references/doc-fetching.md

@@ -0,0 +1,67 @@
+# Documentation Lookup
+
+**Level 1 — Bundled references (always try first)**
+
+Check the relevant file under `skills/agora/references/`. These are inline-stable:
+RTC init patterns, RTM messaging, token generation, ConvoAI gotchas and generation
+rules. If the answer is here, stop — no fetch needed.
+
+**Level 2 — Live docs (when Level 1 is insufficient)**
+
+When bundled references don't cover the detail needed (full request/response schemas,
+vendor-specific configs, language-specific quick-start code):
+
+If the Agora Docs MCP tool (`agora-docs-mcp`) is available in the current tool/runtime, prefer it for Level 2 documentation lookup. Otherwise use the HTTP fetch flow below. If MCP returns no useful result, fall back to HTTP fetch.
+
+1. Fetch the Agora docs sitemap:
+   ```
+   GET https://docs.agora.io/en/llms.txt
+   ```
+2. Scan the response for a URL matching the product and topic.
+3. Fetch that URL and use its content to answer.
+
+## Fallback
+
+If `llms.txt` is unreachable or the fetched URL returns no useful content, try these
+known markdown entry points directly:
+
+| Product / Language | Markdown URL |
+|---|---|
+| RTC (Web/general) | https://docs-md.agora.io/en/video-calling/get-started/get-started-sdk.md |
+| RTC (voice-only) | https://docs-md.agora.io/en/voice-calling/get-started/get-started-sdk.md |
+| RTM (Web/general) | https://docs-md.agora.io/en/signaling/get-started/sdk-quickstart.md |
+| RTM (iOS) | https://docs-md.agora.io/en/signaling/get-started/sdk-quickstart?platform=ios.md |
+| RTM (Android) | https://docs-md.agora.io/en/signaling/get-started/sdk-quickstart?platform=android.md |
+| ConvoAI | https://docs-md.agora.io/en/conversational-ai/get-started/quickstart.md |
+| ConvoAI (TypeScript SDK) | https://docs-md.agora.io/en/conversational-ai/develop/integrate-sdk.md |
+| ConvoAI (Python SDK) | https://docs-md.agora.io/en/conversational-ai/develop/integrate-sdk?platform=python.md |
+| Cloud Recording | https://docs-md.agora.io/en/cloud-recording/get-started/getstarted.md |
+| Server Gateway (C++) | https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk.md |
+| Server Gateway (Java) | https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=java.md |
+| Server Gateway (Python) | https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=python.md |
+| Server Gateway (Go) | https://docs-md.agora.io/en/server-gateway/get-started/integrate-sdk?platform=go.md |
+| Tokens | https://docs-md.agora.io/en/video-calling/token-authentication/deploy-token-server.md |
+
+## Agora Docs MCP Server (optional)
+
+Agora also provides `agora-docs-mcp`, an MCP server that gives AI assistants
+direct tool-call access to documentation — an alternative to the Level 2 HTTP
+fetch above. It traverses docs only; it does not use Agora backend APIs, log in,
+create projects, or inspect account state. If a user asks about installing or
+using the Agora Docs MCP server, see [mcp-tools.md](mcp-tools.md).
+
+## Agora CLI
+
+For local `agora` command-line usage, check [cli/README.md](cli/README.md) first. Treat that file as the source of truth for the currently verified CLI baseline and command surface.
+
+If the bundled CLI references do not cover a CLI-only detail, use the canonical CLI repository instead of general Agora product docs:
+
+- <https://github.com/AgoraIO/cli>
+- `README.md` — install, first run, command model, common workflows
+- `docs/commands.md` — generated command reference
+- `docs/automation.md` — JSON envelopes and automation contract
+- `docs/error-codes.md` — stable error codes and recovery decisions
+- `docs/telemetry.md` — telemetry preferences and environment controls
+- `CHANGELOG.md` and GitHub Releases — version-specific changes
+
+Do not invent CLI commands, flags, environment variables, or JSON fields. If the installed CLI exposes a command that is not in the bundled references, prefer `agora introspect --json` or `agora --help --all`, then cross-check the CLI repository docs before answering.

package/assets/agora/references/integration-patterns.md

@@ -0,0 +1,201 @@
+# Multi-Product Integration Patterns
+
+This file covers how RTC, RTM, and Conversational AI work together. For SDK-specific code, follow the Level 2 fetch links in each product's reference file.
+
+## When to Use Multiple Products
+
+| Scenario | Products |
+|---|---|
+| Video/voice call only | RTC only |
+| Video call + chat or presence | RTC + RTM |
+| AI agent in a call | RTC + ConvoAI REST API (server-side) |
+| AI agent + live transcripts or state | RTC + RTM + ConvoAI REST API |
+| Text-only signaling (no media) | RTM only |
+
+## RTC + RTM Together
+
+### Initialization Order
+
+Always initialize both SDKs independently — they share no initialization path.
+
+RTC UID and RTM user ID do **not** need to match. Using a shared identity is a coordination convention, not a platform requirement. The right initialization order depends on which identity strategy your app uses.
+
+#### Default pattern — auto-assigned RTC UID
+
+Use this when the RTC client joins with `uid: 0` / `null` and the SDK assigns the final RTC UID:
+
+1. Create and initialize the RTC engine/client
+2. Join the RTC channel
+3. Read the assigned RTC UID from the join callback / resolved promise
+4. Create or log in to the RTM client with `String(rtcUid)`
+5. Subscribe to the RTM channel
+
+This is the safest default because it avoids guessing the RTM identity before the RTC UID is known.
+
+#### Advanced pattern — app-level stable identity
+
+Use this when your app already has a stable user identity independent of the RTC UID:
+
+1. Create and initialize the RTC engine/client
+2. Create and log in to the RTM client with your app-level user identity
+3. Subscribe to the RTM channel
+4. Join the RTC channel
+
+This pattern is useful when you want signaling, presence, or pre-call state to arrive before media starts. It requires an explicit RTC↔RTM mapping in your app or backend.
+
+### UID Strategy
+
+RTC and RTM use different UID types:
+
+| SDK | Platform | UID type |
+|---|---|---|
+| RTC | Web | `number` |
+| RTC | iOS | `UInt` (unsigned 32-bit) |
+| RTC | Android | `Int` (signed 32-bit) |
+| RTM | All platforms | `String` |
+
+Recommended default: use `String(rtcUid)` as the RTM `userId` when your RTC UID is auto-assigned and you want a simple 1:1 mapping between the two systems.
+
+Alternative: use a stable app-level string identity for RTM and maintain an explicit mapping from RTC UID → RTM user ID in your app/backend.
+
+The RTM token subject and RTM login `userId` must match exactly. If your server minted the RTM token for `String(rtcUid)`, the client must log in RTM with that same string — not a different random or app-generated identity.
+
+UIDs greater than 2,147,483,647 wrap to negative on Android RTC — avoid them if Android clients are present.
+
+### Channel Name Convention
+
+Use the **same channel name** for both RTC and RTM. The RTM channel is the coordination layer for the RTC session — same name makes routing unambiguous and is required by the ConvoAI toolkit.
+
+### Token Matrix
+
+Both SDKs require separate tokens in production. Generate them independently on your server:
+
+| Token | Scope | Renew on |
+|---|---|---|
+| RTC token | `appId` + `channelName` + `uid` | `token-privilege-will-expire` / `onTokenPrivilegeWillExpire` |
+| RTM token | `appId` + `userId` | RTM connection state `TOKEN_EXPIRED` or equivalent |
+
+See [server/tokens.md](server/tokens.md) for token generation details.
+
+For Level 2 fetch: fetch `https://docs.agora.io/en/llms.txt`, find the token management guide for your platform, then fetch it.
+
+## RTC + RTM + ConvoAI
+
+Before wiring ConvoAI into an existing multi-product app, read [conversational-ai/architecture.md](conversational-ai/architecture.md) for the end-to-end call sequence, then use the official quickstart as the source of truth for code shape and commands. For existing-app work, use [conversational-ai/integration-from-quickstart.md](conversational-ai/integration-from-quickstart.md) after the quickstart source is inspected; runtime proof is required before claiming the integrated flow works.
+
+### How the Products Connect
+
+```
+Client                          Server
+──────────────────────────────────────────────────────
+RTC Engine/Client ──── media ────► Agora RTC
+RTM Client ────── messages ──────► Agora RTM
+                                      │
+                              [ConvoAI agent joins
+                               same RTC channel,
+                               publishes transcripts
+                               and state to same
+                               RTM channel]
+                                      ▲
+App Server ── REST POST /join ──────► Agora ConvoAI API
+```
+
+### Initialization Order for ConvoAI
+
+1. Initialize RTC (but do not join the channel yet)
+2. Initialize RTM and log in
+3. Subscribe to the RTM channel (to receive agent events)
+4. Call ConvoAI REST `POST /join` from your **app server** with `channelName`, `uid` (your user's RTC uid), and the RTM flags (see below)
+5. Join the RTC channel — the agent will already be there or will join shortly
+
+If your client uses auto-assigned RTC UIDs, adapt the order slightly:
+
+1. Initialize RTC
+2. Join RTC and wait for the assigned user UID
+3. Log in to RTM with `String(rtcUid)` and subscribe to the RTM channel
+4. Call `POST /join` from your app server
+
+The agent can publish transcripts/state through RTM only after the RTM client is logged in and subscribed.
+
+If RTM was just enabled on the project, allow bounded wait/retry before treating an RTM startup failure as a persistent project misconfiguration. Control-plane state can update before the RTM runtime path is actually usable.
+
+### Required ConvoAI Flags for RTM Delivery
+
+When calling `POST /join`, include both of these in the request body:
+
+```json
+{
+  "advanced_features": {
+    "enable_rtm": true
+  },
+  "parameters": {
+    "data_channel": "rtm"
+  }
+}
+```
+
+Both flags are required. Omitting either one means the agent publishes transcripts via RTC data channel instead of RTM, and RTM message events will not fire.
+
+### RTM Channel Name = RTC Channel Name
+
+The ConvoAI agent joins the RTM channel with the **same name** as the RTC channel it joined. When handling `onMessageEvent` / `didReceiveMessageEvent`, filter by `channelName` matching your RTC channel if you are subscribed to multiple channels.
+
+### Agent Events via RTM
+
+The agent publishes JSON messages to the RTM channel. Parse `event.message.data` (Android) or `event.message.stringData` (iOS) as JSON. The `customType` field indicates the event type (transcript, interruption, state change, etc.).
+
+For the full event schema and `customType` values, use Level 2 fetch: fetch `https://docs.agora.io/en/llms.txt`, locate the Conversational AI event reference, then fetch it.
+
+### Token Matrix for ConvoAI
+
+ConvoAI sessions require three separate tokens:
+
+| Token | Purpose | Who generates |
+|---|---|---|
+| RTC token (user) | User joins RTC channel | Your app server |
+| RTM token (user) | User logs into RTM | Your app server |
+| RTC token (agent) | ConvoAI agent joins RTC | Your app server, passed in POST /join |
+
+See [conversational-ai/auth-flow.md](conversational-ai/auth-flow.md) for the full three-token flow (REST API implementors) or [conversational-ai/README.md](conversational-ai/README.md) for SDK-based flows.
+
+## Codec Selection for Mixed Platforms
+
+When Web clients share a channel with iOS or Android native clients:
+
+- Web defaults to `codec: 'vp8'` — this scales well for multi-user calls and is the recommended choice
+- `'vp9'` is also a good option with better compression
+- `'h264'` does not scale well beyond small groups — avoid it for multi-user scenarios
+- If codecs differ between Web and native clients, Agora transcodes server-side — this works but adds latency and is billed separately
+
+See [rtc/cross-platform-coordination.md](rtc/cross-platform-coordination.md) for full cross-platform interop notes.
+
+## Cleanup Order
+
+Reverse of initialization:
+
+1. Leave the RTC channel
+2. Unsubscribe from RTM channels
+3. Log out of RTM
+4. Release both engines/clients
+
+For ConvoAI: call `DELETE /leave` (or the SDK equivalent) from your app server before leaving the RTC channel, to give the agent time to exit gracefully.
+
+## Reference Files by Product
+
+| Product | Platform | File |
+|---|---|---|
+| RTC | Web | [rtc/web.md](rtc/web.md) |
+| RTC | React | [rtc/react.md](rtc/react.md) |
+| RTC | Next.js | [rtc/nextjs.md](rtc/nextjs.md) |
+| RTC | iOS | [rtc/ios.md](rtc/ios.md) |
+| RTC | Android | [rtc/android.md](rtc/android.md) |
+| RTC | React Native | [rtc/react-native.md](rtc/react-native.md) |
+| RTC | Flutter | [rtc/flutter.md](rtc/flutter.md) |
+| RTM | Web | [rtm/web.md](rtm/web.md) |
+| RTM | iOS | [rtm/ios.md](rtm/ios.md) |
+| RTM | Android | [rtm/android.md](rtm/android.md) |
+| ConvoAI | All | [conversational-ai/README.md](conversational-ai/README.md) |
+| ConvoAI toolkit | iOS | [conversational-ai/agent-toolkit-ios.md](conversational-ai/agent-toolkit-ios.md) |
+| ConvoAI toolkit | Android | [conversational-ai/agent-toolkit-android.md](conversational-ai/agent-toolkit-android.md) |
+| Tokens | Server | [server/tokens.md](server/tokens.md) |
+| Cross-platform | All | [rtc/cross-platform-coordination.md](rtc/cross-platform-coordination.md) |

package/assets/agora/references/mcp-tools.md

@@ -0,0 +1,49 @@
+# Agora Docs MCP Server
+
+<!-- applies-from: v0.2.0 -->
+
+The Agora Docs MCP server (`agora-docs-mcp`) gives AI assistants direct tool-call access to Agora documentation. It is an
+optional enhancement — the skill works without it using the two-tier fetch
+approach in [doc-fetching.md](doc-fetching.md).
+
+Agora Docs MCP is for traversing docs only. It does not operate Agora backends,
+log in to accounts, create projects, write env files, or check project readiness;
+the local `agora` CLI handles those workflows.
+
+**Only use MCP when the user explicitly asks for it.** The default documentation
+lookup is the two-tier fetch approach in [doc-fetching.md](doc-fetching.md) — use
+that regardless of whether MCP is installed.
+
+**MCP endpoint:** `https://mcp.agora.io`
+
+## Tools
+
+| Tool | Input | Returns |
+|---|---|---|
+| `get-doc-content` | `{"uri": "docs://..."}` | Full markdown content |
+| `search-docs` | `{"query": "keyword"}` | List of matching doc URIs |
+| `list-docs` | `{"category": "...", "limit": 20}` | All docs in a category |
+
+Use `search-docs` when the topic is known but the URI isn't. Use `get-doc-content`
+directly when the URI is known.
+
+## Installation
+
+**Claude Code:**
+```bash
+claude mcp add agora-docs-mcp --transport http https://mcp.agora.io
+```
+
+**Cursor / Windsurf / other MCP-compatible tools:** Add `https://mcp.agora.io` as
+an HTTP MCP server in your tool's MCP settings. See your tool's documentation for
+the exact configuration format.
+
+For the latest setup instructions and any changes to the endpoint, see:
+<https://docs.agora.io/en/mcp>
+
+## Usage Note
+
+After fetching quick-start docs via MCP, use the content for API structure and field
+names only. Do NOT copy sample code verbatim — quick-start examples typically hardcode
+credentials and omit production requirements. Apply the gotchas and generation rules
+in `references/conversational-ai/README.md` to any generated code.