Skip to main content

​
Overview

The Agents client provides methods for creating, managing, and testing conversational AI agents. Access it via client.conversational_ai.agents.

​
Methods

​
create

client.conversational_ai.agents.create(
    conversation_config: ConversationalConfig,
    platform_settings: Optional[AgentPlatformSettingsRequestModel] = None,
    workflow: Optional[AgentWorkflowRequestModel] = None,
    name: Optional[str] = None,
    tags: Optional[Sequence[str]] = None,
    coaching_settings: Optional[dict] = None,
    request_options: Optional[RequestOptions] = None,
) -> CreateAgentResponseModel
Create an agent from a config object.
​
conversation_config
ConversationalConfig
required
Conversation configuration for an agent.
​
platform_settings
AgentPlatformSettingsRequestModel
Platform settings for the agent that aren’t related to the conversation orchestration and content.
​
workflow
AgentWorkflowRequestModel
Workflow for the agent. This defines the flow of the conversation and how the agent interacts with tools.
​
name
str
A name to make the agent easier to find.
​
tags
Sequence[str]
Tags to help classify and filter the agent.
​
coaching_settings
dict
Coaching settings for the agent.
​
request_options
RequestOptions
Request-specific configuration.
Returns: CreateAgentResponseModel with the created agent details. Example: 
from elevenlabs import ElevenLabs, ConversationalConfig

client = ElevenLabs(api_key="YOUR_API_KEY")

agent = client.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(),
    name="Customer Support Agent",
    tags=["support", "customer-service"]
)
print(f"Created agent: {agent.agent_id}")

​
get

client.conversational_ai.agents.get(
    agent_id: str,
    version_id: Optional[str] = None,
    branch_id: Optional[str] = None,
    request_options: Optional[RequestOptions] = None,
) -> GetAgentResponseModel
Retrieve config for an agent.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
version_id
str
The ID of the agent version to use.
​
branch_id
str
The ID of the branch to use.
​
request_options
RequestOptions
Request-specific configuration.
Returns: GetAgentResponseModel with the agent configuration. Example: 
agent = client.conversational_ai.agents.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)
print(f"Agent name: {agent.name}")

​
delete

client.conversational_ai.agents.delete(
    agent_id: str,
    request_options: Optional[RequestOptions] = None,
) -> None
Delete an agent.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
request_options
RequestOptions
Request-specific configuration.
Example: 
client.conversational_ai.agents.delete(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)

​
update

client.conversational_ai.agents.update(
    agent_id: str,
    branch_id: Optional[str] = None,
    conversation_config: Optional[ConversationalConfig] = None,
    platform_settings: Optional[AgentPlatformSettingsRequestModel] = None,
    workflow: Optional[AgentWorkflowRequestModel] = None,
    name: Optional[str] = None,
    tags: Optional[Sequence[str]] = None,
    coaching_settings: Optional[dict] = None,
    version_description: Optional[str] = None,
    request_options: Optional[RequestOptions] = None,
) -> GetAgentResponseModel
Patches an agent settings.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
branch_id
str
The ID of the branch to use.
​
conversation_config
ConversationalConfig
Conversation configuration for an agent.
​
platform_settings
AgentPlatformSettingsRequestModel
Platform settings for the agent.
​
workflow
AgentWorkflowRequestModel
Workflow for the agent.
​
name
str
A name to make the agent easier to find.
​
tags
Sequence[str]
Tags to help classify and filter the agent.
​
coaching_settings
dict
Coaching settings for the agent.
​
version_description
str
Description for this version when publishing changes (only applicable for versioned agents).
​
request_options
RequestOptions
Request-specific configuration.
Returns: GetAgentResponseModel with the updated agent configuration. Example: 
updated_agent = client.conversational_ai.agents.update(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    name="Updated Support Agent",
    tags=["support", "v2"]
)

​
list

client.conversational_ai.agents.list(
    page_size: Optional[int] = None,
    search: Optional[str] = None,
    archived: Optional[bool] = None,
    show_only_owned_agents: Optional[bool] = None,
    sort_direction: Optional[SortDirection] = None,
    sort_by: Optional[AgentSortBy] = None,
    cursor: Optional[str] = None,
    request_options: Optional[RequestOptions] = None,
) -> GetAgentsPageResponseModel
Returns a list of your agents and their metadata.
​
page_size
int
How many agents to return at maximum. Cannot exceed 100, defaults to 30.
​
search
str
Search by agent name.
​
archived
bool
Filter agents by archived status.
​
show_only_owned_agents
bool
If set to true, omit agents shared by others and include only the ones you own.
​
sort_direction
SortDirection
The direction to sort the results (“asc” or “desc”).
​
sort_by
AgentSortBy
The field to sort the results by (e.g., “name”, “created_at”).
​
cursor
str
Used for fetching next page. Cursor is returned in the response.
​
request_options
RequestOptions
Request-specific configuration.
Returns: GetAgentsPageResponseModel with paginated agent list. Example: 
response = client.conversational_ai.agents.list(
    page_size=10,
    search="support",
    show_only_owned_agents=True,
    sort_by="name",
    sort_direction="asc"
)

