> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/elevenlabs/elevenlabs-python/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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.

<ParamField path="conversation_config" type="ConversationalConfig" required>
  Conversation configuration for an agent.
</ParamField>

<ParamField path="platform_settings" type="AgentPlatformSettingsRequestModel">
  Platform settings for the agent that aren't related to the conversation orchestration and content.
</ParamField>

<ParamField path="workflow" type="AgentWorkflowRequestModel">
  Workflow for the agent. This defines the flow of the conversation and how the agent interacts with tools.
</ParamField>

<ParamField path="name" type="str">
  A name to make the agent easier to find.
</ParamField>

<ParamField path="tags" type="Sequence[str]">
  Tags to help classify and filter the agent.
</ParamField>

<ParamField path="coaching_settings" type="dict">
  Coaching settings for the agent.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `CreateAgentResponseModel` with the created agent details.

**Example:**

```python theme={null}
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

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="version_id" type="str">
  The ID of the agent version to use.
</ParamField>

<ParamField path="branch_id" type="str">
  The ID of the branch to use.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `GetAgentResponseModel` with the agent configuration.

**Example:**

```python theme={null}
agent = client.conversational_ai.agents.get(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)
print(f"Agent name: {agent.name}")
```

***

### delete

```python theme={null}
client.conversational_ai.agents.delete(
    agent_id: str,
    request_options: Optional[RequestOptions] = None,
) -> None
```

Delete an agent.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Example:**

```python theme={null}
client.conversational_ai.agents.delete(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz"
)
```

***

### update

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="branch_id" type="str">
  The ID of the branch to use.
</ParamField>

<ParamField path="conversation_config" type="ConversationalConfig">
  Conversation configuration for an agent.
</ParamField>

<ParamField path="platform_settings" type="AgentPlatformSettingsRequestModel">
  Platform settings for the agent.
</ParamField>

<ParamField path="workflow" type="AgentWorkflowRequestModel">
  Workflow for the agent.
</ParamField>

<ParamField path="name" type="str">
  A name to make the agent easier to find.
</ParamField>

<ParamField path="tags" type="Sequence[str]">
  Tags to help classify and filter the agent.
</ParamField>

<ParamField path="coaching_settings" type="dict">
  Coaching settings for the agent.
</ParamField>

<ParamField path="version_description" type="str">
  Description for this version when publishing changes (only applicable for versioned agents).
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `GetAgentResponseModel` with the updated agent configuration.

**Example:**

```python theme={null}
updated_agent = client.conversational_ai.agents.update(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    name="Updated Support Agent",
    tags=["support", "v2"]
)
```

***

### list

```python theme={null}
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.

<ParamField path="page_size" type="int">
  How many agents to return at maximum. Cannot exceed 100, defaults to 30.
</ParamField>

<ParamField path="search" type="str">
  Search by agent name.
</ParamField>

<ParamField path="archived" type="bool">
  Filter agents by archived status.
</ParamField>

<ParamField path="show_only_owned_agents" type="bool">
  If set to true, omit agents shared by others and include only the ones you own.
</ParamField>

<ParamField path="sort_direction" type="SortDirection">
  The direction to sort the results ("asc" or "desc").
</ParamField>

<ParamField path="sort_by" type="AgentSortBy">
  The field to sort the results by (e.g., "name", "created\_at").
</ParamField>

<ParamField path="cursor" type="str">
  Used for fetching next page. Cursor is returned in the response.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `GetAgentsPageResponseModel` with paginated agent list.

**Example:**

```python theme={null}
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

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="name" type="str">
  A name to make the agent easier to find.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `CreateAgentResponseModel` with the duplicated agent details.

**Example:**

```python theme={null}
cloned_agent = client.conversational_ai.agents.duplicate(
    agent_id="agent_3701k3ttaq12ewp8b7qv5rfyszkz",
    name="Support Agent Copy"
)
```

***

### simulate\_conversation

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="simulation_specification" type="ConversationSimulationSpecification" required>
  A specification detailing how the conversation should be simulated.
</ParamField>

<ParamField path="extra_evaluation_criteria" type="Sequence[PromptEvaluationCriteria]">
  A list of evaluation criteria to test.
</ParamField>

<ParamField path="new_turns_limit" type="int">
  Maximum number of new turns to generate in the conversation simulation.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `AgentSimulatedChatTestResponseModel` with simulation results.

**Example:**

```python theme={null}
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

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent.
</ParamField>

<ParamField path="simulation_specification" type="ConversationSimulationSpecification" required>
  A specification detailing how the conversation should be simulated.
</ParamField>

<ParamField path="extra_evaluation_criteria" type="Sequence[PromptEvaluationCriteria]">
  A list of evaluation criteria to test.
</ParamField>

<ParamField path="new_turns_limit" type="int">
  Maximum number of new turns to generate in the conversation simulation.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

***

### run\_tests

```python theme={null}
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.

<ParamField path="agent_id" type="str" required>
  The ID of an agent. This is returned on agent creation.
</ParamField>

<ParamField path="tests" type="Sequence[SingleTestRunRequestModel]" required>
  List of tests to run on the agent.
</ParamField>

<ParamField path="agent_config_override" type="AdhocAgentConfigOverrideForTestRequestModel">
  Configuration overrides to use for testing. If not provided, the agent's default configuration will be used.
</ParamField>

<ParamField path="branch_id" type="str">
  ID of the branch to run the tests on. If not provided, the tests will be run on the agent default configuration.
</ParamField>

<ParamField path="request_options" type="RequestOptions">
  Request-specific configuration.
</ParamField>

**Returns:** `GetTestSuiteInvocationResponseModel` with test results.

**Example:**

```python theme={null}
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:

```python theme={null}
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())
```