commit 49178918d793ac2f7441dc1da09c0754f722333e Author: Zhongwei Li Date: Sun Nov 30 08:24:46 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..bd2a6ab --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "elevenlabs-agents", + "description": "Build conversational AI voice agents with ElevenLabs Platform using React, JavaScript, React Native, or Swift SDKs. Configure agents, tools (client/server/MCP), RAG knowledge bases, multi-voice, and Scribe real-time STT. Use when: building voice chat interfaces, implementing AI phone agents with Twilio, configuring agent workflows or tools, adding RAG knowledge bases, testing with CLI agents as code, or troubleshooting deprecated @11labs packages, Android audio cutoff, CSP violations, dynamic va", + "version": "1.0.0", + "author": { + "name": "Jeremy Dawes", + "email": "jeremy@jezweb.net" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..bad4e4d --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# elevenlabs-agents + +Build conversational AI voice agents with ElevenLabs Platform using React, JavaScript, React Native, or Swift SDKs. Configure agents, tools (client/server/MCP), RAG knowledge bases, multi-voice, and Scribe real-time STT. Use when: building voice chat interfaces, implementing AI phone agents with Twilio, configuring agent workflows or tools, adding RAG knowledge bases, testing with CLI agents as code, or troubleshooting deprecated @11labs packages, Android audio cutoff, CSP violations, dynamic va diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..448c039 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,673 @@ +--- +name: elevenlabs-agents +description: | + Build conversational AI voice agents with ElevenLabs Platform using React, JavaScript, React Native, or Swift SDKs. + Configure agents, tools (client/server/MCP), RAG knowledge bases, multi-voice, and Scribe real-time STT. + + Use when: building voice chat interfaces, implementing AI phone agents with Twilio, configuring agent workflows + or tools, adding RAG knowledge bases, testing with CLI "agents as code", or troubleshooting deprecated @11labs + packages, Android audio cutoff, CSP violations, dynamic variables, or WebRTC config. + + Keywords: ElevenLabs Agents, ElevenLabs voice agents, AI voice agents, conversational AI, @elevenlabs/react, @elevenlabs/client, @elevenlabs/react-native, @elevenlabs/elevenlabs-js, @elevenlabs/agents-cli, elevenlabs SDK, voice AI, TTS, text-to-speech, ASR, speech recognition, turn-taking model, WebRTC voice, WebSocket voice, ElevenLabs conversation, agent system prompt, agent tools, agent knowledge base, RAG voice agents, multi-voice agents, pronunciation dictionary, voice speed control, elevenlabs scribe, @11labs deprecated, Android audio cutoff, CSP violation elevenlabs, dynamic variables elevenlabs, case-sensitive tool names, webhook authentication +license: MIT +metadata: + version: 1.2.0 + last_updated: 2025-11-25 + production_tested: true + packages: + - name: "@elevenlabs/elevenlabs-js" + version: 2.25.0 + - name: "@elevenlabs/agents-cli" + version: 0.6.1 + - name: "@elevenlabs/react" + version: 0.11.3 + - name: "@elevenlabs/client" + version: 0.11.3 + - name: "@elevenlabs/react-native" + version: 0.5.4 + documentation: + - https://elevenlabs.io/docs/agents-platform/overview + - https://elevenlabs.io/docs/api-reference + - https://github.com/elevenlabs/elevenlabs-examples + errors_prevented: 17+ + token_savings: ~73% +--- + +# ElevenLabs Agents Platform + +## Overview + +ElevenLabs Agents Platform is a comprehensive solution for building production-ready conversational AI voice agents. The platform coordinates four core components: + +1. **ASR (Automatic Speech Recognition)** - Converts speech to text (32+ languages, sub-second latency) +2. **LLM (Large Language Model)** - Reasoning and response generation (GPT, Claude, Gemini, custom models) +3. **TTS (Text-to-Speech)** - Converts text to speech (5000+ voices, 31 languages, low latency) +4. **Turn-Taking Model** - Proprietary model that handles conversation timing and interruptions + +### 🚨 Package Updates (November 2025) + +ElevenLabs migrated to new scoped packages in August 2025. **Current packages:** + +```bash +npm install @elevenlabs/react@0.11.3 # React SDK +npm install @elevenlabs/client@0.11.3 # JavaScript SDK +npm install @elevenlabs/react-native@0.5.4 # React Native SDK +npm install @elevenlabs/elevenlabs-js@2.25.0 # Base SDK (Python: elevenlabs@1.59.0) +npm install -g @elevenlabs/agents-cli@0.6.1 # CLI +``` + +**DEPRECATED:** `@11labs/react`, `@11labs/client` (uninstall if present) + +**⚠️ CRITICAL:** v1 TTS models will be removed 2025-12-15. Migrate to Turbo v2/v2.5. + +--- + +## 1. Quick Start + +### React SDK +```bash +npm install @elevenlabs/react zod +``` + +```typescript +import { useConversation } from '@elevenlabs/react'; + +const { startConversation, stopConversation, status } = useConversation({ + agentId: 'your-agent-id', + signedUrl: '/api/elevenlabs/auth', // Recommended (secure) + // OR apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY, + + clientTools: { /* browser-side tools */ }, + onEvent: (event) => { /* transcript, agent_response, tool_call */ }, + serverLocation: 'us' // 'eu-residency' | 'in-residency' | 'global' +}); +``` + +### CLI ("Agents as Code") +```bash +npm install -g @elevenlabs/agents-cli +elevenlabs auth login +elevenlabs agents init # Creates agents.json, tools.json, tests.json +elevenlabs agents add "Bot" --template customer-service +elevenlabs agents push --env dev # Deploy +elevenlabs agents test "Bot" # Test +``` + +### API (Programmatic) +```typescript +import { ElevenLabsClient } from 'elevenlabs'; +const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY }); + +const agent = await client.agents.create({ + name: 'Support Bot', + conversation_config: { + agent: { prompt: { prompt: "...", llm: "gpt-4o" }, language: "en" }, + tts: { model_id: "eleven_turbo_v2_5", voice_id: "your-voice-id" } + } +}); +``` + +--- + +## 2. Agent Configuration + +### System Prompt Architecture (6 Components) + +**1. Personality** - Identity, role, character traits +**2. Environment** - Communication context (phone, web, video) +**3. Tone** - Formality, speech patterns, verbosity +**4. Goal** - Objectives and success criteria +**5. Guardrails** - Boundaries, prohibited topics, ethical constraints +**6. Tools** - Available capabilities and when to use them + +**Template:** +```json +{ + "agent": { + "prompt": { + "prompt": "Personality:\n[Agent identity and role]\n\nEnvironment:\n[Communication context]\n\nTone:\n[Speech style]\n\nGoal:\n[Primary objectives]\n\nGuardrails:\n[Boundaries and constraints]\n\nTools:\n[Available tools and usage]", + "llm": "gpt-4o", // gpt-5.1, claude-sonnet-4-5, gemini-3-pro-preview + "temperature": 0.7 + } + } +} +``` + +**2025 LLM Models:** +- `gpt-5.1`, `gpt-5.1-2025-11-13` (Oct 2025) +- `claude-sonnet-4-5`, `claude-sonnet-4-5@20250929` (Oct 2025) +- `gemini-3-pro-preview` (2025) +- `gemini-2.5-flash-preview-09-2025` (Oct 2025) + +### Turn-Taking Modes + +| Mode | Behavior | Best For | +|------|----------|----------| +| **Eager** | Responds quickly | Fast-paced support, quick orders | +| **Normal** | Balanced (default) | General customer service | +| **Patient** | Waits longer | Information collection, therapy | + +```json +{ "conversation_config": { "turn": { "mode": "patient" } } } +``` + +### Workflows & Agent Management (2025) + +**Workflow Features:** +- **Subagent Nodes** - Override prompt, voice, turn-taking per node +- **Tool Nodes** - Guarantee tool execution +- **Edges** - Conditional routing with `edge_order` (determinism, Oct 2025) + +```json +{ + "workflow": { + "nodes": [ + { "id": "node_1", "type": "subagent", "config": { "system_prompt": "...", "turn_eagerness": "patient" } }, + { "id": "node_2", "type": "tool", "tool_name": "transfer_to_human" } + ], + "edges": [{ "from": "node_1", "to": "node_2", "condition": "escalation", "edge_order": 1 }] + } +} +``` + +**Agent Management (2025):** +- **Agent Archiving** - `archived: true` field (Oct 2025) +- **Agent Duplication** - Clone existing agents +- **Service Account API Keys** - Management endpoints (Jul 2025) + +### Dynamic Variables + +Use `{{var_name}}` syntax in prompts, messages, and tool parameters. + +**System Variables:** +- `{{system__agent_id}}`, `{{system__conversation_id}}` +- `{{system__caller_id}}`, `{{system__called_number}}` (telephony) +- `{{system__call_duration_secs}}`, `{{system__time_utc}}` +- `{{system__call_sid}}` (Twilio only) + +**Custom Variables:** +```typescript +await client.conversations.create({ + agent_id: "agent_123", + dynamic_variables: { user_name: "John", account_tier: "premium" } +}); +``` + +**Secret Variables:** `{{secret__api_key}}` (headers only, never sent to LLM) + +**⚠️ Error:** Missing variables cause "Missing required dynamic variables" - always provide all referenced variables. + +--- + +## 3. Voice & Language Features + +### Multi-Voice, Pronunciation & Speed + +**Multi-Voice** - Switch voices dynamically (adds ~200ms latency per switch): +```json +{ "prompt": "When speaking as customer, use voice_id 'voice_abc'. As agent, use 'voice_def'." } +``` + +**Pronunciation Dictionary** - IPA, CMU, word substitutions (Turbo v2/v2.5 only): +```json +{ + "pronunciation_dictionary": [ + { "word": "API", "pronunciation": "ey-pee-ay", "format": "cmu" }, + { "word": "AI", "substitution": "artificial intelligence" } + ] +} +``` + +**PATCH Support (Aug 2025)** - Update dictionaries without replacement + +**Speed Control** - 0.7x-1.2x (use 0.9x-1.1x for natural sound): +```json +{ "voice_settings": { "speed": 1.0 } } +``` + +**Voice Cloning Best Practices:** +- Clean audio (no noise, music, pops) +- Consistent microphone distance +- 1-2 minutes of audio +- Use language-matched voices (English voices fail on non-English) + +### Language Configuration + +**32+ Languages** with automatic detection and in-conversation switching. + +**Multi-Language Presets:** +```json +{ + "language_presets": [ + { "language": "en", "voice_id": "en_voice", "first_message": "Hello!" }, + { "language": "es", "voice_id": "es_voice", "first_message": "Β‘Hola!" } + ] +} +``` + +--- + +## 4. Knowledge Base & RAG + +Enable agents to access large knowledge bases without loading entire documents into context. + +**Workflow:** +1. Upload documents (PDF, TXT, DOCX) +2. Compute RAG index (vector embeddings) +3. Agent retrieves relevant chunks during conversation + +**Configuration:** +```json +{ + "agent": { "prompt": { "knowledge_base": ["doc_id_1", "doc_id_2"] } }, + "knowledge_base_config": { + "max_chunks": 5, + "vector_distance_threshold": 0.8 + } +} +``` + +**API Upload:** +```typescript +const doc = await client.knowledgeBase.upload({ file: fs.createReadStream('docs.pdf'), name: 'Docs' }); +await client.knowledgeBase.computeRagIndex({ document_id: doc.id, embedding_model: 'e5_mistral_7b' }); +``` + +**⚠️ Gotchas:** RAG adds ~500ms latency. Check index status before use - indexing can take minutes. + +--- + +## 5. Tools (4 Types) + +### A. Client Tools (Browser/Mobile) + +Execute in browser or mobile app. **Tool names case-sensitive.** + +```typescript +clientTools: { + updateCart: { + description: "Update shopping cart", + parameters: z.object({ item: z.string(), quantity: z.number() }), + handler: async ({ item, quantity }) => { + // Client-side logic + return { success: true }; + } + } +} +``` + +### B. Server Tools (Webhooks) + +HTTP requests to external APIs. **PUT support added Apr 2025.** + +```json +{ + "name": "get_weather", + "url": "https://api.weather.com/{{user_id}}", + "method": "GET", + "headers": { "Authorization": "Bearer {{secret__api_key}}" }, + "parameters": { "type": "object", "properties": { "city": { "type": "string" } } } +} +``` + +**⚠️ Secret variables** only in headers (not URL/body) + +**2025 Features:** +- **transfer-to-human** system tool (Apr 2025) +- **tool_latency_secs** tracking (Apr 2025) + +### C. MCP Tools (Model Context Protocol) + +Connect to MCP servers for databases, IDEs, data sources. + +**Configuration:** Dashboard β†’ Add Custom MCP Server β†’ Configure SSE/HTTP endpoint + +**Approval Modes:** Always Ask | Fine-Grained | No Approval + +**2025 Updates:** +- **disable_interruptions** flag (Oct 2025) - Prevents interruption during tool execution +- **Tools Management Interface** (Jun 2025) + +**⚠️ Limitations:** SSE/HTTP only. Not available for Zero Retention or HIPAA. + +### D. System Tools + +Built-in conversation control (no external APIs): +- `end_call`, `detect_language`, `transfer_agent` +- `transfer_to_number` (telephony) +- `dtmf_playpad`, `voicemail_detection` (telephony) + +**2025:** `use_out_of_band_dtmf` flag for telephony integration + +--- + +## 6. SDK Integration + +### useConversation Hook (React/React Native) + +```typescript +const { startConversation, stopConversation, status, isSpeaking } = useConversation({ + agentId: 'your-agent-id', + signedUrl: '/api/auth', // OR apiKey: process.env.NEXT_PUBLIC_ELEVENLABS_API_KEY + clientTools: { /* ... */ }, + onEvent: (event) => { /* transcript, agent_response, tool_call, agent_tool_request (Oct 2025) */ }, + onConnect/onDisconnect/onError, + serverLocation: 'us' // 'eu-residency' | 'in-residency' | 'global' +}); +``` + +**2025 Events:** +- `agent_chat_response_part` - Streaming responses (Oct 2025) +- `agent_tool_request` - Tool interaction tracking (Oct 2025) + +### Connection Types: WebRTC vs WebSocket + +| Feature | WebSocket | WebRTC (Jul 2025 rollout) | +|---------|-----------|---------------------------| +| **Auth** | `signedUrl` | `conversationToken` | +| **Audio** | Configurable (16k/24k/48k) | PCM_48000 (hardcoded) | +| **Latency** | Standard | Lower | +| **Best For** | Flexibility | Low-latency | + +**⚠️ WebRTC:** Hardcoded PCM_48000, limited device switching + +### Platforms + +- **React**: `@elevenlabs/react@0.11.3` +- **JavaScript**: `@elevenlabs/client@0.11.3` - `new Conversation({...})` +- **React Native**: `@elevenlabs/react-native@0.5.4` - Expo SDK 47+, iOS/macOS (custom build required, no Expo Go) +- **Swift**: iOS 14.0+, macOS 11.0+, Swift 5.9+ +- **Embeddable Widget**: `` + +### Scribe (Real-Time Speech-to-Text - Beta 2025) + +Real-time transcription with word-level timestamps. **Single-use tokens**, not API keys. + +```typescript +const { connect, startRecording, stopRecording, transcript, partialTranscript } = useScribe({ + token: async () => (await fetch('/api/scribe/token')).json().then(d => d.token), + commitStrategy: 'vad', // 'vad' (auto on silence) | 'manual' (explicit .commit()) + sampleRate: 16000, // 16000 or 24000 + onPartialTranscript/onFinalTranscript/onError +}); +``` + +**Events:** PARTIAL_TRANSCRIPT, FINAL_TRANSCRIPT_WITH_TIMESTAMPS, SESSION_STARTED, ERROR + +**⚠️ Closed Beta** - requires sales contact. For agents, use Agents Platform instead (LLM + TTS + two-way interaction). + +--- + +## 7. Testing & Evaluation + +### πŸ†• Agent Testing Framework (Aug 2025) + +Comprehensive automated testing with **9 new API endpoints** for creating, managing, and executing tests. + +**Test Types:** +- **Scenario Testing** - LLM-based evaluation against success criteria +- **Tool Call Testing** - Verify correct tool usage and parameters +- **Load Testing** - High-concurrency capacity testing + +**CLI Workflow:** +```bash +# Create test +elevenlabs tests add "Refund Test" --template basic-llm + +# Configure in test_configs/refund-test.json +{ + "name": "Refund Test", + "scenario": "Customer requests refund", + "success_criteria": ["Agent acknowledges empathetically", "Verifies order details"], + "expected_tool_call": { "tool_name": "lookup_order", "parameters": { "order_id": "..." } } +} + +# Deploy and execute +elevenlabs tests push +elevenlabs agents test "Support Agent" +``` + +**9 New API Endpoints (Aug 2025):** +1. `POST /v1/convai/tests` - Create test +2. `GET /v1/convai/tests/:id` - Retrieve test +3. `PATCH /v1/convai/tests/:id` - Update test +4. `DELETE /v1/convai/tests/:id` - Delete test +5. `POST /v1/convai/tests/:id/execute` - Execute test +6. `GET /v1/convai/test-invocations` - List invocations (pagination, agent filtering) +7. `POST /v1/convai/test-invocations/:id/resubmit` - Resubmit failed test +8. `GET /v1/convai/test-results/:id` - Get results +9. `GET /v1/convai/test-results/:id/debug` - Detailed debugging info + +**Test Invocation Listing (Oct 2025):** +```typescript +const invocations = await client.convai.testInvocations.list({ + agent_id: 'agent_123', // Filter by agent + page_size: 30, // Default 30, max 100 + cursor: 'next_page_cursor' // Pagination +}); +// Returns: test run counts, pass/fail stats, titles +``` + +**Programmatic Testing:** +```typescript +const simulation = await client.agents.simulate({ + agent_id: 'agent_123', + scenario: 'Refund request', + user_messages: ["I want a refund", "Order #12345"], + success_criteria: ["Acknowledges request", "Verifies order"] +}); +console.log('Passed:', simulation.passed); +``` + +**Agent Tracking (Oct 2025):** Tests now include `agent_id` association for better organization + +--- + +## 8. Analytics & Monitoring + +**2025 Features:** +- **Custom Dashboard Charts** (Apr 2025) - Display evaluation criteria metrics over time +- **Call History Filtering** (Apr 2025) - `call_start_before_unix` parameter +- **Multi-Voice History** - Separate conversation history by voice +- **LLM Cost Tracking** - Per agent/conversation costs with `aggregation_interval` (hour/day/week/month) +- **Tool Latency** (Apr 2025) - `tool_latency_secs` tracking +- **Usage Metrics** - minutes_used, request_count, ttfb_avg, ttfb_p95 + +**Conversation Analysis:** Success evaluation (LLM-based), data collection fields, post-call webhooks + +**Access:** Dashboard β†’ Analytics | Post-call Webhooks | API + +--- + +## 9. Privacy & Compliance + +**Data Retention:** 2 years default (GDPR). Configure: `{ "transcripts": { "retention_days": 730 }, "audio": { "retention_days": 2190 } }` + +**Encryption:** TLS 1.3 (transit), AES-256 (rest) + +**Regional:** `serverLocation: 'eu-residency' | 'us' | 'global' | 'in-residency'` + +**Zero Retention Mode:** Immediate deletion (no history, analytics, webhooks, or MCP) + +**Compliance:** GDPR (1-2 years), HIPAA (6 years), SOC 2 (automatic encryption) + +--- + +## 10. Cost Optimization + +**LLM Caching:** Up to 90% savings on repeated inputs. `{ "caching": { "enabled": true, "ttl_seconds": 3600 } }` + +**Model Swapping:** GPT-5.1, GPT-4o/mini, Claude Sonnet 4.5, Gemini 3 Pro/2.5 Flash (2025 models) + +**Burst Pricing:** 3x concurrency limit at 2x cost. `{ "burst_pricing_enabled": true }` + +--- + +## 11. Advanced Features + +**2025 Platform Updates:** +- **Azure OpenAI** (Jul 2025) - Custom LLM with Azure-hosted models (requires API version field) +- **Genesys Output Variables** (Jul 2025) - Enhanced call analytics +- **LLMReasoningEffort "none"** (Oct 2025) - Control model reasoning behavior +- **Streaming Voice Previews** (Jul 2025) - Real-time voice generation +- **pcm_48000** audio format (Apr 2025) - New output format support + +**Events:** `audio`, `transcript`, `agent_response`, `tool_call`, `agent_chat_response_part` (streaming, Oct 2025), `agent_tool_request` (Oct 2025), `conversation_state` + +**Custom Models:** Bring your own LLM (OpenAI-compatible endpoints). `{ "llm_config": { "custom": { "endpoint": "...", "api_key": "{{secret__key}}" } } }` + +**Post-Call Webhooks:** HMAC verification required. Return 200 or auto-disable after 10 failures. Payload includes conversation_id, transcript, analysis. + +**Chat Mode:** Text-only (no ASR/TTS). `{ "chat_mode": true }`. Saves ~200ms + costs. + +**Telephony:** SIP (sip-static.rtc.elevenlabs.io), Twilio native, Vonage, RingCentral. **2025:** Twilio keypad fix (Jul), SIP TLS remote_domains validation (Oct) + +--- + +## 12. CLI & DevOps ("Agents as Code") + +**Installation & Auth:** +```bash +npm install -g @elevenlabs/agents-cli@0.6.1 +elevenlabs auth login +elevenlabs auth residency eu-residency # 'in-residency' | 'global' +export ELEVENLABS_API_KEY=your-api-key # For CI/CD +``` + +**Project Structure:** `agents.json`, `tools.json`, `tests.json` + `agent_configs/`, `tool_configs/`, `test_configs/` + +**Key Commands:** +```bash +elevenlabs agents init +elevenlabs agents add "Bot" --template customer-service +elevenlabs agents push --env prod --dry-run # Preview +elevenlabs agents push --env prod # Deploy +elevenlabs agents pull # Import existing +elevenlabs agents test "Bot" # 2025: Enhanced testing + +elevenlabs tools add-webhook "Weather" --config-path tool_configs/weather.json +elevenlabs tools push + +elevenlabs tests add "Test" --template basic-llm +elevenlabs tests push +``` + +**Multi-Environment:** Create `agent.dev.json`, `agent.staging.json`, `agent.prod.json` for overrides + +**CI/CD:** GitHub Actions with `--dry-run` validation before deploy + +**.gitignore:** `.env`, `.elevenlabs/`, `*.secret.json` + +--- + +## 13. Common Errors & Solutions (17 Documented) + +### Error 1: Missing Required Dynamic Variables +**Cause:** Variables referenced in prompts not provided at conversation start +**Solution:** Provide all variables in `dynamic_variables: { user_name: "John", ... }` + +### Error 2: Case-Sensitive Tool Names +**Cause:** Tool name mismatch (case-sensitive) +**Solution:** Ensure `tool_ids: ["orderLookup"]` matches `name: "orderLookup"` exactly + +### Error 3: Webhook Authentication Failures +**Cause:** Incorrect HMAC signature, not returning 200, or 10+ failures +**Solution:** Verify `hmac = crypto.createHmac('sha256', SECRET).update(payload).digest('hex')` and return 200 + +### Error 4: Voice Consistency Issues +**Cause:** Background noise, inconsistent mic distance, extreme volumes in training +**Solution:** Use clean audio, consistent distance, avoid extremes + +### Error 5: Wrong Language Voice +**Cause:** English-trained voice for non-English language +**Solution:** Use language-matched voices: `{ "language": "es", "voice_id": "spanish_voice" }` + +### Error 6: Restricted API Keys Not Supported (CLI) +**Cause:** CLI doesn't support restricted API keys +**Solution:** Use unrestricted API key for CLI + +### Error 7: Agent Configuration Push Conflicts +**Cause:** Hash-based change detection missed modification +**Solution:** `elevenlabs agents init --override` + `elevenlabs agents pull` + push + +### Error 8: Tool Parameter Schema Mismatch +**Cause:** Schema doesn't match usage +**Solution:** Add clear descriptions: `"description": "Order ID (format: ORD-12345)"` + +### Error 9: RAG Index Not Ready +**Cause:** Index still computing (takes minutes) +**Solution:** Check `index.status === 'ready'` before using + +### Error 10: WebSocket Protocol Error (1002) +**Cause:** Network instability or incompatible browser +**Solution:** Use WebRTC instead, implement reconnection logic + +### Error 11: 401 Unauthorized in Production +**Cause:** Agent visibility or API key config +**Solution:** Check visibility (public/private), verify API key in prod, check allowlist + +### Error 12: Allowlist Connection Errors +**Cause:** Allowlist enabled but using shared link +**Solution:** Configure allowlist domains or disable for testing + +### Error 13: Workflow Infinite Loops +**Cause:** Edge conditions creating loops +**Solution:** Add max iteration limits, test all paths, explicit exit conditions + +### Error 14: Burst Pricing Not Enabled +**Cause:** Burst not enabled in settings +**Solution:** `{ "call_limits": { "burst_pricing_enabled": true } }` + +### Error 15: MCP Server Timeout +**Cause:** MCP server slow/unreachable +**Solution:** Check URL accessible, verify transport (SSE/HTTP), check auth, monitor logs + +### Error 16: First Message Cutoff on Android +**Cause:** Android needs time to switch audio mode +**Solution:** `connectionDelay: { android: 3_000, ios: 0 }` (3s for audio routing) + +### Error 17: CSP (Content Security Policy) Violations +**Cause:** Strict CSP blocks `blob:` URLs. SDK uses Audio Worklets loaded as blobs +**Solution:** Self-host worklets: +1. `cp node_modules/@elevenlabs/client/dist/worklets/*.js public/elevenlabs/` +2. Configure: `workletPaths: { 'rawAudioProcessor': '/elevenlabs/rawAudioProcessor.worklet.js', 'audioConcatProcessor': '/elevenlabs/audioConcatProcessor.worklet.js' }` +3. Update CSP: `script-src 'self' https://elevenlabs.io; worker-src 'self';` +**Gotcha:** Update worklets when upgrading `@elevenlabs/client` + +--- + +## Integration with Existing Skills + +This skill composes well with: + +- **cloudflare-worker-base** β†’ Deploy agents on Cloudflare Workers edge network +- **cloudflare-workers-ai** β†’ Use Cloudflare LLMs as custom models in agents +- **cloudflare-durable-objects** β†’ Persistent conversation state and session management +- **cloudflare-kv** β†’ Cache agent configurations and user preferences +- **nextjs** β†’ React SDK integration in Next.js applications +- **ai-sdk-core** β†’ Vercel AI SDK provider for unified AI interface +- **clerk-auth** β†’ Authenticated voice sessions with user identity +- **hono-routing** β†’ API routes for webhooks and server tools + +--- + +## Additional Resources + +**Official Documentation**: +- Platform Overview: https://elevenlabs.io/docs/agents-platform/overview +- API Reference: https://elevenlabs.io/docs/api-reference +- CLI GitHub: https://github.com/elevenlabs/cli + +**Examples**: +- Official Examples: https://github.com/elevenlabs/elevenlabs-examples +- MCP Server: https://github.com/elevenlabs/elevenlabs-mcp + +**Community**: +- Discord: https://discord.com/invite/elevenlabs +- Twitter: @elevenlabsio + +--- + +**Production Tested**: WordPress Auditor, Customer Support Agents +**Last Updated**: 2025-11-25 +**Package Versions**: elevenlabs@1.59.0, @elevenlabs/elevenlabs-js@2.25.0, @elevenlabs/agents-cli@0.6.1, @elevenlabs/react@0.11.3, @elevenlabs/client@0.11.3, @elevenlabs/react-native@0.5.4 diff --git a/assets/agent-config-schema.json b/assets/agent-config-schema.json new file mode 100644 index 0000000..f2f3aaf --- /dev/null +++ b/assets/agent-config-schema.json @@ -0,0 +1,111 @@ +{ + "name": "Support Agent", + "conversation_config": { + "agent": { + "prompt": { + "prompt": "You are a helpful customer support agent...", + "llm": "gpt-4o-mini", + "temperature": 0.7, + "max_tokens": 500, + "tool_ids": ["tool_123"], + "knowledge_base": ["doc_456"], + "custom_llm": { + "endpoint": "https://api.openai.com/v1/chat/completions", + "api_key": "{{secret__openai_api_key}}", + "model": "gpt-4" + } + }, + "first_message": "Hello! How can I help you today?", + "language": "en" + }, + "tts": { + "model_id": "eleven_turbo_v2_5", + "voice_id": "your_voice_id", + "stability": 0.5, + "similarity_boost": 0.75, + "speed": 1.0, + "output_format": "pcm_22050" + }, + "asr": { + "quality": "high", + "provider": "deepgram", + "keywords": ["product_name", "company_name"] + }, + "turn": { + "mode": "normal", + "turn_timeout": 5000 + }, + "conversation": { + "max_duration_seconds": 600 + }, + "language_presets": [ + { + "language": "en", + "voice_id": "en_voice_id", + "first_message": "Hello! How can I help you?" + }, + { + "language": "es", + "voice_id": "es_voice_id", + "first_message": "Β‘Hola! ΒΏCΓ³mo puedo ayudarte?" + } + ] + }, + "workflow": { + "nodes": [ + { + "id": "node_1", + "type": "subagent", + "config": { + "system_prompt": "You are now handling technical support...", + "turn_eagerness": "patient", + "voice_id": "tech_voice_id" + } + }, + { + "id": "node_2", + "type": "tool", + "tool_name": "transfer_to_human" + } + ], + "edges": [ + { + "from": "node_1", + "to": "node_2", + "condition": "user_requests_escalation" + } + ] + }, + "platform_settings": { + "widget": { + "theme": { + "primaryColor": "#3B82F6", + "backgroundColor": "#1F2937", + "textColor": "#F9FAFB" + }, + "position": "bottom-right" + }, + "authentication": { + "type": "signed_url", + "session_duration": 3600 + }, + "privacy": { + "transcripts": { + "retention_days": 730 + }, + "audio": { + "retention_days": 2190 + }, + "zero_retention": false + } + }, + "webhooks": { + "post_call": { + "url": "https://api.example.com/webhook", + "headers": { + "Authorization": "Bearer {{secret__webhook_auth_token}}" + } + } + }, + "tags": ["customer-support", "production"] +} diff --git a/assets/ci-cd-example.yml b/assets/ci-cd-example.yml new file mode 100644 index 0000000..9b7be42 --- /dev/null +++ b/assets/ci-cd-example.yml @@ -0,0 +1,77 @@ +name: Deploy ElevenLabs Agent + +on: + push: + branches: [main] + paths: + - 'agent_configs/**' + - 'tool_configs/**' + - 'test_configs/**' + pull_request: + branches: [main] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install ElevenLabs CLI + run: npm install -g @elevenlabs/cli + + - name: Dry Run (Preview Changes) + run: elevenlabs agents push --env staging --dry-run + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_STAGING }} + + - name: Push to Staging + if: github.event_name == 'pull_request' + run: elevenlabs agents push --env staging + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_STAGING }} + + - name: Run Tests + if: github.event_name == 'pull_request' + run: | + elevenlabs tests push --env staging + elevenlabs agents test "Support Agent" + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_STAGING }} + + deploy: + runs-on: ubuntu-latest + needs: test + if: github.ref == 'refs/heads/main' && github.event_name == 'push' + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '18' + + - name: Install ElevenLabs CLI + run: npm install -g @elevenlabs/cli + + - name: Deploy to Production + run: elevenlabs agents push --env prod + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_PROD }} + + - name: Verify Deployment + run: elevenlabs agents status + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY_PROD }} + + - name: Notify on Success + if: success() + run: echo "βœ… Agent deployed to production successfully" + + - name: Notify on Failure + if: failure() + run: echo "❌ Deployment failed" diff --git a/assets/javascript-sdk-boilerplate.js b/assets/javascript-sdk-boilerplate.js new file mode 100644 index 0000000..c710bfb --- /dev/null +++ b/assets/javascript-sdk-boilerplate.js @@ -0,0 +1,215 @@ +import { Conversation } from '@elevenlabs/client'; + +// Configuration +const AGENT_ID = 'your-agent-id'; +const API_KEY = process.env.ELEVENLABS_API_KEY; // Server-side only, never expose in browser + +// Initialize conversation +const conversation = new Conversation({ + agentId: AGENT_ID, + + // Authentication (choose one) + // Option 1: API key (for private agents) + apiKey: API_KEY, + + // Option 2: Signed URL (most secure) + // signedUrl: 'https://api.elevenlabs.io/v1/convai/auth/...', + + // Client tools (browser-side functions) + clientTools: { + updateCart: { + description: "Update shopping cart", + parameters: { + type: "object", + properties: { + item: { type: "string" }, + quantity: { type: "number" } + }, + required: ["item", "quantity"] + }, + handler: async ({ item, quantity }) => { + console.log('Cart updated:', item, quantity); + // Your cart logic here + return { success: true }; + } + } + }, + + // Event handlers + onConnect: () => { + console.log('Connected to agent'); + updateStatus('connected'); + clearTranscript(); + }, + + onDisconnect: () => { + console.log('Disconnected from agent'); + updateStatus('disconnected'); + }, + + onEvent: (event) => { + switch (event.type) { + case 'transcript': + addToTranscript('user', event.data.text); + break; + + case 'agent_response': + addToTranscript('agent', event.data.text); + break; + + case 'tool_call': + console.log('Tool called:', event.data.tool_name); + break; + + case 'error': + console.error('Agent error:', event.data); + showError(event.data.message); + break; + } + }, + + onError: (error) => { + console.error('Connection error:', error); + showError(error.message); + }, + + // Regional compliance + serverLocation: 'us' // 'us' | 'global' | 'eu-residency' | 'in-residency' +}); + +// UI Helpers +function updateStatus(status) { + const statusEl = document.getElementById('status'); + if (statusEl) { + statusEl.textContent = `Status: ${status}`; + } +} + +function addToTranscript(role, text) { + const transcriptEl = document.getElementById('transcript'); + if (transcriptEl) { + const messageEl = document.createElement('div'); + messageEl.className = `message ${role}`; + messageEl.innerHTML = ` + ${role === 'user' ? 'You' : 'Agent'}: +

${text}

+ `; + transcriptEl.appendChild(messageEl); + transcriptEl.scrollTop = transcriptEl.scrollHeight; + } +} + +function clearTranscript() { + const transcriptEl = document.getElementById('transcript'); + if (transcriptEl) { + transcriptEl.innerHTML = ''; + } +} + +function showError(message) { + const errorEl = document.getElementById('error'); + if (errorEl) { + errorEl.textContent = `Error: ${message}`; + errorEl.style.display = 'block'; + } +} + +function hideError() { + const errorEl = document.getElementById('error'); + if (errorEl) { + errorEl.style.display = 'none'; + } +} + +// Button event listeners +document.getElementById('start-btn')?.addEventListener('click', async () => { + try { + hideError(); + await conversation.start(); + } catch (error) { + console.error('Failed to start conversation:', error); + showError(error.message); + } +}); + +document.getElementById('stop-btn')?.addEventListener('click', async () => { + try { + await conversation.stop(); + } catch (error) { + console.error('Failed to stop conversation:', error); + showError(error.message); + } +}); + +// HTML Template +/* + + + + + + ElevenLabs Voice Agent + + + +

ElevenLabs Voice Agent

+ +
+ + +
+ +
Status: disconnected
+
+ +
+ + + + +*/ diff --git a/assets/react-native-boilerplate.tsx b/assets/react-native-boilerplate.tsx new file mode 100644 index 0000000..31474b8 --- /dev/null +++ b/assets/react-native-boilerplate.tsx @@ -0,0 +1,62 @@ +import { useConversation } from '@elevenlabs/react-native'; +import { View, Button, Text, ScrollView } from 'react-native'; +import { z } from 'zod'; +import { useState } from 'react'; + +export default function VoiceAgent() { + const [transcript, setTranscript] = useState>([]); + + const { startConversation, stopConversation, status } = useConversation({ + agentId: process.env.EXPO_PUBLIC_ELEVENLABS_AGENT_ID!, + + // Use signed URL (most secure) + signedUrl: async () => { + const response = await fetch('https://your-api.com/elevenlabs/auth'); + const { signedUrl } = await response.json(); + return signedUrl; + }, + + clientTools: { + updateProfile: { + description: "Update user profile", + parameters: z.object({ + name: z.string() + }), + handler: async ({ name }) => { + console.log('Updating profile:', name); + return { success: true }; + } + } + }, + + onEvent: (event) => { + if (event.type === 'transcript') { + setTranscript(prev => [...prev, { role: 'user', text: event.data.text }]); + } else if (event.type === 'agent_response') { + setTranscript(prev => [...prev, { role: 'agent', text: event.data.text }]); + } + } + }); + + return ( + + Voice Agent + + + + + + + + {/* Status */} +
+

Status: {status}

+ {isSpeaking &&

Agent is speaking...

} +
+ + {/* Error */} + {error && ( +
+ Error: {error} +
+ )} + + {/* Transcript */} +
+

Transcript

+ + {transcript.length === 0 ? ( +

No conversation yet. Click "Start Conversation" to begin.

+ ) : ( + transcript.map((message, i) => ( +
+

+ {message.role === 'user' ? 'You' : 'Agent'} +

+

{message.text}

+
+ )) + )} +
+ + ); +} diff --git a/assets/swift-sdk-boilerplate.swift b/assets/swift-sdk-boilerplate.swift new file mode 100644 index 0000000..0a23162 --- /dev/null +++ b/assets/swift-sdk-boilerplate.swift @@ -0,0 +1,70 @@ +import SwiftUI +import ElevenLabs + +struct VoiceAgentView: View { + @State private var isConnected = false + @State private var transcript: [(role: String, text: String)] = [] + + private let agentID = "your-agent-id" + private let apiKey = "your-api-key" // Use environment variable in production + + var body: some View { + VStack { + Text("Voice Agent") + .font(.largeTitle) + .padding() + + HStack { + Button("Start Conversation") { + startConversation() + } + .disabled(isConnected) + + Button("Stop") { + stopConversation() + } + .disabled(!isConnected) + } + .padding() + + Text("Status: \(isConnected ? "Connected" : "Disconnected")") + .padding() + + ScrollView { + ForEach(transcript.indices, id: \.self) { index in + let message = transcript[index] + HStack { + VStack(alignment: .leading) { + Text(message.role == "user" ? "You" : "Agent") + .font(.caption) + .fontWeight(.bold) + Text(message.text) + } + .padding() + .background(message.role == "user" ? Color.blue.opacity(0.1) : Color.gray.opacity(0.1)) + .cornerRadius(8) + Spacer() + } + .padding(.horizontal) + } + } + } + } + + private func startConversation() { + // Initialize ElevenLabs conversation + // Implementation would use the ElevenLabs Swift SDK + isConnected = true + } + + private func stopConversation() { + isConnected = false + } +} + +#Preview { + VoiceAgentView() +} + +// Note: This is a placeholder. Full Swift SDK documentation available at: +// https://github.com/elevenlabs/elevenlabs-swift-sdk diff --git a/assets/system-prompt-template.md b/assets/system-prompt-template.md new file mode 100644 index 0000000..44ee183 --- /dev/null +++ b/assets/system-prompt-template.md @@ -0,0 +1,210 @@ +# System Prompt Template + +Use this template to create structured, effective agent prompts. + +--- + +## Personality +``` +You are [NAME], a [ROLE/PROFESSION] at [COMPANY]. +You have [YEARS] years of experience [DOING WHAT]. +Your key traits: [LIST 3-5 PERSONALITY TRAITS]. +``` + +**Example**: +``` +You are Sarah, a patient and knowledgeable technical support specialist at TechCorp. +You have 7 years of experience helping customers troubleshoot software issues. +Your key traits: patient, empathetic, detail-oriented, solution-focused, friendly. +``` + +--- + +## Environment +``` +You're communicating via [CHANNEL: phone/chat/video]. +Context: [ENVIRONMENTAL FACTORS]. +Communication style: [GUIDELINES]. +``` + +**Example**: +``` +You're speaking with customers over the phone. +Context: Background noise and poor connections are common. +Communication style: Speak clearly, use short sentences, pause occasionally for emphasis. +``` + +--- + +## Tone +``` +Formality: [PROFESSIONAL/CASUAL/FORMAL]. +Language: [CONTRACTIONS/JARGON GUIDELINES]. +Verbosity: [SENTENCE/RESPONSE LENGTH]. +Emotional Expression: [HOW TO EXPRESS EMPATHY/ENTHUSIASM]. +``` + +**Example**: +``` +Formality: Professional yet warm and approachable. +Language: Use contractions for natural conversation. Avoid jargon unless customer uses it first. +Verbosity: 2-3 sentences per response. Ask one question at a time. +Emotional Expression: Show empathy with phrases like "I understand how frustrating that must be." +``` + +--- + +## Goal +``` +Primary Goal: [MAIN OBJECTIVE] + +Secondary Goals: +- [SUPPORTING OBJECTIVE 1] +- [SUPPORTING OBJECTIVE 2] +- [SUPPORTING OBJECTIVE 3] + +Success Criteria: +- [MEASURABLE OUTCOME 1] +- [MEASURABLE OUTCOME 2] +``` + +**Example**: +``` +Primary Goal: Resolve customer technical issues on the first call. + +Secondary Goals: +- Verify customer identity securely +- Document issue details accurately +- Provide proactive tips to prevent future issues + +Success Criteria: +- Customer verbally confirms issue is resolved +- Issue documented in CRM +- Customer satisfaction β‰₯ 4/5 +``` + +--- + +## Guardrails +``` +Never: +- [PROHIBITED ACTION 1] +- [PROHIBITED ACTION 2] +- [PROHIBITED ACTION 3] + +Always: +- [REQUIRED ACTION 1] +- [REQUIRED ACTION 2] + +Escalate When: +- [ESCALATION TRIGGER 1] +- [ESCALATION TRIGGER 2] +``` + +**Example**: +``` +Never: +- Provide medical, legal, or financial advice +- Share confidential company information +- Make promises about refunds without verification +- Continue if customer becomes abusive + +Always: +- Verify customer identity before accessing account details +- Document all interactions +- Offer alternative solutions if first approach fails + +Escalate When: +- Customer requests manager +- Issue requires account credit/refund approval +- Technical issue beyond knowledge base +- Customer exhibits abusive behavior +``` + +--- + +## Tools +``` +Available Tools: + +1. tool_name(param1, param2) + Purpose: [WHAT IT DOES] + Use When: [TRIGGER CONDITION] + Example: [SAMPLE USAGE] + +2. ... + +Guidelines: +- Always explain to customer before calling tool +- Wait for tool response before continuing +- If tool fails, offer alternative +``` + +**Example**: +``` +Available Tools: + +1. lookup_order(order_id: string) + Purpose: Fetch order details from database + Use When: Customer mentions order number or asks about order status + Example: "Let me look that up for you. [Call lookup_order('ORD-12345')]" + +2. send_password_reset(email: string) + Purpose: Trigger password reset email + Use When: Customer can't access account and identity verified + Example: "I'll send a password reset email. [Call send_password_reset('user@example.com')]" + +3. transfer_to_supervisor() + Purpose: Escalate to human agent + Use When: Issue requires manager approval or customer explicitly requests + Example: "Let me connect you with a supervisor. [Call transfer_to_supervisor()]" + +Guidelines: +- Always explain what you're doing before calling tool +- Wait for tool response before continuing conversation +- If tool fails, acknowledge and offer alternative solution +``` + +--- + +## Complete Prompt + +Combine all sections into your final system prompt: + +``` +Personality: +You are [NAME], a [ROLE] at [COMPANY]. You have [EXPERIENCE]. Your traits: [TRAITS]. + +Environment: +You're communicating via [CHANNEL]. [CONTEXT]. [COMMUNICATION STYLE]. + +Tone: +[FORMALITY]. [LANGUAGE]. [VERBOSITY]. [EMOTIONAL EXPRESSION]. + +Goal: +Primary: [PRIMARY GOAL] +Secondary: [SECONDARY GOALS] +Success: [SUCCESS CRITERIA] + +Guardrails: +Never: [PROHIBITIONS] +Always: [REQUIREMENTS] +Escalate: [TRIGGERS] + +Tools: +[TOOL DESCRIPTIONS WITH EXAMPLES] +``` + +--- + +## Testing Your Prompt + +1. Create test scenarios covering common use cases +2. Run conversations and analyze transcripts +3. Check for: + - Tone consistency + - Goal achievement + - Guardrail adherence + - Tool usage accuracy +4. Iterate based on findings +5. Monitor analytics dashboard for real performance diff --git a/assets/widget-embed-template.html b/assets/widget-embed-template.html new file mode 100644 index 0000000..59a8014 --- /dev/null +++ b/assets/widget-embed-template.html @@ -0,0 +1,78 @@ + + + + + + ElevenLabs Voice Agent Widget + + +

Welcome to Our Support

+

Need help? Click the voice assistant button in the bottom-right corner!

+ + + + + + + + + diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..491b95c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,125 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jezweb/claude-skills:skills/elevenlabs-agents", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "799ad0048eddd949e159d5079bd98723c7c83a86", + "treeHash": "c33b4ac9169f56f6656d7a375536a10474750451e17493db80bf59934dcecc7e", + "generatedAt": "2025-11-28T10:19:02.870530Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "elevenlabs-agents", + "description": "Build conversational AI voice agents with ElevenLabs Platform using React, JavaScript, React Native, or Swift SDKs. Configure agents, tools (client/server/MCP), RAG knowledge bases, multi-voice, and Scribe real-time STT. Use when: building voice chat interfaces, implementing AI phone agents with Twilio, configuring agent workflows or tools, adding RAG knowledge bases, testing with CLI agents as code, or troubleshooting deprecated @11labs packages, Android audio cutoff, CSP violations, dynamic va", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "7a738c23198bdc7b22d80a41efeb73dedc6620031e56a88f616ce2c773e64fac" + }, + { + "path": "SKILL.md", + "sha256": "e3d13197550d228b52a12b67b88c954be6f673c8f8632d5d59864234e3e9cee9" + }, + { + "path": "references/cost-optimization.md", + "sha256": "0b8bba82aea1132fd32f1f641a425f5c29d0e671780379f359751f315af984e3" + }, + { + "path": "references/system-prompt-guide.md", + "sha256": "b7cb12ec838532ddf23750907f81a3cb074237a9ff86610e9503a96cd2893175" + }, + { + "path": "references/cli-commands.md", + "sha256": "e572d52139ff613c2e8b014d3702333127c99833fe2fdb78282fa3ecd745504c" + }, + { + "path": "references/compliance-guide.md", + "sha256": "57ad846c52b99829ff2c9fe8f3487021c758cea83327a5ba6d84820e7ab04242" + }, + { + "path": "references/testing-guide.md", + "sha256": "23ff831a472080e8c4b0ddbd5897b018909c2a5a31bbbb3ee3d20668346e34c8" + }, + { + "path": "references/workflow-examples.md", + "sha256": "ade5909e4c37fb574acead086181702c23fe1c4c796a01627dfdb0b007567a71" + }, + { + "path": "references/tool-examples.md", + "sha256": "448239060b5c89acae1cb30dcdcbf27783a08344801f2c57e55f6cdbd7f450de" + }, + { + "path": "references/api-reference.md", + "sha256": "e8ca6b215f8854696919e5d28d464ab7958c5cabad78721207ce18327a45085d" + }, + { + "path": "scripts/test-agent.sh", + "sha256": "fd3b7e7f8e347d06c899d0bea2b6ab9464a76c6e9284890245f5c93a13b0d051" + }, + { + "path": "scripts/deploy-agent.sh", + "sha256": "aa30e299d4db74ecfecffad5d088918ee21607c2a38c512c30e23b72eea9d680" + }, + { + "path": "scripts/create-agent.sh", + "sha256": "103e8cbb95e7b75053585cbfc93ca01f98f3a4953521412fb9876d670a785b2d" + }, + { + "path": "scripts/simulate-conversation.sh", + "sha256": "a8eb469088a969f9186ba6ffe83551040bb14627123817cf4b297290834151c5" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "b844509e8c6225e29536ad2e9d6059a0aecd474b77bb59be7c7997d2a57f3350" + }, + { + "path": "assets/agent-config-schema.json", + "sha256": "d46b74c9896a0f4c73a62eddb2d470e2b80d0ac6cccb7713405c1e3ac9b8c408" + }, + { + "path": "assets/react-native-boilerplate.tsx", + "sha256": "fcc88f1253a023ea23dc7f2d47733bce25dd1ee50d2e9d480396eb4c8b5c781d" + }, + { + "path": "assets/widget-embed-template.html", + "sha256": "e9f76b2f5b962b2e9aa4b839a97836fa7ebd1d3b99c4d5f465c913888009e4a4" + }, + { + "path": "assets/react-sdk-boilerplate.tsx", + "sha256": "83e08e4a943e636294e8666301e05a4efb7464d27165a9bd85a967cbf8b2953b" + }, + { + "path": "assets/system-prompt-template.md", + "sha256": "b1e92c088d9a8a2a517d093b6d4444d030141c4504bb85bbbb237bc2a8ed1eac" + }, + { + "path": "assets/ci-cd-example.yml", + "sha256": "84ddf10354ce34fd1caa19c4e7b58cee2b154e616c259cce34aedf98c53192e1" + }, + { + "path": "assets/javascript-sdk-boilerplate.js", + "sha256": "9f7a0aa5147a52ec43a08a43fbb161a23cafeadec9ef15d9cd667ab1ba298982" + }, + { + "path": "assets/swift-sdk-boilerplate.swift", + "sha256": "2b013f0c9eb369fb1689a92f23feed280c427563381964426291827f783924e5" + } + ], + "dirSha256": "c33b4ac9169f56f6656d7a375536a10474750451e17493db80bf59934dcecc7e" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/api-reference.md b/references/api-reference.md new file mode 100644 index 0000000..03b4493 --- /dev/null +++ b/references/api-reference.md @@ -0,0 +1,413 @@ +# ElevenLabs Agents API Reference + +## Base URL + +``` +https://api.elevenlabs.io/v1/convai +``` + +## Authentication + +All requests require an API key in the header: + +```bash +curl -H "xi-api-key: YOUR_API_KEY" https://api.elevenlabs.io/v1/convai/agents +``` + +--- + +## Agents + +### Create Agent + +**Endpoint**: `POST /agents/create` + +**Request Body**: +```json +{ + "name": "Support Agent", + "conversation_config": { + "agent": { + "prompt": { + "prompt": "You are a helpful support agent.", + "llm": "gpt-4o", + "temperature": 0.7, + "max_tokens": 500, + "tool_ids": ["tool_123"], + "knowledge_base": ["doc_456"] + }, + "first_message": "Hello! How can I help?", + "language": "en" + }, + "tts": { + "model_id": "eleven_turbo_v2_5", + "voice_id": "voice_abc123", + "stability": 0.5, + "similarity_boost": 0.75, + "speed": 1.0 + }, + "asr": { + "quality": "high", + "provider": "deepgram" + }, + "turn": { + "mode": "normal" + } + } +} +``` + +**Response**: +```json +{ + "agent_id": "agent_abc123", + "name": "Support Agent", + "created_at": "2025-11-03T12:00:00Z" +} +``` + +### Update Agent + +**Endpoint**: `PATCH /agents/:agent_id` + +**Request Body**: Same as Create Agent + +### Get Agent + +**Endpoint**: `GET /agents/:agent_id` + +**Response**: +```json +{ + "agent_id": "agent_abc123", + "name": "Support Agent", + "conversation_config": { ... }, + "created_at": "2025-11-03T12:00:00Z", + "updated_at": "2025-11-03T14:00:00Z" +} +``` + +### List Agents + +**Endpoint**: `GET /agents` + +**Response**: +```json +{ + "agents": [ + { + "agent_id": "agent_abc123", + "name": "Support Agent", + "created_at": "2025-11-03T12:00:00Z" + } + ] +} +``` + +### Delete Agent + +**Endpoint**: `DELETE /agents/:agent_id` + +**Response**: +```json +{ + "success": true +} +``` + +--- + +## Conversations + +### Create Conversation + +**Endpoint**: `POST /conversations/create` + +**Request Body**: +```json +{ + "agent_id": "agent_abc123", + "dynamic_variables": { + "user_name": "John", + "account_tier": "premium" + }, + "overrides": { + "agent": { + "prompt": { + "prompt": "Custom prompt override" + } + } + } +} +``` + +**Response**: +```json +{ + "conversation_id": "conv_xyz789", + "signed_url": "wss://api.elevenlabs.io/v1/convai/...", + "created_at": "2025-11-03T12:00:00Z" +} +``` + +### Get Conversation + +**Endpoint**: `GET /conversations/:conversation_id` + +**Response**: +```json +{ + "conversation_id": "conv_xyz789", + "agent_id": "agent_abc123", + "transcript": "...", + "duration_seconds": 120, + "status": "completed", + "created_at": "2025-11-03T12:00:00Z", + "ended_at": "2025-11-03T12:02:00Z" +} +``` + +--- + +## Knowledge Base + +### Upload Document + +**Endpoint**: `POST /knowledge-base/upload` + +**Request Body** (multipart/form-data): +``` +file: +name: "Support Documentation" +``` + +**Response**: +```json +{ + "document_id": "doc_456", + "name": "Support Documentation", + "status": "processing" +} +``` + +### Compute RAG Index + +**Endpoint**: `POST /knowledge-base/:document_id/rag-index` + +**Request Body**: +```json +{ + "embedding_model": "e5_mistral_7b" +} +``` + +**Response**: +```json +{ + "document_id": "doc_456", + "status": "computing" +} +``` + +### Get RAG Index Status + +**Endpoint**: `GET /knowledge-base/:document_id/rag-index` + +**Response**: +```json +{ + "document_id": "doc_456", + "status": "ready", + "embedding_model": "e5_mistral_7b", + "created_at": "2025-11-03T12:00:00Z" +} +``` + +--- + +## Tools + +### Create Webhook Tool + +**Endpoint**: `POST /tools/webhook` + +**Request Body**: +```json +{ + "name": "get_weather", + "description": "Fetch current weather for a city", + "url": "https://api.weather.com/v1/current", + "method": "GET", + "parameters": { + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "City name" + } + }, + "required": ["city"] + }, + "headers": { + "Authorization": "Bearer {{secret__weather_api_key}}" + } +} +``` + +**Response**: +```json +{ + "tool_id": "tool_123", + "name": "get_weather", + "created_at": "2025-11-03T12:00:00Z" +} +``` + +--- + +## Testing + +### Simulate Conversation + +**Endpoint**: `POST /agents/:agent_id/simulate` + +**Request Body**: +```json +{ + "scenario": "Customer requests refund", + "user_messages": [ + "I want a refund for order #12345", + "I ordered it last week" + ], + "success_criteria": [ + "Agent acknowledges request", + "Agent provides timeline" + ] +} +``` + +**Response**: +```json +{ + "simulation_id": "sim_123", + "passed": true, + "transcript": "...", + "evaluation": { + "criteria_met": 2, + "criteria_total": 2, + "details": [ + { + "criterion": "Agent acknowledges request", + "passed": true + }, + { + "criterion": "Agent provides timeline", + "passed": true + } + ] + } +} +``` + +--- + +## Error Codes + +| Code | Meaning | Solution | +|------|---------|----------| +| 400 | Bad Request | Check request body format | +| 401 | Unauthorized | Verify API key is correct | +| 403 | Forbidden | Check agent visibility settings | +| 404 | Not Found | Verify resource ID exists | +| 429 | Rate Limited | Implement backoff strategy | +| 500 | Server Error | Retry with exponential backoff | + +--- + +## Rate Limits + +- **Standard Tier**: 100 requests/minute +- **Pro Tier**: 500 requests/minute +- **Enterprise Tier**: Custom limits + +**Rate Limit Headers**: +``` +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 95 +X-RateLimit-Reset: 1730640000 +``` + +--- + +## Pagination + +**Query Parameters**: +``` +?page=1&per_page=50 +``` + +**Response Headers**: +``` +X-Total-Count: 250 +X-Page: 1 +X-Per-Page: 50 +``` + +--- + +## Webhook Events + +### Post-Call Webhook + +**Event Type**: `post_call_transcription` + +**Payload**: +```json +{ + "type": "post_call_transcription", + "data": { + "conversation_id": "conv_xyz789", + "agent_id": "agent_abc123", + "transcript": "...", + "duration_seconds": 120, + "analysis": { + "sentiment": "positive", + "resolution": true, + "extracted_data": {} + } + }, + "event_timestamp": "2025-11-03T12:02:00Z" +} +``` + +**Verification** (HMAC SHA-256): +```typescript +import crypto from 'crypto'; + +const signature = request.headers['elevenlabs-signature']; +const payload = JSON.stringify(request.body); + +const hmac = crypto + .createHmac('sha256', process.env.WEBHOOK_SECRET) + .update(payload) + .digest('hex'); + +if (signature !== hmac) { + // Invalid signature +} +``` + +--- + +## SDK vs API + +| Feature | SDK | API | +|---------|-----|-----| +| WebSocket Connection | βœ… | ❌ | +| Client Tools | βœ… | ❌ | +| Real-time Events | βœ… | ❌ | +| Agent Management | ❌ | βœ… | +| Tool Management | ❌ | βœ… | +| Knowledge Base | ❌ | βœ… | + +**Recommendation**: Use SDK for conversations, API for agent management. diff --git a/references/cli-commands.md b/references/cli-commands.md new file mode 100644 index 0000000..c26e8c7 --- /dev/null +++ b/references/cli-commands.md @@ -0,0 +1,274 @@ +# CLI Commands Reference + +## Installation + +```bash +npm install -g @elevenlabs/cli +# or +pnpm install -g @elevenlabs/cli +``` + +--- + +## Authentication + +### Login +```bash +elevenlabs auth login +``` + +### Check Current User +```bash +elevenlabs auth whoami +``` + +### Set Residency +```bash +elevenlabs auth residency eu-residency +# Options: global | eu-residency | in-residency +``` + +### Logout +```bash +elevenlabs auth logout +``` + +--- + +## Project Initialization + +### Initialize New Project +```bash +elevenlabs agents init +``` + +### Recreate Project Structure +```bash +elevenlabs agents init --override +``` + +--- + +## Agent Management + +### Add Agent +```bash +elevenlabs agents add "Agent Name" --template TEMPLATE +``` + +**Templates**: default | minimal | voice-only | text-only | customer-service | assistant + +### Push to Platform +```bash +# Push all agents +elevenlabs agents push + +# Push specific agent +elevenlabs agents push --agent "Agent Name" + +# Push to environment +elevenlabs agents push --env prod + +# Dry run (preview changes) +elevenlabs agents push --dry-run +``` + +### Pull from Platform +```bash +# Pull all agents +elevenlabs agents pull + +# Pull specific agent +elevenlabs agents pull --agent "Agent Name" +``` + +### List Agents +```bash +elevenlabs agents list +``` + +### Check Sync Status +```bash +elevenlabs agents status +``` + +### Delete Agent +```bash +elevenlabs agents delete AGENT_ID +``` + +### Generate Widget +```bash +elevenlabs agents widget "Agent Name" +``` + +--- + +## Tool Management + +### Add Webhook Tool +```bash +elevenlabs tools add-webhook "Tool Name" --config-path tool_configs/tool.json +``` + +### Add Client Tool +```bash +elevenlabs tools add-client "Tool Name" --config-path tool_configs/tool.json +``` + +### Push Tools +```bash +elevenlabs tools push +``` + +### Pull Tools +```bash +elevenlabs tools pull +``` + +### Delete Tool +```bash +elevenlabs tools delete TOOL_ID + +# Delete all tools +elevenlabs tools delete --all +``` + +--- + +## Testing + +### Add Test +```bash +elevenlabs tests add "Test Name" --template basic-llm +``` + +### Push Tests +```bash +elevenlabs tests push +``` + +### Pull Tests +```bash +elevenlabs tests pull +``` + +### Run Test +```bash +elevenlabs agents test "Agent Name" +``` + +--- + +## Multi-Environment Workflow + +```bash +# Development +elevenlabs agents push --env dev + +# Staging +elevenlabs agents push --env staging + +# Production +elevenlabs agents push --env prod --dry-run +# Review changes... +elevenlabs agents push --env prod +``` + +--- + +## Common Workflows + +### Create and Deploy Agent +```bash +elevenlabs auth login +elevenlabs agents init +elevenlabs agents add "Support Bot" --template customer-service +# Edit agent_configs/support-bot.json +elevenlabs agents push --env dev +elevenlabs agents test "Support Bot" +elevenlabs agents push --env prod +``` + +### Update Existing Agent +```bash +elevenlabs agents pull +# Edit agent_configs/agent-name.json +elevenlabs agents push --dry-run +elevenlabs agents push +``` + +### Promote Agent to Production +```bash +# Test in staging first +elevenlabs agents push --env staging +elevenlabs agents test "Agent Name" + +# If tests pass, promote to prod +elevenlabs agents push --env prod +``` + +--- + +## Environment Variables + +```bash +# For CI/CD +export ELEVENLABS_API_KEY=your-api-key + +# Run commands +elevenlabs agents push --env prod +``` + +--- + +## Troubleshooting + +### Reset Project +```bash +elevenlabs agents init --override +elevenlabs agents pull +``` + +### Check Version +```bash +elevenlabs --version +``` + +### Get Help +```bash +elevenlabs --help +elevenlabs agents --help +elevenlabs tools --help +``` + +--- + +## File Locations + +### Config Files +``` +~/.elevenlabs/api_key # API key (if not using keychain) +``` + +### Project Files +``` +./agents.json # Agent registry +./tools.json # Tool registry +./tests.json # Test registry +./agent_configs/*.json # Individual agent configs +./tool_configs/*.json # Individual tool configs +./test_configs/*.json # Individual test configs +``` + +--- + +## Best Practices + +1. **Always use --dry-run** before pushing to production +2. **Commit configs to Git** for version control +3. **Use environment-specific configs** (dev/staging/prod) +4. **Test agents** before deploying +5. **Pull before editing** to avoid conflicts +6. **Use templates** for consistency +7. **Document changes** in commit messages diff --git a/references/compliance-guide.md b/references/compliance-guide.md new file mode 100644 index 0000000..aec406e --- /dev/null +++ b/references/compliance-guide.md @@ -0,0 +1,227 @@ +# Privacy & Compliance Guide + +## GDPR Compliance + +### Data Retention +**Default**: 2 years (730 days) + +```json +{ + "privacy": { + "transcripts": { + "retention_days": 730 + }, + "audio": { + "retention_days": 730 + } + } +} +``` + +### Right to Be Forgotten +Enable data deletion requests: +```typescript +await client.conversations.delete(conversation_id); +``` + +### Data Residency +```typescript +const { startConversation } = useConversation({ + serverLocation: 'eu-residency' // GDPR-compliant EU data centers +}); +``` + +### User Consent +Inform users before recording: +```json +{ + "first_message": "This call will be recorded for quality and training purposes. Do you consent?" +} +``` + +--- + +## HIPAA Compliance + +### Data Retention +**Minimum**: 6 years (2190 days) + +```json +{ + "privacy": { + "transcripts": { + "retention_days": 2190 + }, + "audio": { + "retention_days": 2190 + } + } +} +``` + +### Encryption +- **In Transit**: TLS 1.3 (automatic) +- **At Rest**: AES-256 (automatic) + +### Business Associate Agreement (BAA) +Contact ElevenLabs for HIPAA BAA. + +### PHI Handling +**Never**: +- Store PHI in dynamic variables +- Log PHI in tool parameters +- Send PHI to third-party tools without BAA + +**Always**: +- Use secure authentication +- Verify patient identity +- Document access logs + +--- + +## SOC 2 Compliance + +### Security Controls +βœ… Encryption in transit and at rest (automatic) +βœ… Access controls (API key management) +βœ… Audit logs (conversation history) +βœ… Incident response (automatic backups) + +### Best Practices +```json +{ + "authentication": { + "type": "signed_url", // Most secure + "session_duration": 3600 // 1 hour max + } +} +``` + +--- + +## Regional Compliance + +### US Residency +```typescript +serverLocation: 'us' +``` + +### EU Residency (GDPR) +```typescript +serverLocation: 'eu-residency' +``` + +### India Residency +```typescript +serverLocation: 'in-residency' +``` + +--- + +## Zero Retention Mode + +**Maximum Privacy**: Immediately delete all data after conversation ends. + +```json +{ + "privacy": { + "zero_retention": true + } +} +``` + +**Limitations**: +- No conversation history +- No analytics +- No post-call webhooks +- No MCP tool integrations + +--- + +## PCI DSS (Payment Card Industry) + +### Never: +❌ Store credit card numbers in conversation logs +❌ Send credit card data to LLM +❌ Log CVV or PIN numbers + +### Always: +βœ… Use PCI-compliant payment processors (Stripe, PayPal) +βœ… Tokenize payment data +βœ… Use DTMF keypad for card entry (telephony) + +### Example: Secure Payment Collection +```json +{ + "system_tools": [ + { + "name": "dtmf_playpad", + "description": "Display keypad for secure card entry" + } + ] +} +``` + +--- + +## Compliance Checklist + +### GDPR +- [ ] Data retention ≀ 2 years (or justify longer) +- [ ] EU data residency enabled +- [ ] User consent obtained before recording +- [ ] Data deletion process implemented +- [ ] Privacy policy updated + +### HIPAA +- [ ] Data retention β‰₯ 6 years +- [ ] BAA signed with ElevenLabs +- [ ] Encryption enabled (automatic) +- [ ] Access logs maintained +- [ ] Staff trained on PHI handling + +### SOC 2 +- [ ] API key security (never expose in client) +- [ ] Use signed URLs for authentication +- [ ] Monitor access logs +- [ ] Incident response plan documented + +### PCI DSS +- [ ] Never log card data +- [ ] Use tokenization for payments +- [ ] DTMF keypad for card entry +- [ ] PCI-compliant payment processor + +--- + +## Monitoring & Auditing + +### Access Logs +```typescript +const logs = await client.conversations.list({ + agent_id: 'agent_123', + from_date: '2025-01-01', + to_date: '2025-12-31' +}); +``` + +### Compliance Reports +- Monthly conversation volume +- Data retention adherence +- Security incidents +- User consent rates + +--- + +## Incident Response + +### Data Breach Protocol +1. Identify affected conversations +2. Notify ElevenLabs immediately +3. Delete compromised data +4. Notify affected users (GDPR requirement) +5. Document incident +6. Review security controls + +### Contact +security@elevenlabs.io diff --git a/references/cost-optimization.md b/references/cost-optimization.md new file mode 100644 index 0000000..a64d085 --- /dev/null +++ b/references/cost-optimization.md @@ -0,0 +1,275 @@ +# Cost Optimization Guide + +## 1. LLM Caching + +### How It Works +- **First request**: Full cost (`input_cache_write`) +- **Subsequent requests**: 10% cost (`input_cache_read`) +- **Cache TTL**: 5 minutes to 1 hour (configurable) + +### Configuration +```json +{ + "llm_config": { + "caching": { + "enabled": true, + "ttl_seconds": 3600 + } + } +} +``` + +### What Gets Cached +βœ… System prompts +βœ… Tool definitions +βœ… Knowledge base context +βœ… Recent conversation history + +❌ User messages (always fresh) +❌ Dynamic variables +❌ Tool responses + +### Savings +**Up to 90%** on cached inputs + +**Example**: +- System prompt: 500 tokens +- Without caching: 500 tokens Γ— 100 conversations = 50,000 tokens +- With caching: 500 tokens (first) + 50 tokens Γ— 99 (cached) = 5,450 tokens +- **Savings**: 89% + +--- + +## 2. Model Swapping + +### Model Comparison + +| Model | Cost (per 1M tokens) | Speed | Quality | Best For | +|-------|---------------------|-------|---------|----------| +| GPT-4o | $5 | Medium | Highest | Complex reasoning | +| GPT-4o-mini | $0.15 | Fast | High | Most use cases | +| Claude Sonnet 4.5 | $3 | Medium | Highest | Long context | +| Gemini 2.5 Flash | $0.075 | Fastest | Medium | Simple tasks | + +### Configuration +```json +{ + "llm_config": { + "model": "gpt-4o-mini" + } +} +``` + +### Optimization Strategy +1. **Start with gpt-4o-mini** for all agents +2. **Upgrade to gpt-4o** only if: + - Complex reasoning required + - High accuracy critical + - User feedback indicates quality issues +3. **Use Gemini 2.5 Flash** for: + - Simple routing/classification + - FAQ responses + - Order status lookups + +### Savings +**Up to 97%** (gpt-4o β†’ Gemini 2.5 Flash) + +--- + +## 3. Burst Pricing + +### How It Works +- **Normal**: Your subscription concurrency limit (e.g., 10 calls) +- **Burst**: Up to 3Γ— your limit (e.g., 30 calls) +- **Cost**: 2Γ— per-minute rate for burst calls + +### Configuration +```json +{ + "call_limits": { + "burst_pricing_enabled": true + } +} +``` + +### When to Use +βœ… Black Friday traffic spikes +βœ… Product launches +βœ… Seasonal demand (holidays) +βœ… Marketing campaigns + +❌ Sustained high traffic (upgrade plan instead) +❌ Unpredictable usage patterns + +### Cost Calculation +**Example**: +- Subscription: 10 concurrent calls ($0.10/min per call) +- Traffic spike: 25 concurrent calls +- Burst calls: 25 - 10 = 15 calls +- Burst cost: 15 Γ— $0.20/min = $3/min +- Regular cost: 10 Γ— $0.10/min = $1/min +- **Total**: $4/min during spike + +--- + +## 4. Prompt Optimization + +### Reduce Token Count + +**Before** (500 tokens): +``` +You are a highly experienced and knowledgeable customer support specialist with extensive training in technical troubleshooting, customer service best practices, and empathetic communication. You should always maintain a professional yet friendly demeanor while helping customers resolve their issues efficiently and effectively. +``` + +**After** (150 tokens): +``` +You are an experienced support specialist. Be professional, friendly, and efficient. +``` + +**Savings**: 70% token reduction + +### Use Tools Instead of Context + +**Before**: Include FAQ in system prompt (2,000 tokens) +**After**: Use RAG/knowledge base (100 tokens + retrieval) + +**Savings**: 95% for large knowledge bases + +--- + +## 5. Turn-Taking Optimization + +### Impact on Cost + +| Mode | Latency | LLM Calls | Cost Impact | +|------|---------|-----------|-------------| +| Eager | Low | More | Higher (more interruptions) | +| Normal | Medium | Medium | Balanced | +| Patient | High | Fewer | Lower (fewer interruptions) | + +### Recommendation +Use **Patient** mode for cost-sensitive applications where speed is less critical. + +--- + +## 6. Voice Settings + +### Speed vs Cost + +| Speed | TTS Cost | User Experience | +|-------|----------|-----------------| +| 0.7x | Higher (longer audio) | Slow | +| 1.0x | Baseline | Natural | +| 1.2x | Lower (shorter audio) | Fast | + +### Recommendation +Use **1.1x speed** for slight cost savings without compromising experience. + +--- + +## 7. Conversation Duration Limits + +### Configuration +```json +{ + "conversation": { + "max_duration_seconds": 300 // 5 minutes + } +} +``` + +### Use Cases +- FAQ bots (limit: 2-3 minutes) +- Order status (limit: 1 minute) +- Full support (limit: 10-15 minutes) + +### Savings +Prevents unexpectedly long conversations. + +--- + +## 8. Analytics-Driven Optimization + +### Monitor Metrics +1. **Average conversation duration** +2. **LLM tokens per conversation** +3. **Tool call frequency** +4. **Resolution rate** + +### Identify Issues +- Long conversations β†’ improve prompts or add escalation +- High token count β†’ enable caching or shorten prompts +- Low resolution rate β†’ upgrade model or improve knowledge base + +--- + +## 9. Cost Monitoring + +### API Usage Tracking +```typescript +const usage = await client.analytics.getLLMUsage({ + agent_id: 'agent_123', + from_date: '2025-11-01', + to_date: '2025-11-30' +}); + +console.log('Total tokens:', usage.total_tokens); +console.log('Cached tokens:', usage.cached_tokens); +console.log('Cost:', usage.total_cost); +``` + +### Set Budgets +```json +{ + "cost_limits": { + "daily_budget_usd": 100, + "monthly_budget_usd": 2000 + } +} +``` + +--- + +## 10. Cost Optimization Checklist + +### Before Launch +- [ ] Enable LLM caching +- [ ] Use gpt-4o-mini (not gpt-4o) +- [ ] Optimize prompt length +- [ ] Set conversation duration limits +- [ ] Use RAG instead of large system prompts +- [ ] Configure burst pricing if needed + +### During Operation +- [ ] Monitor LLM token usage weekly +- [ ] Review conversation analytics monthly +- [ ] Test cheaper models quarterly +- [ ] Optimize prompts based on analytics +- [ ] Review and remove unused tools + +### Continuous Improvement +- [ ] A/B test cheaper models +- [ ] Analyze long conversations +- [ ] Improve resolution rates +- [ ] Reduce average conversation duration +- [ ] Increase cache hit rates + +--- + +## Expected Savings + +**Baseline Configuration**: +- Model: gpt-4o +- No caching +- Average prompt: 1,000 tokens +- Average conversation: 5 minutes +- Cost: ~$0.50/conversation + +**Optimized Configuration**: +- Model: gpt-4o-mini +- Caching enabled +- Average prompt: 300 tokens +- Average conversation: 3 minutes +- Cost: ~$0.05/conversation + +**Total Savings**: **90%** πŸŽ‰ diff --git a/references/system-prompt-guide.md b/references/system-prompt-guide.md new file mode 100644 index 0000000..f86a33a --- /dev/null +++ b/references/system-prompt-guide.md @@ -0,0 +1,276 @@ +# System Prompt Engineering Guide + +## 6-Component Framework + +### 1. Personality +Define who the agent is. + +**Template**: +``` +You are [NAME], a [ROLE/PROFESSION] at [COMPANY]. +You have [EXPERIENCE/BACKGROUND]. +Your traits: [LIST PERSONALITY TRAITS]. +``` + +**Example**: +``` +You are Sarah, a patient and knowledgeable technical support specialist at TechCorp. +You have 7 years of experience helping customers troubleshoot software issues. +Your traits: patient, empathetic, detail-oriented, solution-focused. +``` + +### 2. Environment +Describe the communication context. + +**Template**: +``` +You're communicating via [CHANNEL: phone/chat/video]. +Consider [ENVIRONMENTAL FACTORS]. +Adapt your communication style to [CONTEXT]. +``` + +**Example**: +``` +You're speaking with customers over the phone. +Background noise and poor connections are common. +Speak clearly, use short sentences, and occasionally pause for emphasis. +``` + +### 3. Tone +Specify speech patterns and formality. + +**Template**: +``` +Tone: [FORMALITY LEVEL]. +Language: [CONTRACTIONS/JARGON GUIDELINES]. +Verbosity: [SENTENCE LENGTH, RESPONSE LENGTH]. +Emotional Expression: [GUIDELINES]. +``` + +**Example**: +``` +Tone: Professional yet warm and approachable. +Language: Use contractions ("I'm", "let's") for natural conversation. Avoid technical jargon unless the customer uses it first. +Verbosity: Keep responses to 2-3 sentences. Ask one question at a time. +Emotional Expression: Express empathy with phrases like "I understand how frustrating that must be." +``` + +### 4. Goal +Define objectives and success criteria. + +**Template**: +``` +Primary Goal: [MAIN OBJECTIVE] + +Secondary Goals: +- [SUPPORTING OBJECTIVE 1] +- [SUPPORTING OBJECTIVE 2] + +Success Criteria: +- [MEASURABLE OUTCOME 1] +- [MEASURABLE OUTCOME 2] +``` + +**Example**: +``` +Primary Goal: Resolve customer technical issues on the first call. + +Secondary Goals: +- Verify customer identity securely +- Document issue details accurately +- Provide proactive tips to prevent future issues + +Success Criteria: +- Customer verbally confirms their issue is resolved +- Issue documented in CRM system +- Customer satisfaction score β‰₯ 4/5 +``` + +### 5. Guardrails +Set boundaries and ethical constraints. + +**Template**: +``` +Never: +- [PROHIBITED ACTION 1] +- [PROHIBITED ACTION 2] + +Always: +- [REQUIRED ACTION 1] +- [REQUIRED ACTION 2] + +Escalation Triggers: +- [CONDITION REQUIRING HUMAN INTERVENTION] +``` + +**Example**: +``` +Never: +- Provide medical, legal, or financial advice +- Share confidential company information +- Make promises about refunds without verification +- Continue conversation if customer becomes abusive + +Always: +- Verify customer identity before accessing account details +- Document all interactions in CRM +- Offer alternative solutions if first approach doesn't work + +Escalation Triggers: +- Customer requests manager +- Issue requires account credit/refund approval +- Technical issue beyond your knowledge base +- Customer exhibits abusive behavior +``` + +### 6. Tools +Describe available functions and when to use them. + +**Template**: +``` +Available Tools: + +1. tool_name(parameters) + Purpose: [WHAT IT DOES] + Use When: [TRIGGER CONDITION] + Example: [SAMPLE USAGE] + +2. ... + +Guidelines: +- [GENERAL TOOL USAGE RULES] +``` + +**Example**: +``` +Available Tools: + +1. lookup_order(order_id: string) + Purpose: Fetch order details from database + Use When: Customer mentions an order number or asks about order status + Example: "Let me look that up for you. [Call lookup_order(order_id='ORD-12345')]" + +2. send_password_reset(email: string) + Purpose: Trigger password reset email + Use When: Customer can't access account and identity is verified + Example: "I'll send you a password reset email. [Call send_password_reset(email='customer@example.com')]" + +3. transfer_to_supervisor() + Purpose: Escalate to human agent + Use When: Issue requires manager approval or customer explicitly requests + Example: "Let me connect you with a supervisor. [Call transfer_to_supervisor()]" + +Guidelines: +- Always explain to the customer what you're doing before calling a tool +- Wait for tool response before continuing +- If tool fails, acknowledge and offer alternative +``` + +--- + +## Complete Example Templates + +### Customer Support Agent +``` +Personality: +You are Alex, a friendly and knowledgeable customer support specialist at TechCorp. You have 5 years of experience helping customers solve technical issues. You're patient, empathetic, and always maintain a positive attitude. + +Environment: +You're speaking with customers over the phone. Communication is voice-only. Customers may have background noise or poor connection quality. Speak clearly and use thoughtful pauses for emphasis. + +Tone: +Professional yet warm. Use contractions ("I'm", "let's") to sound natural. Avoid jargon unless the customer uses it first. Keep responses concise (2-3 sentences max). Use encouraging phrases like "I'll be happy to help with that." + +Goal: +Primary: Resolve customer technical issues on the first call. +Secondary: Verify customer identity, document issues accurately, provide proactive solutions. +Success: Customer verbally confirms issue is resolved. + +Guardrails: +- Never provide medical/legal/financial advice +- Don't share confidential company information +- Escalate if customer becomes abusive +- Never make promises about refunds without verification + +Tools: +1. lookup_order(order_id) - Fetch order details when customer mentions order number +2. transfer_to_supervisor() - Escalate when issue requires manager approval +3. send_password_reset(email) - Trigger reset when customer can't access account +Always explain what you're doing before calling tools. +``` + +### Educational Tutor +``` +Personality: +You are Maya, a patient and encouraging math tutor. You have 10 years of experience teaching middle school students. You're enthusiastic about learning and celebrate every small victory. + +Environment: +You're tutoring students via voice chat. Students may feel anxious or frustrated about math. Create a safe, judgment-free environment where mistakes are learning opportunities. + +Tone: +Warm, encouraging, and patient. Never sound frustrated or disappointed. Use positive reinforcement frequently ("Great thinking!", "You're on the right track!"). Adjust complexity based on student's responses. + +Goal: +Primary: Help students understand math concepts, not just get answers. +Secondary: Build confidence and reduce math anxiety. +Success: Student can explain the concept in their own words and solve similar problems independently. + +Guardrails: +- Never give answers directlyβ€”guide students to discover solutions +- Don't move to next topic until current concept is mastered +- If student becomes frustrated, take a break or switch to easier problem +- Never compare students or use negative language + +Tools: +1. show_visual_aid(concept) - Display diagram or graph to illustrate concept +2. generate_practice_problem(difficulty) - Create custom practice problem +3. celebrate_achievement() - Play positive feedback animation +Always make learning feel like an achievement, not a chore. +``` + +--- + +## Prompt Engineering Tips + +### Do's: +βœ… Use specific examples in guidelines +βœ… Define success criteria clearly +βœ… Include escalation conditions +βœ… Explain tool usage thoroughly +βœ… Test prompts with real conversations +βœ… Iterate based on analytics + +### Don'ts: +❌ Use overly long prompts (increases cost) +❌ Be vague about goals or boundaries +❌ Include conflicting instructions +❌ Forget to test edge cases +❌ Use negative language excessively +❌ Overcomplicate simple tasks + +--- + +## Testing Your Prompts + +1. **Scenario Testing**: Run automated tests with success criteria +2. **Edge Case Testing**: Test boundary conditions and unusual inputs +3. **Tone Testing**: Evaluate conversation tone and empathy +4. **Tool Testing**: Verify tools are called correctly +5. **Analytics Review**: Monitor real conversations for issues + +--- + +## Prompt Iteration Workflow + +``` +1. Write initial prompt using 6-component framework +2. Deploy to dev environment +3. Run 5-10 test conversations +4. Analyze transcripts for issues +5. Refine prompt based on findings +6. Deploy to staging +7. Run automated tests +8. Review analytics dashboard +9. Deploy to production +10. Monitor and iterate +``` diff --git a/references/testing-guide.md b/references/testing-guide.md new file mode 100644 index 0000000..99a7b74 --- /dev/null +++ b/references/testing-guide.md @@ -0,0 +1,188 @@ +# Testing Guide + +## 1. Scenario Testing (LLM-Based) + +### Create Test +```bash +elevenlabs tests add "Refund Request" --template basic-llm +``` + +### Test Configuration +```json +{ + "name": "Refund Request Test", + "scenario": "Customer requests refund for defective product", + "user_input": "I want a refund for order #12345. The product arrived broken.", + "success_criteria": [ + "Agent acknowledges the issue empathetically", + "Agent asks for order number or uses provided number", + "Agent verifies order details", + "Agent provides clear next steps or refund timeline" + ], + "evaluation_type": "llm" +} +``` + +### Run Test +```bash +elevenlabs agents test "Support Agent" +``` + +## 2. Tool Call Testing + +### Test Configuration +```json +{ + "name": "Order Lookup Test", + "scenario": "Customer asks about order status", + "user_input": "What's the status of order ORD-12345?", + "expected_tool_call": { + "tool_name": "lookup_order", + "parameters": { + "order_id": "ORD-12345" + } + } +} +``` + +## 3. Load Testing + +### Basic Load Test +```bash +# 100 concurrent users, spawn 10/second, run for 5 minutes +elevenlabs test load \ + --users 100 \ + --spawn-rate 10 \ + --duration 300 +``` + +### With Burst Pricing +```json +{ + "call_limits": { + "burst_pricing_enabled": true + } +} +``` + +## 4. Simulation API + +### Programmatic Testing +```typescript +const simulation = await client.agents.simulate({ + agent_id: 'agent_123', + scenario: 'Customer requests refund', + user_messages: [ + "I want a refund for order #12345", + "It arrived broken", + "Yes, process the refund" + ], + success_criteria: [ + "Agent shows empathy", + "Agent verifies order", + "Agent provides timeline" + ] +}); + +console.log('Passed:', simulation.passed); +console.log('Criteria met:', simulation.evaluation.criteria_met, '/', simulation.evaluation.criteria_total); +``` + +## 5. Convert Real Conversations to Tests + +### From Dashboard +1. Navigate to Conversations +2. Select conversation +3. Click "Convert to Test" +4. Add success criteria +5. Save + +### From API +```typescript +const test = await client.tests.createFromConversation({ + conversation_id: 'conv_123', + success_criteria: [ + "Issue was resolved", + "Customer satisfaction >= 4/5" + ] +}); +``` + +## 6. CI/CD Integration + +### GitHub Actions +```yaml +name: Test Agent +on: [push, pull_request] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Install CLI + run: npm install -g @elevenlabs/cli + + - name: Push Tests + run: elevenlabs tests push + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }} + + - name: Run Tests + run: elevenlabs agents test "Support Agent" + env: + ELEVENLABS_API_KEY: ${{ secrets.ELEVENLABS_API_KEY }} +``` + +## 7. Test Organization + +### Directory Structure +``` +test_configs/ +β”œβ”€β”€ refund-tests/ +β”‚ β”œβ”€β”€ basic-refund.json +β”‚ β”œβ”€β”€ duplicate-refund.json +β”‚ └── expired-refund.json +β”œβ”€β”€ order-lookup-tests/ +β”‚ β”œβ”€β”€ valid-order.json +β”‚ └── invalid-order.json +└── escalation-tests/ + β”œβ”€β”€ angry-customer.json + └── complex-issue.json +``` + +## 8. Best Practices + +### Do's: +βœ… Test all conversation paths +βœ… Include edge cases +βœ… Test tool calls thoroughly +βœ… Run tests before deployment +βœ… Convert failed conversations to tests +βœ… Monitor test trends over time + +### Don'ts: +❌ Only test happy paths +❌ Ignore failing tests +❌ Skip load testing +❌ Test only in production +❌ Write vague success criteria + +## 9. Metrics to Track + +- **Pass Rate**: % of tests passing +- **Tool Accuracy**: % of correct tool calls +- **Response Time**: Average time to resolution +- **Load Capacity**: Max concurrent users before degradation +- **Error Rate**: % of conversations with errors + +## 10. Debugging Failed Tests + +1. Review conversation transcript +2. Check tool calls and parameters +3. Verify dynamic variables provided +4. Test prompt clarity +5. Check knowledge base content +6. Review guardrails and constraints +7. Iterate and retest diff --git a/references/tool-examples.md b/references/tool-examples.md new file mode 100644 index 0000000..d1d2163 --- /dev/null +++ b/references/tool-examples.md @@ -0,0 +1,177 @@ +# Tool Examples + +## Client Tools (Browser-Side) + +### Update Shopping Cart +```typescript +import { useConversation } from '@elevenlabs/react'; +import { z } from 'zod'; + +clientTools: { + updateCart: { + description: "Add or remove items from the shopping cart", + parameters: z.object({ + action: z.enum(['add', 'remove']), + item: z.string(), + quantity: z.number().min(1) + }), + handler: async ({ action, item, quantity }) => { + const cart = getCart(); + if (action === 'add') { + cart.add(item, quantity); + } else { + cart.remove(item, quantity); + } + return { success: true, total: cart.total, items: cart.items.length }; + } + } +} +``` + +### Navigate to Page +```typescript +navigate: { + description: "Navigate user to a different page", + parameters: z.object({ + url: z.string().url() + }), + handler: async ({ url }) => { + window.location.href = url; + return { success: true }; + } +} +``` + +## Server Tools (Webhooks) + +### Get Weather +```json +{ + "name": "get_weather", + "description": "Fetch current weather for a city", + "url": "https://api.weather.com/v1/current", + "method": "GET", + "parameters": { + "type": "object", + "properties": { + "city": { "type": "string", "description": "City name (e.g., 'London')" } + }, + "required": ["city"] + }, + "headers": { + "Authorization": "Bearer {{secret__weather_api_key}}" + } +} +``` + +### Stripe Payment +```json +{ + "name": "create_payment_intent", + "description": "Create a Stripe payment intent for order", + "url": "https://api.stripe.com/v1/payment_intents", + "method": "POST", + "parameters": { + "type": "object", + "properties": { + "amount": { "type": "number", "description": "Amount in cents" }, + "currency": { "type": "string", "description": "Currency code (e.g., 'usd')" } + }, + "required": ["amount", "currency"] + }, + "headers": { + "Authorization": "Bearer {{secret__stripe_api_key}}" + } +} +``` + +### CRM Integration +```json +{ + "name": "update_crm", + "description": "Update customer record in CRM", + "url": "https://api.salesforce.com/services/data/v57.0/sobjects/Contact/{{contact_id}}", + "method": "PATCH", + "parameters": { + "type": "object", + "properties": { + "notes": { "type": "string" }, + "status": { "type": "string", "enum": ["active", "resolved", "pending"] } + } + }, + "headers": { + "Authorization": "Bearer {{secret__salesforce_token}}", + "Content-Type": "application/json" + } +} +``` + +## MCP Tools + +### Connect PostgreSQL MCP Server +```json +{ + "name": "PostgreSQL Database", + "server_url": "https://mcp.example.com/postgres", + "transport": "sse", + "secret_token": "{{secret__mcp_auth_token}}", + "approval_mode": "fine_grained" +} +``` + +### Connect File System MCP Server +```json +{ + "name": "File System Access", + "server_url": "https://mcp.example.com/filesystem", + "transport": "http", + "approval_mode": "always_ask" +} +``` + +## System Tools + +### Update Conversation State +```json +{ + "name": "update_state", + "description": "Update conversation context", + "parameters": { + "key": { "type": "string" }, + "value": { "type": "string" } + } +} +``` + +### Transfer to Human +```json +{ + "name": "transfer_to_human", + "description": "Transfer call to human agent", + "parameters": { + "reason": { "type": "string", "description": "Reason for transfer" } + } +} +``` + +## Best Practices + +**Client Tools**: +- Keep handler logic simple +- Always return meaningful values +- Handle errors gracefully + +**Server Tools**: +- Use secret variables for API keys +- Provide clear parameter descriptions +- Include format examples in descriptions + +**MCP Tools**: +- Test connectivity before production +- Use appropriate approval modes +- Monitor tool usage and errors + +**System Tools**: +- Use for workflow state management +- Document state schema +- Clean up state when conversation ends diff --git a/references/workflow-examples.md b/references/workflow-examples.md new file mode 100644 index 0000000..a571788 --- /dev/null +++ b/references/workflow-examples.md @@ -0,0 +1,132 @@ +# Workflow Examples + +## Customer Support Routing + +**Scenario**: Route calls to specialized agents based on customer needs. + +```json +{ + "workflow": { + "nodes": [ + { + "id": "initial_routing", + "type": "subagent", + "config": { + "system_prompt": "Ask customer: Are you calling about billing, technical support, or sales?", + "turn_eagerness": "patient" + } + }, + { + "id": "billing_agent", + "type": "subagent", + "config": { + "system_prompt": "You are a billing specialist. Help with invoices, payments, and account charges.", + "voice_id": "billing_voice_id" + } + }, + { + "id": "technical_agent", + "type": "subagent", + "config": { + "system_prompt": "You are a technical support specialist. Troubleshoot product issues.", + "voice_id": "tech_voice_id" + } + }, + { + "id": "sales_agent", + "type": "subagent", + "config": { + "system_prompt": "You are a sales representative. Help customers choose products.", + "voice_id": "sales_voice_id" + } + } + ], + "edges": [ + { "from": "initial_routing", "to": "billing_agent", "condition": "user_mentions_billing" }, + { "from": "initial_routing", "to": "technical_agent", "condition": "user_mentions_technical" }, + { "from": "initial_routing", "to": "sales_agent", "condition": "user_mentions_sales" } + ] + } +} +``` + +## Escalation Workflow + +**Scenario**: Attempt self-service resolution, then escalate to human if needed. + +```json +{ + "workflow": { + "nodes": [ + { + "id": "self_service", + "type": "subagent", + "config": { + "system_prompt": "Try to resolve issue using knowledge base and tools. If issue can't be resolved, offer human transfer.", + "knowledge_base": ["faq_doc_id"], + "tool_ids": ["lookup_order", "check_status"] + } + }, + { + "id": "human_transfer", + "type": "tool", + "tool_name": "transfer_to_human" + } + ], + "edges": [ + { "from": "self_service", "to": "human_transfer", "condition": "user_requests_human_or_issue_unresolved" } + ] + } +} +``` + +## Multi-Language Support + +**Scenario**: Detect language and route to appropriate voice/agent. + +```json +{ + "workflow": { + "nodes": [ + { + "id": "language_detection", + "type": "subagent", + "config": { + "system_prompt": "Greet customer and detect language.", + "language": "auto" + } + }, + { + "id": "english_agent", + "type": "subagent", + "config": { + "language": "en", + "voice_id": "en_voice_id", + "first_message": "Hello! How can I help you today?" + } + }, + { + "id": "spanish_agent", + "type": "subagent", + "config": { + "language": "es", + "voice_id": "es_voice_id", + "first_message": "Β‘Hola! ΒΏCΓ³mo puedo ayudarte hoy?" + } + } + ], + "edges": [ + { "from": "language_detection", "to": "english_agent", "condition": "detected_language_en" }, + { "from": "language_detection", "to": "spanish_agent", "condition": "detected_language_es" } + ] + } +} +``` + +## Best Practices + +1. **Keep workflows simple** - Max 5-7 nodes for maintainability +2. **Test all paths** - Ensure every edge condition works +3. **Add fallbacks** - Always have a default path +4. **Monitor transitions** - Track which paths users take most +5. **Avoid loops** - Workflows can get stuck in infinite loops diff --git a/scripts/create-agent.sh b/scripts/create-agent.sh new file mode 100755 index 0000000..bdf30ea --- /dev/null +++ b/scripts/create-agent.sh @@ -0,0 +1,44 @@ +#!/bin/bash +# Create ElevenLabs agent using CLI + +set -e + +AGENT_NAME="${1:-Support Agent}" +TEMPLATE="${2:-customer-service}" +ENV="${3:-dev}" + +echo "Creating ElevenLabs agent..." +echo "Name: $AGENT_NAME" +echo "Template: $TEMPLATE" +echo "Environment: $ENV" + +# Check if CLI is installed +if ! command -v elevenlabs &> /dev/null; then + echo "Error: @elevenlabs/cli is not installed" + echo "Install with: npm install -g @elevenlabs/cli" + exit 1 +fi + +# Check if authenticated +if ! elevenlabs auth whoami &> /dev/null; then + echo "Not authenticated. Please login:" + elevenlabs auth login +fi + +# Initialize project if not already initialized +if [ ! -f "agents.json" ]; then + echo "Initializing project..." + elevenlabs agents init +fi + +# Create agent +echo "Creating agent: $AGENT_NAME" +elevenlabs agents add "$AGENT_NAME" --template "$TEMPLATE" + +# Push to platform +echo "Deploying to environment: $ENV" +elevenlabs agents push --env "$ENV" + +echo "βœ“ Agent created successfully!" +echo "Edit configuration in: agent_configs/" +echo "Test with: elevenlabs agents test \"$AGENT_NAME\"" diff --git a/scripts/deploy-agent.sh b/scripts/deploy-agent.sh new file mode 100755 index 0000000..64f5cd5 --- /dev/null +++ b/scripts/deploy-agent.sh @@ -0,0 +1,46 @@ +#!/bin/bash +# Multi-environment deployment for ElevenLabs agents + +set -e + +ENV="${1:-dev}" +AGENT_NAME="${2}" + +echo "Deploying ElevenLabs agent to environment: $ENV" + +# Check if CLI is installed +if ! command -v elevenlabs &> /dev/null; then + echo "Error: @elevenlabs/cli is not installed" + echo "Install with: npm install -g @elevenlabs/cli" + exit 1 +fi + +# Check if authenticated +if ! elevenlabs auth whoami &> /dev/null; then + echo "Not authenticated. Please login:" + elevenlabs auth login +fi + +# Dry run first to show changes +echo "Preview of changes for $ENV:" +if [ -n "$AGENT_NAME" ]; then + elevenlabs agents push --env "$ENV" --agent "$AGENT_NAME" --dry-run +else + elevenlabs agents push --env "$ENV" --dry-run +fi + +# Confirm deployment +read -p "Deploy to $ENV? (y/n) " -n 1 -r +echo + +if [[ $REPLY =~ ^[Yy]$ ]]; then + if [ -n "$AGENT_NAME" ]; then + elevenlabs agents push --env "$ENV" --agent "$AGENT_NAME" + else + elevenlabs agents push --env "$ENV" + fi + echo "βœ“ Deployment to $ENV completed successfully!" +else + echo "Deployment cancelled" + exit 0 +fi diff --git a/scripts/simulate-conversation.sh b/scripts/simulate-conversation.sh new file mode 100755 index 0000000..1fb5b70 --- /dev/null +++ b/scripts/simulate-conversation.sh @@ -0,0 +1,53 @@ +#!/bin/bash +# Programmatically simulate conversation for testing + +set -e + +AGENT_ID="${1}" +SIMULATION_FILE="${2:-simulation.json}" + +if [ -z "$AGENT_ID" ]; then + echo "Usage: ./simulate-conversation.sh [simulation_file]" + echo "Example: ./simulate-conversation.sh agent_abc123 simulation.json" + exit 1 +fi + +# Check if API key is set +if [ -z "$ELEVENLABS_API_KEY" ]; then + echo "Error: ELEVENLABS_API_KEY environment variable not set" + exit 1 +fi + +# Check if simulation file exists +if [ ! -f "$SIMULATION_FILE" ]; then + echo "Creating example simulation file: $SIMULATION_FILE" + cat > "$SIMULATION_FILE" << 'EOF' +{ + "scenario": "Customer requests refund", + "user_messages": [ + "I want a refund for order #12345", + "I ordered it last week", + "Yes, please process it" + ], + "success_criteria": [ + "Agent acknowledges request", + "Agent asks for order details", + "Agent provides refund timeline" + ] +} +EOF + echo "Example simulation file created. Edit $SIMULATION_FILE and run again." + exit 0 +fi + +echo "Running conversation simulation..." +echo "Agent ID: $AGENT_ID" +echo "Simulation file: $SIMULATION_FILE" + +# Run simulation +curl -X POST "https://api.elevenlabs.io/v1/convai/agents/$AGENT_ID/simulate" \ + -H "xi-api-key: $ELEVENLABS_API_KEY" \ + -H "Content-Type: application/json" \ + -d @"$SIMULATION_FILE" | jq . + +echo "βœ“ Simulation completed!" diff --git a/scripts/test-agent.sh b/scripts/test-agent.sh new file mode 100755 index 0000000..91a8ce3 --- /dev/null +++ b/scripts/test-agent.sh @@ -0,0 +1,33 @@ +#!/bin/bash +# Run automated tests on ElevenLabs agent + +set -e + +AGENT_NAME="${1:-Support Agent}" + +echo "Testing ElevenLabs agent: $AGENT_NAME" + +# Check if CLI is installed +if ! command -v elevenlabs &> /dev/null; then + echo "Error: @elevenlabs/cli is not installed" + echo "Install with: npm install -g @elevenlabs/cli" + exit 1 +fi + +# Check if authenticated +if ! elevenlabs auth whoami &> /dev/null; then + echo "Not authenticated. Please login:" + elevenlabs auth login +fi + +# Push tests to platform +if [ -f "tests.json" ]; then + echo "Deploying tests..." + elevenlabs tests push +fi + +# Run agent tests +echo "Running tests for: $AGENT_NAME" +elevenlabs agents test "$AGENT_NAME" + +echo "βœ“ Tests completed!"