create_agent
Create a conversational AI agent with custom voice, language, and behavior settings for interactive audio applications.
Instructions
Create a conversational AI agent with custom configuration.
⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user.
Args:
name: Name of the agent
first_message: First message the agent will say i.e. "Hi, how can I help you today?"
system_prompt: System prompt for the agent
voice_id: ID of the voice to use for the agent
language: ISO 639-1 language code for the agent
llm: LLM to use for the agent
temperature: Temperature for the agent. The lower the temperature, the more deterministic the agent's responses will be. Range is 0 to 1.
max_tokens: Maximum number of tokens to generate.
asr_quality: Quality of the ASR. `high` or `low`.
model_id: ID of the ElevenLabs model to use for the agent.
optimize_streaming_latency: Optimize streaming latency. Range is 0 to 4.
stability: Stability for the agent. Range is 0 to 1.
similarity_boost: Similarity boost for the agent. Range is 0 to 1.
turn_timeout: Timeout for the agent to respond in seconds. Defaults to 7 seconds.
max_duration_seconds: Maximum duration of a conversation in seconds. Defaults to 600 seconds (10 minutes).
record_voice: Whether to record the agent's voice.
retention_days: Number of days to retain the agent's data.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| first_message | Yes | ||
| system_prompt | Yes | ||
| voice_id | No | cgSgspJ2msm6clMCkdW9 | |
| language | No | en | |
| llm | No | gemini-2.0-flash-001 | |
| temperature | No | ||
| max_tokens | No | ||
| asr_quality | No | high | |
| model_id | No | eleven_turbo_v2 | |
| optimize_streaming_latency | No | ||
| stability | No | ||
| similarity_boost | No | ||
| turn_timeout | No | ||
| max_duration_seconds | No | ||
| record_voice | No | ||
| retention_days | No |
Implementation Reference
- elevenlabs_mcp/server.py:565-641 (handler)The @mcp.tool decorator registers the create_agent tool and defines its handler function, which creates a conversational AI agent by calling the ElevenLabs API with constructed conversation config and platform settings.
@mcp.tool( description="""Create a conversational AI agent with custom configuration. ⚠️ COST WARNING: This tool makes an API call to ElevenLabs which may incur costs. Only use when explicitly requested by the user. Args: name: Name of the agent first_message: First message the agent will say i.e. "Hi, how can I help you today?" system_prompt: System prompt for the agent voice_id: ID of the voice to use for the agent language: ISO 639-1 language code for the agent llm: LLM to use for the agent temperature: Temperature for the agent. The lower the temperature, the more deterministic the agent's responses will be. Range is 0 to 1. max_tokens: Maximum number of tokens to generate. asr_quality: Quality of the ASR. `high` or `low`. model_id: ID of the ElevenLabs model to use for the agent. optimize_streaming_latency: Optimize streaming latency. Range is 0 to 4. stability: Stability for the agent. Range is 0 to 1. similarity_boost: Similarity boost for the agent. Range is 0 to 1. turn_timeout: Timeout for the agent to respond in seconds. Defaults to 7 seconds. max_duration_seconds: Maximum duration of a conversation in seconds. Defaults to 600 seconds (10 minutes). record_voice: Whether to record the agent's voice. retention_days: Number of days to retain the agent's data. """ ) def create_agent( name: str, first_message: str, system_prompt: str, voice_id: str | None = DEFAULT_VOICE_ID, language: str = "en", llm: str = "gemini-2.0-flash-001", temperature: float = 0.5, max_tokens: int | None = None, asr_quality: str = "high", model_id: str = "eleven_turbo_v2", optimize_streaming_latency: int = 3, stability: float = 0.5, similarity_boost: float = 0.8, turn_timeout: int = 7, max_duration_seconds: int = 300, record_voice: bool = True, retention_days: int = 730, ) -> TextContent: conversation_config = create_conversation_config( language=language, system_prompt=system_prompt, llm=llm, first_message=first_message, temperature=temperature, max_tokens=max_tokens, asr_quality=asr_quality, voice_id=voice_id, model_id=model_id, optimize_streaming_latency=optimize_streaming_latency, stability=stability, similarity_boost=similarity_boost, turn_timeout=turn_timeout, max_duration_seconds=max_duration_seconds, ) platform_settings = create_platform_settings( record_voice=record_voice, retention_days=retention_days, ) response = client.conversational_ai.agents.create( name=name, conversation_config=conversation_config, platform_settings=platform_settings, ) return TextContent( type="text", text=f"""Agent created successfully: Name: {name}, Agent ID: {response.agent_id}, System Prompt: {system_prompt}, Voice ID: {voice_id or "Default"}, Language: {language}, LLM: {llm}, You can use this agent ID for future interactions with the agent.""", ) - elevenlabs_mcp/convai.py:1-59 (helper)Helper function to create the conversation configuration dictionary used by the create_agent tool.
def create_conversation_config( language: str, system_prompt: str, llm: str, first_message: str | None, temperature: float, max_tokens: int | None, asr_quality: str, voice_id: str | None, model_id: str, optimize_streaming_latency: int, stability: float, similarity_boost: float, turn_timeout: int, max_duration_seconds: int, ) -> dict: return { "agent": { "language": language, "prompt": { "prompt": system_prompt, "llm": llm, "tools": [{"type": "system", "name": "end_call", "description": ""}], "knowledge_base": [], "temperature": temperature, **({"max_tokens": max_tokens} if max_tokens else {}), }, **({"first_message": first_message} if first_message else {}), "dynamic_variables": {"dynamic_variable_placeholders": {}}, }, "asr": { "quality": asr_quality, "provider": "elevenlabs", "user_input_audio_format": "pcm_16000", "keywords": [], }, "tts": { **({"voice_id": voice_id} if voice_id else {}), "model_id": model_id, "agent_output_audio_format": "pcm_16000", "optimize_streaming_latency": optimize_streaming_latency, "stability": stability, "similarity_boost": similarity_boost, }, "turn": {"turn_timeout": turn_timeout}, "conversation": { "max_duration_seconds": max_duration_seconds, "client_events": [ "audio", "interruption", "user_transcript", "agent_response", "agent_response_correction", ], }, "language_presets": {}, "is_blocked_ivc": False, "is_blocked_non_ivc": False, } - elevenlabs_mcp/convai.py:62-86 (helper)Helper function to create the platform settings dictionary used by the create_agent tool.
def create_platform_settings( record_voice: bool, retention_days: int, ) -> dict: return { "widget": { "variant": "full", "avatar": {"type": "orb", "color_1": "#6DB035", "color_2": "#F5CABB"}, "feedback_mode": "during", "terms_text": '#### Terms and conditions\n\nBy clicking "Agree," and each time I interact with this AI agent, I consent to the recording, storage, and sharing of my communications with third-party service providers, and as described in the Privacy Policy.\nIf you do not wish to have your conversations recorded, please refrain from using this service.', "show_avatar_when_collapsed": True, }, "evaluation": {}, "auth": {"allowlist": []}, "overrides": {}, "call_limits": {"agent_concurrency_limit": -1, "daily_limit": 100000}, "privacy": { "record_voice": record_voice, "retention_days": retention_days, "delete_transcript_and_pii": True, "delete_audio": True, "apply_to_existing_conversations": False, }, "data_collection": {}, }