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

# Update Agent

> Update an existing AI agent's configuration

Update any configuration fields for an existing AI agent. Only include fields you want to change.

## Request Body

<ParamField body="agent_id" type="string" required>
  The unique identifier of the agent to update.
</ParamField>

<ParamField body="name" type="string">
  Agent display name (max 100 characters).
</ParamField>

<ParamField body="greeting" type="string">
  Message spoken when answering calls (max 500 characters).
</ParamField>

<ParamField body="system_prompt" type="string">
  Instructions defining the agent's behavior (max 10,000 characters).
</ParamField>

<ParamField body="voice_id" type="string">
  Voice for phone calls. Use the [List Voices](/api-reference/endpoints/list-voices) endpoint to get all available options, including any cloned voices on your account.

  **ElevenLabs voices:**

  | Voice ID               | Name    | Description                   |
  | ---------------------- | ------- | ----------------------------- |
  | `EXAVITQu4vr4xnSDxMaL` | Sarah   | Professional, American female |
  | `MF3mGyEYCl7XYWbV9V6O` | Elli    | Youthful, American female     |
  | `TxGEqnHWrfWFTfGW9XjX` | Josh    | Strong, American male         |
  | `pFZP5JQG7iQjIQuC4Bku` | Lily    | Confident, British female     |
  | `nPczCjzI2devNBz1zQrb` | Brian   | Classy, American male         |
  | `onwK4e9ZLuTAKqWW03F9` | Daniel  | Formal, British male          |
  | `cjVigY5qzO86Huf0OWal` | Eric    | Friendly, American male       |
  | `cgSgspJ2msm6clMCkdW9` | Jessica | Expressive, American female   |
  | `XrExE9yKIg1WjnnlVkGX` | Matilda | Upbeat, American female       |
  | `CwhRBWXzGAHq8TQ4Fs17` | Roger   | Classy, American male         |
  | `FGY2WhTYpPnrIDTdsKH5` | Laura   | Sassy, American female        |
  | `IKne3meq5aSn9XLyUdCD` | Charlie | Hyped, Australian male        |
  | `JBFqnCBsd6RMkjVDRZzb` | George  | Mature, British male          |
  | `N2lVS1w4EtoT3dr4eOWO` | Callum  | Husky, American male          |
  | `SAz9YHcvj6GT2YYXdXww` | River   | Calm, neutral American        |
  | `SOYHLrjzK2X1ezoPC6cr` | Harry   | Rough, American male          |
  | `TX3LPaxmHKxFdv7VOQHJ` | Liam    | Confident, American male      |
  | `Xb7hH8MSUJpSbSDYk0k2` | Alice   | Professional, British female  |
  | `bIHbv24MWmeRgasZH58o` | Will    | Chill, American male          |
  | `hpp4J3VqNfWAUOO0d1Us` | Bella   | Professional, American female |
  | `iP95p4xoKVk53GoZ742B` | Chris   | Casual, American male         |
  | `pNInz6obpgDQGcFmaJgB` | Adam    | Deep, American male           |
  | `pqHfZKP75CvOlQylNhV4` | Bill    | Trustworthy, American male    |

  **OpenAI voices** (prefix `openai-`):

  | Voice ID         | Name    | Description           |
  | ---------------- | ------- | --------------------- |
  | `openai-alloy`   | Alloy   | Neutral, professional |
  | `openai-echo`    | Echo    | Warm, friendly        |
  | `openai-fable`   | Fable   | Expressive, dynamic   |
  | `openai-nova`    | Nova    | Bright, energetic     |
  | `openai-onyx`    | Onyx    | Deep, authoritative   |
  | `openai-shimmer` | Shimmer | Soft, calm            |
</ParamField>

<ParamField body="llm_model" type="string">
  LLM model for conversation.

  | Model ID       | Description                                               |
  | -------------- | --------------------------------------------------------- |
  | `gpt-4.1`      | Recommended — best balance of speed and quality (default) |
  | `gpt-4.1-mini` | Fast and cost-effective                                   |
  | `gpt-4o-mini`  | Fast and cost-effective                                   |
  | `gpt-4o`       | Most capable, higher latency                              |
</ParamField>

<ParamField body="language" type="string">
  Language code (e.g., `en-US`, `es-ES`).
</ParamField>

<ParamField body="max_call_duration" type="integer">
  Maximum call duration in seconds (60 to 3600).
</ParamField>

<ParamField body="end_call_phrases" type="array">
  Phrases that trigger call termination.
</ParamField>

<ParamField body="transfer_phone_number" type="string">
  Phone number for call transfers.
</ParamField>

<ParamField body="is_active" type="boolean">
  Enable or disable the agent.
</ParamField>

<ParamField body="functions" type="object">
  Configuration for agent functions. See [Create Agent](/api-reference/endpoints/create-agent) for full schema.

  **Example - Enable transfer with multiple numbers:**

  ```json theme={null}
  {
    "transfer": {
      "enabled": true,
      "numbers": [
        { "number": "+14155551234", "label": "Sales", "description": "Transfer for sales inquiries" }
      ]
    }
  }
  ```

  **Example - Configure end call:**

  ```json theme={null}
  {
    "end_call": {
      "enabled": true,
      "description": "End the call after confirming the appointment."
    }
  }
  ```
</ParamField>

