> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xuna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get, update, list, and delete Conversational AI agents

> Retrieve, update, list, and delete voice agents using the XUNA AI Conversational AI REST API with Python and TypeScript examples.

Once you have created an agent, you can retrieve its configuration, apply partial updates, list all agents in your account, or delete agents you no longer need.

## Get an agent

Retrieve the full configuration object for a single agent.

```
GET https://api.xuna.ai/v1/convai/agents/{agent_id}
```

<ParamField path="agent_id" type="string" required>
  The ID of the agent to retrieve.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  agent = client.conversational_ai.agents.get(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  print(agent)
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.conversationalAi.agents.get(
      "agent_7101k5zvyjhmfg983brhmhkd98n6"
  );
  console.log(agent);
  ```

  ```bash cURL theme={null}
  curl https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

The response contains the full `conversation_config` object, metadata, and any knowledge base or tool attachments.

***

## Update an agent

Apply a partial update to an existing agent. Only the fields you include in the request body are changed.

```
PATCH https://api.xuna.ai/v1/convai/agents/{agent_id}
```

<ParamField path="agent_id" type="string" required>
  The ID of the agent to update.
</ParamField>

<ParamField body="conversation_config" type="object">
  Partial conversation config. Provide only the fields you want to change.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  client.conversational_ai.agents.update(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
      conversation_config={
          "agent": {
              "first_message": "Hello! How can I assist you today?",
          }
      },
  )
  ```

  ```typescript TypeScript theme={null}
  await client.conversationalAi.agents.update(
      "agent_7101k5zvyjhmfg983brhmhkd98n6",
      {
          conversationConfig: {
              agent: {
                  firstMessage: "Hello! How can I assist you today?",
              },
          },
      }
  );
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "conversation_config": {
        "agent": {
          "first_message": "Hello! How can I assist you today?"
        }
      }
    }'
  ```
</CodeGroup>

<Tip>
  Use PATCH to iterate quickly on your agent's prompt and voice without recreating it. All existing settings outside the updated fields are preserved.
</Tip>

***

## List agents

Return all agents in your account.

```
GET https://api.xuna.ai/v1/convai/agents
```

<CodeGroup>
  ```python Python theme={null}
  result = client.conversational_ai.agents.list()
  for agent in result.agents:
      print(agent.agent_id, agent.name)
  ```

  ```typescript TypeScript theme={null}
  const result = await client.conversationalAi.agents.list();
  for (const agent of result.agents) {
      console.log(agent.agentId, agent.name);
  }
  ```

  ```bash cURL theme={null}
  curl https://api.xuna.ai/v1/convai/agents \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

**Response:**

<ResponseField name="agents" type="object[]" required>
  Array of agent summary objects. Each entry includes `agent_id`, `name`, `tags`, and creation timestamps.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Indicates whether additional pages of results are available.
</ResponseField>

***

## Delete an agent

Permanently delete an agent. This action cannot be undone.

```
DELETE https://api.xuna.ai/v1/convai/agents/{agent_id}
```

<ParamField path="agent_id" type="string" required>
  The ID of the agent to delete.
</ParamField>

<CodeGroup>
  ```python Python theme={null}
  client.conversational_ai.agents.delete(
      agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6"
  )
  print("Agent deleted.")
  ```

  ```typescript TypeScript theme={null}
  await client.conversationalAi.agents.delete(
      "agent_7101k5zvyjhmfg983brhmhkd98n6"
  );
  console.log("Agent deleted.");
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.xuna.ai/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6 \
    -H "x-api-key: YOUR_API_KEY"
  ```
</CodeGroup>

<Warning>
  Deleting an agent also removes its association with any phone numbers. Assign a different agent to those numbers before deleting if you want inbound calls to continue.
</Warning>