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.