<ParamField body="dynamic_variables" type="array">
  Dynamic variables for extracting structured data from conversations. Replaces all existing variables for this agent.

  Each variable object:

  * `name` (string, required) — Variable name (e.g., `caller_name`)
  * `description` (string) — What to extract
  * `var_type` (string) — `text` (default), `number`, `boolean`, or `enum`
  * `enum_options` (array) — Required when `var_type` is `enum`

  ```json theme={null}
  [
    {"name": "caller_name", "description": "Full name of the caller", "var_type": "text"},
    {"name": "priority", "description": "Call priority level", "var_type": "enum", "enum_options": ["low", "medium", "high"]}
  ]
  ```
</ParamField>

<ParamField body="memory_enabled" type="boolean">
  Enable [caller memory](/features/agent-memory) — the agent remembers past conversations with each contact.
</ParamField>

<ParamField body="memory_config" type="object">
  Configuration for caller memory. Only applies when `memory_enabled` is `true`.

  | Property              | Type    | Default | Description                                              |
  | --------------------- | ------- | ------- | -------------------------------------------------------- |
  | `include_summaries`   | boolean | `true`  | Include AI-generated relationship summary in context     |
  | `max_history_calls`   | number  | `5`     | Number of recent calls to consider when building context |
  | `include_key_topics`  | boolean | `true`  | Include key topics in context                            |
  | `include_preferences` | boolean | `true`  | Include caller preferences in context                    |

  ```json theme={null}
  {
    "include_summaries": true,
    "max_history_calls": 10,
    "include_key_topics": true,
    "include_preferences": true
  }
  ```
</ParamField>

<ParamField body="semantic_memory_enabled" type="boolean">
  Enable [semantic memory](/features/agent-memory#semantic-memory) — the agent finds similar past conversations across all contacts using AI embeddings.
</ParamField>

<ParamField body="semantic_memory_config" type="object">
  Configuration for semantic memory. Only applies when `semantic_memory_enabled` is `true`.

  | Property                | Type    | Default | Description                                |
  | ----------------------- | ------- | ------- | ------------------------------------------ |
  | `max_results`           | number  | `3`     | Number of similar conversations to include |
  | `similarity_threshold`  | number  | `0.75`  | Minimum similarity score (0.6–0.85)        |
  | `include_other_callers` | boolean | `true`  | Include conversations from other contacts  |

  ```json theme={null}
  {
    "max_results": 5,
    "similarity_threshold": 0.75,
    "include_other_callers": true
  }
  ```
</ParamField>

<ParamField body="shared_memory_agent_ids" type="array">
  Array of agent UUIDs that share memory with this agent. Allows multiple agents to access the same contact memories.

  ```json theme={null}
  ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"]
  ```
</ParamField>

<ParamField body="recording_enabled" type="boolean">
  Whether calls handled by this agent are recorded. Defaults to `true`. Set to `false` to disable recording for all calls routed to this agent (both inbound and outbound).

  ```json theme={null}
  { "agent_id": "550e8400-e29b-41d4-a716-446655440000", "recording_enabled": false }
  ```
</ParamField>

## Response

Returns the updated agent object.

<RequestExample>
  ```bash cURL — Update greeting and model theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/update-agent \
    -H "Authorization: Bearer mgp_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "greeting": "Hi there! Thanks for calling Acme Dental. How can I help you?",
      "llm_model": "gpt-4.1"
    }'
  ```

  ```bash cURL — Change voice theme={null}
  curl -X POST https://api.magpipe.ai/functions/v1/update-agent \
    -H "Authorization: Bearer mgp_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "550e8400-e29b-41d4-a716-446655440000",
      "voice_id": "nPczCjzI2devNBz1zQrb"
    }'
  ```

  ```javascript Node.js theme={null}
  // Update greeting and model
  const response = await fetch(
    'https://api.magpipe.ai/functions/v1/update-agent',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer mgp_your_api_key',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        agent_id: '550e8400-e29b-41d4-a716-446655440000',
        greeting: 'Hi there! Thanks for calling Acme Dental. How can I help you?',
        llm_model: 'gpt-4.1',
      }),
    }
  );

  const agent = await response.json();
  console.log('Updated:', agent.updated_at);

  // Change voice to Brian
  await fetch('https://api.magpipe.ai/functions/v1/update-agent', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer mgp_your_api_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      agent_id: '550e8400-e29b-41d4-a716-446655440000',
      voice_id: 'nPczCjzI2devNBz1zQrb',
    }),
  });
  ```

  ```python Python theme={null}
  import requests

  # Update greeting and model
  response = requests.post(
      'https://api.magpipe.ai/functions/v1/update-agent',
      headers={
          'Authorization': 'Bearer mgp_your_api_key',
          'Content-Type': 'application/json',
      },
      json={
          'agent_id': '550e8400-e29b-41d4-a716-446655440000',
          'greeting': 'Hi there! Thanks for calling Acme Dental. How can I help you?',
          'llm_model': 'gpt-4.1',
      }
  )
  print(f"Updated: {response.json()['updated_at']}")

  # Change voice to Brian
  requests.post(
      'https://api.magpipe.ai/functions/v1/update-agent',
      headers={
          'Authorization': 'Bearer mgp_your_api_key',
          'Content-Type': 'application/json',
      },
      json={
          'agent_id': '550e8400-e29b-41d4-a716-446655440000',
          'voice_id': 'nPczCjzI2devNBz1zQrb',
      }
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Sarah - Receptionist",
    "greeting": "Hi there! Thanks for calling Acme Dental. How can I help you?",
    "llm_model": "gpt-4o",
    "updated_at": "2024-01-16T09:15:00Z",
    "dynamic_variables": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "caller_name",
        "description": "Full name of the caller",
        "var_type": "text",
        "enum_options": null,
        "created_at": "2024-01-10T10:00:00Z",
        "updated_at": "2024-01-10T10:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>