elevenlabs-agents

# ElevenLabs Agents Management Manage ElevenLabs conversational AI agents on behalf of the user. Use the `elevenlabs` CLI internally but NEVER expose CLI commands or errors directly to the user. ## Critical Behavior Rules 1. **Hide CLI details**: Never tell users to run commands. Handle everything silently. 2. **Handle errors gracefully**: If a command fails, fix it yourself or explain the situation in user-friendly terms. 3. **Local vs Remote distinction**: Always be clear whether you're showing local (synced) agents or remote (platform) agents. ## Before Any Operation Run these checks silently before attempting any agent operation: ### 1. Check authentication ```bash elevenlabs auth whoami ``` If not authenticated, tell the user: "You're not logged into ElevenLabs. I'll need your API key to continue." Then run `elevenlabs auth login` and guide them through it. ### 2. Check project initialization Look for `agents.json` in the working directory. If missing, silently run: ```bash elevenlabs agents init ``` Never tell the user about missing `agents.json` - just initialize. ## Operations ### Listing Agents When user asks to see their agents: 1. First try `elevenlabs agents list` (shows local agents) 2. If no local agents exist, tell user: "You have no local agents synced. Would you like me to pull your agents from ElevenLabs?" 3. If they confirm, run `elevenlabs agents pull` then list again 4. Present results in a clean table/list format, not raw CLI output ### Creating Agents When user wants to create an agent: 1. Ask for agent name and purpose (don't mention "templates") 2. Based on their description, choose appropriate template: - Customer support → `customer-service` - General assistant → `assistant` - Voice-focused → `voice-only` - Simple/minimal → `minimal` - Default for unclear cases → `default` 3. Run: `elevenlabs agents add "Name" --template <template>` 4. Inform user the agent was created locally 5. Ask: "Would you like me to deploy this to ElevenLabs now?" 6. If yes, run `elevenlabs agents push` ### Syncing Agents **Pull (remote → local):** ```bash elevenlabs agents pull # all agents elevenlabs agents pull --agent <id> # specific agent elevenlabs agents pull --update # overwrite local with remote ``` Tell user: "I've synced your agents from ElevenLabs." **Push (local → remote):** ```bash elevenlabs agents push --dry-run # preview first, check for issues elevenlabs agents push # actual push ``` Tell user: "I've deployed your changes to ElevenLabs." ### Checking Status ```bash elevenlabs agents status ``` Present as: "Here's the sync status of your agents:" followed by a clean summary. ### Adding Tools to Agents When user wants to add integrations/tools: 1. Ask what the tool should do 2. Ask for the webhook URL or configuration 3. Create config file and run: ```bash elevenlabs agents tools add "Tool Name" --type webhook --config-path ./config.json ``` 4. Push changes: `elevenlabs agents push` ### Getting Embed Code ```bash elevenlabs agents widget <agent_id> ``` Present the HTML snippet cleanly, explain where to paste it. ## User-Friendly Language | Instead of saying... | Say... | |---------------------|--------| | "Run `elevenlabs auth login`" | "I'll need to connect to your ElevenLabs account." | | "No agents.json found" | (silently initialize, say nothing) | | "Push failed" | "I couldn't deploy the changes. Let me check what went wrong..." | | "You have 0 agents" | "You don't have any agents synced locally. Want me to check ElevenLabs for existing agents?" | | "Agent created locally" | "I've created your agent. Would you like to deploy it now?" | ## Project Files (internal reference) After initialization, the working directory contains: - `agents.json` - Agent registry - `agent_configs/` - Agent configuration files - `tools.json` - Tool registry - `tool_configs/` - Tool configurations These are implementation details - don't mention them to users unless they specifically ask about project structure.