Overview Agents are the core of ElevenLabs Conversational AI. Each agent has a unique configuration that defines its behavior, voice, conversation style, and capabilities.
Creating an Agent Create a new agent with a conversation configuration:
from elevenlabs import ElevenLabs, ConversationalConfig client = ElevenLabs( api_key = "YOUR_API_KEY" , ) response = client.conversational_ai.agents.create( conversation_config = ConversationalConfig( # Configure your agent's behavior ), name = "My Customer Support Agent" , tags = [ "customer-support" , "production" ], ) agent_id = response.agent_id print ( f "Created agent: { agent_id } " )
Configuration Options conversation_config
ConversationalConfig
required
Conversation configuration defining the agent’s behavior and personality
A human-readable name to make the agent easier to find
Tags to help classify and filter the agent
platform_settings
AgentPlatformSettingsRequestModel
Platform settings for the agent (non-conversation related settings)
workflow
AgentWorkflowRequestModel
Workflow defining the conversation flow and tool interactions
Retrieving an Agent Get an agent’s configuration by ID:
agent = client.conversational_ai.agents.get( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" , version_id = "version_id" , # Optional branch_id = "branch_id" , # Optional ) print ( f "Agent name: { agent.name } " ) print ( f "Agent config: { agent.conversation_config } " )
Parameters The unique identifier of the agent
The ID of a specific agent version to retrieve
The ID of a specific branch to retrieve
Listing Agents Retrieve a paginated list of your agents:
response = client.conversational_ai.agents.list( page_size = 30 , search = "customer" , archived = False , show_only_owned_agents = True , sort_direction = "desc" , sort_by = "created_at" , ) for agent in response.agents: print ( f " { agent.agent_id } : { agent.name } " ) # Pagination if response.has_more: next_page = client.conversational_ai.agents.list( cursor = response.next_cursor )
List Parameters Number of agents to return (max 100)
Filter by archived status
If true, excludes agents shared with you by others
Sort direction: "asc" or "desc"
Field to sort by (e.g., "name", "created_at")
Pagination cursor from previous response
Updating an Agent Update an existing agent’s configuration:
updated_agent = client.conversational_ai.agents.update( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" , name = "Updated Customer Support Agent" , conversation_config = ConversationalConfig( # Updated configuration ), version_description = "Improved response handling" , )
Update Parameters The ID of the agent to update
The ID of the branch to update
Updated name for the agent
Updated conversation configuration
Description for this version (for versioned agents)
Duplicating an Agent Create a copy of an existing agent:
new_agent = client.conversational_ai.agents.duplicate( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" , name = "Customer Support Agent (Copy)" , ) print ( f "Duplicated agent: { new_agent.agent_id } " )
Deleting an Agent Permanently delete an agent:
client.conversational_ai.agents.delete( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" )
Deleting an agent is permanent and cannot be undone. All associated data will be removed.
Testing Agents Simulate Conversation Test your agent with a simulated conversation:
from elevenlabs import ( ConversationSimulationSpecification, AgentConfig, ) result = client.conversational_ai.agents.simulate_conversation( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" , simulation_specification = ConversationSimulationSpecification( simulated_user_config = AgentConfig( first_message = "Hello, I need help with my order" , language = "en" , ), ), new_turns_limit = 10 , ) print ( f "Conversation turns: { len (result.conversation_turns) } " ) for turn in result.conversation_turns: print ( f " { turn.role } : { turn.message } " )
Run Test Suite Run predefined tests on your agent:
from elevenlabs import SingleTestRunRequestModel result = client.conversational_ai.agents.run_tests( agent_id = "agent_3701k3ttaq12ewp8b7qv5rfyszkz" , tests = [ SingleTestRunRequestModel( test_id = "test_greeting" , ), SingleTestRunRequestModel( test_id = "test_order_lookup" , ), ], ) print ( f "Test results: { result.status } " )
Async Usage All agent operations support async/await:
import asyncio from elevenlabs import AsyncElevenLabs, ConversationalConfig client = AsyncElevenLabs( api_key = "YOUR_API_KEY" , ) async def main (): # Create agent response = await client.conversational_ai.agents.create( conversation_config = ConversationalConfig(), name = "Async Agent" , ) # List agents agents = await client.conversational_ai.agents.list() # Update agent updated = await client.conversational_ai.agents.update( agent_id = response.agent_id, name = "Updated Async Agent" , ) # Delete agent await client.conversational_ai.agents.delete( agent_id = response.agent_id ) asyncio.run(main())
Agent Subresources Agents have several subresources for managing additional functionality:
Summaries : Access conversation summaries and analyticsWidget : Configure embeddable chat widgetsLink : Manage shareable agent linksKnowledge Base : Add and manage agent knowledge basesLLM Usage : Track language model usage and costsBranches : Manage agent version branchesDeployments : Handle agent deploymentsDrafts : Work with draft agent configurations
API Reference View complete API documentation for all agent endpoints