Agents Client

Reference for agent management methods

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())