for agent in response.agents:
    print(f"{agent.name}: {agent.agent_id}")

​
duplicate

client.conversational_ai.agents.duplicate(
    agent_id: str,
    name: Optional[str] = None,
    request_options: Optional[RequestOptions] = None,
) -> CreateAgentResponseModel
Create a new agent by duplicating an existing one.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
name
str
A name to make the agent easier to find.
​
request_options
RequestOptions
Request-specific configuration.
Returns: CreateAgentResponseModel with the duplicated agent details. Example: 
cloned_agent = client.conversational_ai.agents.duplicate(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    name="Support Agent Copy"
)

​
simulate_conversation

client.conversational_ai.agents.simulate_conversation(
    agent_id: str,
    simulation_specification: ConversationSimulationSpecification,
    extra_evaluation_criteria: Optional[Sequence[PromptEvaluationCriteria]] = None,
    new_turns_limit: Optional[int] = None,
    request_options: Optional[RequestOptions] = None,
) -> AgentSimulatedChatTestResponseModel
Run a conversation between the agent and a simulated user.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
simulation_specification
ConversationSimulationSpecification
required
A specification detailing how the conversation should be simulated.
​
extra_evaluation_criteria
Sequence[PromptEvaluationCriteria]
A list of evaluation criteria to test.
​
new_turns_limit
int
Maximum number of new turns to generate in the conversation simulation.
​
request_options
RequestOptions
Request-specific configuration.
Returns: AgentSimulatedChatTestResponseModel with simulation results. Example: 
from elevenlabs import AgentConfig, ConversationSimulationSpecification

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
)

​
simulate_conversation_stream

client.conversational_ai.agents.simulate_conversation_stream(
    agent_id: str,
    simulation_specification: ConversationSimulationSpecification,
    extra_evaluation_criteria: Optional[Sequence[PromptEvaluationCriteria]] = None,
    new_turns_limit: Optional[int] = None,
    request_options: Optional[RequestOptions] = None,
) -> None
Run a conversation between the agent and a simulated user and stream back the response. Response is streamed back as partial lists of messages that should be concatenated. Once the conversation is complete, a single final message with the conversation analysis will be sent.
​
agent_id
str
required
The ID of an agent.
​
simulation_specification
ConversationSimulationSpecification
required
A specification detailing how the conversation should be simulated.
​
extra_evaluation_criteria
Sequence[PromptEvaluationCriteria]
A list of evaluation criteria to test.
​
new_turns_limit
int
Maximum number of new turns to generate in the conversation simulation.
​
request_options
RequestOptions
Request-specific configuration.

​
run_tests

client.conversational_ai.agents.run_tests(
    agent_id: str,
    tests: Sequence[SingleTestRunRequestModel],
    agent_config_override: Optional[AdhocAgentConfigOverrideForTestRequestModel] = None,
    branch_id: Optional[str] = None,
    request_options: Optional[RequestOptions] = None,
) -> GetTestSuiteInvocationResponseModel
Run selected tests on the agent with provided configuration. If the agent configuration is provided, it will be used to override default agent configuration.
​
agent_id
str
required
The ID of an agent. This is returned on agent creation.
​
tests
Sequence[SingleTestRunRequestModel]
required
List of tests to run on the agent.
​
agent_config_override
AdhocAgentConfigOverrideForTestRequestModel
Configuration overrides to use for testing. If not provided, the agent’s default configuration will be used.
​
branch_id
str
ID of the branch to run the tests on. If not provided, the tests will be run on the agent default configuration.
​
request_options
RequestOptions
Request-specific configuration.
Returns: GetTestSuiteInvocationResponseModel with test results. Example: 
from elevenlabs import SingleTestRunRequestModel

test_results = client.conversational_ai.agents.run_tests(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    tests=[
        SingleTestRunRequestModel(test_id="test_123"),
        SingleTestRunRequestModel(test_id="test_456"),
    ]
)

​
Async Usage

All methods are available on AsyncElevenLabs client with async/await syntax: 
import asyncio
from elevenlabs import AsyncElevenLabs

async def main():
    client = AsyncElevenLabs(api_key="YOUR_API_KEY")
    
    # List agents
    agents = await client.conversational_ai.agents.list(page_size=10)
    
    # Get specific agent
    agent = await client.conversational_ai.agents.get(
        agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
    )

asyncio.run(main())

Build docs developers (and LLMs) love

Get started for freeTalk to us