Agents

Create and manage AI agents with the ElevenLabs Conversational AI API

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

name · str

A human-readable name to make the agent easier to find

tags · List[str]

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

agent_id · str · required

The unique identifier of the agent

version_id · str

The ID of a specific agent version to retrieve

branch_id · str

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

page_size · int · default: "30"

Number of agents to return (max 100)

search · str

Search agents by name

archived · bool

Filter by archived status

show_only_owned_agents · bool

If true, excludes agents shared with you by others

sort_direction · str

Sort direction: "asc" or "desc"

sort_by · str

Field to sort by (e.g., "name", "created_at")

cursor · str

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

agent_id · str · required

The ID of the agent to update

branch_id · str

The ID of the branch to update

name · str

Updated name for the agent

conversation_config · ConversationalConfig

Updated conversation configuration

version_description · str

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 analytics
• Widget: Configure embeddable chat widgets
• Link: Manage shareable agent links
• Knowledge Base: Add and manage agent knowledge bases
• LLM Usage: Track language model usage and costs
• Branches: Manage agent version branches
• Deployments: Handle agent deployments
• Drafts: Work with draft agent configurations

API Reference

View complete API documentation for all agent endpoints