{"id":48633087,"url":"https://github.com/usemoss/moss-voice-agent-demo","last_synced_at":"2026-04-09T06:03:40.097Z","repository":{"id":338625778,"uuid":"1155328136","full_name":"usemoss/moss-voice-agent-demo","owner":"usemoss","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-15T16:28:27.000Z","size":801,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-15T20:34:31.361Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://moss-voice-agent-demo.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usemoss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T11:42:39.000Z","updated_at":"2026-02-15T16:29:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/usemoss/moss-voice-agent-demo","commit_stats":null,"previous_names":["usemoss/moss-voice-agent-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/usemoss/moss-voice-agent-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usemoss%2Fmoss-voice-agent-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usemoss%2Fmoss-voice-agent-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usemoss%2Fmoss-voice-agent-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usemoss%2Fmoss-voice-agent-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usemoss","download_url":"https://codeload.github.com/usemoss/moss-voice-agent-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usemoss%2Fmoss-voice-agent-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31588040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-09T05:33:47.836Z","status":"ssl_error","status_checked_at":"2026-04-09T05:32:26.579Z","response_time":112,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-09T06:03:36.089Z","updated_at":"2026-04-09T06:03:40.089Z","avatar_url":"https://github.com/usemoss.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Moss Voice Agent - Complete Setup Guide\n\nA complete voice agent system built with Moss Voice Platform, featuring a Python-based agent deployment manager and a Next.js web interface for real-time voice interactions.\n\n## 📋 Table of Contents\n\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Getting Started](#getting-started)\n- [Part 1: Deploy the Voice Agent (Manager)](#part-1-deploy-the-voice-agent-manager)\n- [Part 2: Run the Web Interface (Agent UI)](#part-2-run-the-web-interface-agent-ui)\n- [Voice Server Package (@moss-tools/voice-server)](#voice-server-package-moss-toolsvoice-server)\n- [Customizing Your Agent](#customizing-your-agent)\n- [Additional Resources](#additional-resources)\n- [Support](#support)\n\n---\n\n## 🎯 Overview\n\n- **Manager (Python)**: Deploys voice agent with custom tools\n- **Agent UI (Next.js)**: Web interface for voice interactions\n\n## 🏗️ Architecture\n\n```\nManager (Python) → Moss Platform ← Agent UI (Next.js)\n```\n\n---\n\n## ✅ Prerequisites\n\n### Required Software\n\n- **Python+** (for Manager)\n- **Node.js+** (for Agent UI)\n- **pnpm** (package manager for Agent UI)\n- **Git** (optional, for version control)\n\n### Moss Platform Credentials\n\nYou'll need three pieces of information from your Moss Platform account:\n\n1. **MOSS_PROJECT_ID** - Your project UUID\n2. **MOSS_PROJECT_KEY** - Your project read key (starts with `moss_`)\n3. **MOSS_VOICE_AGENT_ID** - Your voice agent UUID\n\n**How to get these:**\n1. Sign up at [Moss Platform](https://portal.usemoss.dev/)\n2. Create a new project\n3. Navigate to your project settings to find your Project ID,  API Key and Voice Agent ID\n\n---\n\n## 🚀 Getting Started\n\n### Clone or Navigate to Your Project\n\n```bash\ncd voice-manage-test\n```\n\nYour project structure should look like this:\n\n```\nvoice-manage-test/\n├── manager/              # Python deployment manager\n│   ├── main.py          # Agent deployment script\n│   ├── pyproject.toml   # Python dependencies\n│   └── .env             # Environment variables\n└── agent-ui/            # Next.js web interface\n    ├── app/             # Next.js app directory\n    ├── package.json     # Node dependencies\n    └── .env.local       # Environment variables\n```\n\n---\n\n## 📦 Part 1: Deploy the Voice Agent (Manager)\n\nThe Manager is a Python script that deploys your voice agent configuration to the Moss Platform.\n\n### Step 1.1: Navigate to Manager Directory\n\n```bash\ncd manager\n```\n\n### Step 1.2: Set Up Environment Variables\n\nCreate or edit the `.env` file with your Moss credentials:\n\n```bash\n# manager/.env\nMOSS_PROJECT_ID=your-project-uuid-here\nMOSS_PROJECT_KEY=moss_your-project-key-here\nMOSS_VOICE_AGENT_ID=your-voice-agent-uuid-here\n```\n\n### Step 1.3: Create Virtual Environment\n\n```bash\n# Create a Python virtual environment using uv\nuv venv\n\n# Activate the virtual environment\n# On macOS/Linux:\nsource .venv/bin/activate\n\n# On Windows:\n# .venv\\Scripts\\activate\n```\n\n### Step 1.4: Install Dependencies\n\n```bash\n# Install required Python packages from PyPI\nuv pip install moss-voice-agent-manager python-dotenv\n\n\nThis will install:\n- `moss-voice-agent-manager` - SDK for deploying agents\n- `python-dotenv` - For loading environment variables\n\n### Step 1.5: Deploy Your Agent\n\n```bash\npython main.py\n```\n\n**Expected Output:**\n\n```\n============================================================\n🚀 Deploying voice agent with custom tools\n============================================================\n✅ Deployment successful!\n🎯 Voice Agent ID: 9c11b621-44bf-42ee-9e40-9b81804b48f0\n============================================================\n```\n\n---\n\n## 🌐 Part 2: Run the Web Interface (Agent UI)\n\n### Step 2.1: Navigate to Agent UI Directory\n\n```bash\n# From the manager directory, go back and enter agent-ui\ncd ../agent-ui\n```\n\n### Step 2.2: Set Up Environment Variables\n\nCreate or edit `.env.local` with your Moss credentials:\n\n```bash\n# agent-ui/.env.local\nMOSS_PROJECT_ID=your-project-uuid-here\nMOSS_PROJECT_KEY=moss_your-project-key-here\nMOSS_VOICE_AGENT_ID=your-voice-agent-uuid-here\n```\n\n**Note:** Use the same credentials as `manager/.env`\n\n### Step 2.3: Install Dependencies\n\n```bash\npnpm install\n```\n\n### Step 2.4: Run the Development Server\n\n```bash\npnpm dev\n```\n\n**Expected Output:**\n\n```\n  ▲ Next.js 15.5.9\n  - Local:        http://localhost:3000\n  - Environments: .env.local\n\n ✓ Starting...\n ✓ Ready in 2.3s\n```\n\n### Step 2.5: Open the Application\n\n1. Open your web browser\n2. Navigate to: **http://localhost:3000**\n3. You should see the voice agent interface\n\n### Step 2.6: Start a Voice Conversation\n\n1. Click the \"Start\" button\n2. Allow microphone access when prompted\n3. Start speaking to the agent\n\n---\n\n## 🔌 Voice Server Package (@moss-tools/voice-server)\n\nThe Agent UI uses `@moss-tools/voice-server` to connect to your deployed agent.\n\n### Key Files\n\n- [app/api/connection-details/route.ts](agent-ui/app/api/connection-details/route.ts) - Creates voice server connections\n- [lib/utils.ts](agent-ui/lib/utils.ts) - Handles token fetching\n\n### API Usage in route.ts\n\n```typescript\nimport { MossVoiceServer } from \"@moss-tools/voice-server\";\n\n// Create voice server instance\nconst voiceServer = await MossVoiceServer.create({\n  projectId: process.env.MOSS_PROJECT_ID!,\n  projectKey: process.env.MOSS_PROJECT_KEY!,\n  voiceAgentId: process.env.MOSS_VOICE_AGENT_ID!,\n});\n\n// Get server URL\nconst serverUrl = voiceServer.getServerUrl();\n\n// Create participant token\nconst participantToken = await voiceServer.createParticipantToken(\n  { identity: participantIdentity, name: participantName },\n  roomName,\n  agentName\n);\n```\n\n### API Response\n\n```typescript\n{\n  serverUrl: string;\n  roomName: string;\n  participantName: string;\n  participantToken: string;\n}\n```\n\n---\n\n## 🛠️ Customizing Your Agent\n\n### Adding New Tools\n\nEdit [manager/main.py](manager/main.py) to add new functions:\n\n```python\ndef get_weather(city: str) -\u003e str:\n    \"\"\"Get current weather for a city.\"\"\"\n    # Your implementation here\n    return f\"The weather in {city} is sunny!\"\n\ndef main():\n    # ... existing code ...\n\n    response = client.deploy(\n        voice_agent_id=voice_agent_id,\n        prompt=\"Updated prompt mentioning weather...\",\n        initial_greeting=\"Hello! I can help with age, discounts, and weather!\",\n        function_tools=[\n            get_user_age,\n            calculate_discount,\n            get_weather  # Add your new tool\n        ],\n    )\n```\n\n**Requirements for tool functions:**\n- Must have type hints for parameters\n- Must have a docstring (used by LLM to understand the tool)\n- Must return a string (the agent will speak this)\n\n### Changing Agent Behavior\n\nModify the `prompt` parameter in [manager/main.py:69](manager/main.py#L69):\n\n```python\nresponse = client.deploy(\n    voice_agent_id=voice_agent_id,\n    prompt=\"\"\"You are a professional financial advisor named Alex.\n    You help users with calculations and provide detailed explanations.\n    Always be formal and precise in your responses.\"\"\",\n    initial_greeting=\"Good day! I'm Alex, your financial advisor. How may I assist you?\",\n    function_tools=[get_user_age, calculate_discount],\n)\n```\n\n### Customizing the UI\n\nThe UI components are in [agent-ui/app](agent-ui/app) directory:\n- Modify styling in Tailwind classes\n- Customize components in `agent-ui/components/`\n- Update layout and branding as needed\n\n### Re-deploying Changes\n\nAfter making changes:\n\n```bash\n# 1. Re-deploy the agent (if you changed tools/prompt)\ncd manager\npython main.py\n\n# 2. Restart the UI (if you changed UI code)\ncd ../agent-ui\n# Stop the dev server (Ctrl+C) and restart\npnpm dev\n```\n\n---\n\n\n### Project Structure Details\n\n```\nvoice-manage-test/\n├── manager/\n│   ├── main.py              # Agent deployment script\n│   ├── pyproject.toml       # Python dependencies \u0026 project config\n│   ├── .env                 # Environment variables (gitignored)\n│   ├── .venv/              # Python virtual environment\n│   └── README.md           # (create for manager-specific docs)\n│\n└── agent-ui/\n    ├── app/\n    │   ├── api/\n    │   │   └── connection-details/\n    │   │       └── route.ts # API endpoint for voice connections\n    │   └── page.tsx        # Main page component\n    ├── components/         # React components\n    ├── lib/               # Utility functions\n    ├── public/            # Static assets\n    ├── package.json       # Node dependencies\n    ├── .env.local        # Environment variables (gitignored)\n    └── README.md         # (create for UI-specific docs)\n```\n\n---\n\n## 🤝 Support\n\nIf you encounter issues:\n\n1. **Check the troubleshooting section** above\n2. **Review Moss Platform documentation** for credential setup\n3. **Check browser console** for client-side errors\n4. **Check terminal output** for server-side errors\n5. **Verify environment variables** match between manager and agent-ui\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusemoss%2Fmoss-voice-agent-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusemoss%2Fmoss-voice-agent-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusemoss%2Fmoss-voice-agent-demo/lists"}