Agents Platform

Patches An Agent Settings

Changed on

Patches an Agent settings

patch/v1/convai/agents/{agent_id}

Request

  • Base URL
    https://api.elevenlabs.io (the document declares no server; this is the origin it was published from)
  • URL
    https://api.elevenlabs.io/v1/convai/agents/{agent_id}
  • Auth
    none declared

Path parameters

agent_idstring required

The id of an agent. This is returned on agent creation.

Example:agent_3701k3ttaq12ewp8b7qv5rfyszkz

Query parameters

enable_versioning_if_not_enabledboolean

Deprecated: all agents are versioned. This parameter is ignored.

branch_idstring nullable

The ID of the branch to use

Example:agtbranch_0901k4aafjxxfxt93gd841r7tv5t
include_procedure_generated_workflow_elementsboolean

Whether to include the workflow nodes and edges generated from structured procedures. When false, the workflow contains only authored elements.

Headers

xi-api-keystring nullable

Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website.

Request body

conversation_configobject nullable

Conversation configuration for an agent

platform_settingsobject nullable

Platform settings for the agent are all settings that aren't related to the conversation orchestration and content.

namestring nullable

A name to make the agent easier to find

tagsstring[] nullable

Tags to help classify and filter the agent

version_descriptionstring nullable

Description for this version when publishing changes (only applicable for versioned agents)

proceduresobject nullable

Procedure versions to publish, keyed by procedure_id. When provided, this map replaces the procedures from the current draft or branch tip. When omitted or null, unpublished procedure edits are used if present; otherwise, the branch tip's procedures are retained. Pass an empty object to remove all procedures.

Example request

{
  "workflow": {
    "edges": {
      "entry_to_tool_a": {
        "forward_condition": {
          "condition": "Tool A condition"
        },
        "source": "entry_node",
        "target": "tool_node_a"
      },
      "start_to_entry": {
        "forward_condition": {},
        "source": "start_node",
        "target": "entry_node"
      },
      "tool_a_to_failure": {
        "forward_condition": {
          "successful": false
        },
        "source": "tool_node_a",
        "target": "failure_node"
      },
      "tool_a_to_tool_b": {
        "forward_condition": {
          "successful": true
        },
        "source": "tool_node_a",
        "target": "tool_node_b"
      },
      "tool_b_to_agent_transfer": {
        "forward_condition": {},
        "source": "tool_node_b",
        "target": "success_transfer"
      },
      "tool_b_to_conversation": {
        "forward_condition": {
          "condition": "Conversation condition"
        },
        "source": "tool_node_b",
        "target": "success_conversation"
      },
      "tool_b_to_end": {
        "forward_condition": {
          "condition": "End condition"
        },
        "source": "tool_node_b",
        "target": "success_end"
      },
      "tool_b_to_phone": {
        "forward_condition": {
          "expression": {
            "children": [
              {
                "name": "force_phone_transfer"
              },
              {
                "prompt": "Phone condition",
                "value_schema": {
                  "description": "Phone condition",
                  "type": "boolean"
                }
              },
              {
                "left": {
                  "name": "mode"
                },
                "right": {
                  "value": "dev"
                }
              }
            ]
          }
        },
        "source": "tool_node_b",
        "target": "success_phone"
      }
    },
    "nodes": {
      "entry_node": {
        "conversation_config": {},
        "edge_order": [
          "entry_to_tool_a"
        ],
        "label": "Entry"
      },
      "failure_node": {
        "conversation_config": {},
        "label": "Failure"
      },
      "start_node": {
        "edge_order": [
          "start_to_entry"
        ]
      },
      "success_conversation": {
        "conversation_config": {},
        "label": "Success A"
      },
      "success_end": {},
      "success_phone": {
        "transfer_destination": {
          "phone_number": "+1234567890"
        }
      },
      "success_transfer": {
        "agent_id": "success_transfer_agent"
      },
      "tool_node_a": {
        "edge_order": [
          "tool_a_to_failure",
          "tool_a_to_tool_b"
        ],
        "tools": [
          {
            "tool_id": "tool_a"
          },
          {
            "tool_id": "tool_b"
          }
        ]
      },
      "tool_node_b": {
        "edge_order": [
          "tool_b_to_conversation",
          "tool_b_to_end",
          "tool_b_to_phone",
          "tool_b_to_agent_transfer"
        ],
        "tools": [
          {
            "tool_id": "tool_a"
          }
        ]
      }
    }
  },
  "name": "My agent",
  "tags": [
    "Customer Support",
    "Technical Help",
    "Eleven"
  ]
}

Response

Successful Response

agent_idstring required

The ID of the agent

namestring required

The name of the agent

tagsstring[]

Agent tags used to categorize the agent

version_idstring nullable

The ID of the version the agent is on

branch_idstring nullable

The ID of the branch the agent is on

main_branch_idstring nullable

The ID of the main branch for this agent

proceduresobject

Procedures keyed by procedure_id.

default_hold_audio_urlstring

URL of the default hold tone played to queued callers when no custom hold audio is uploaded, so the dashboard can preview it.

Example response

{
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "name": "My Agent",
  "workflow": {
    "edges": {
      "entry_to_tool_a": {
        "forward_condition": {
          "condition": "Tool A condition",
          "type": "llm"
        },
        "source": "entry_node",
        "target": "tool_node_a"
      },
      "start_to_entry": {
        "forward_condition": {
          "type": "unconditional"
        },
        "source": "start_node",
        "target": "entry_node"
      },
      "tool_a_to_failure": {
        "forward_condition": {
          "successful": false,
          "type": "result"
        },
        "source": "tool_node_a",
        "target": "failure_node"
      },
      "tool_a_to_tool_b": {
        "forward_condition": {
          "successful": true,
          "type": "result"
        },
        "source": "tool_node_a",
        "target": "tool_node_b"
      },
      "tool_b_to_agent_transfer": {
        "forward_condition": {
          "type": "unconditional"
        },
        "source": "tool_node_b",
        "target": "success_transfer"
      },
      "tool_b_to_conversation": {
        "forward_condition": {
          "condition": "Conversation condition",
          "type": "llm"
        },
        "source": "tool_node_b",
        "target": "success_conversation"
      },
      "tool_b_to_end": {
        "forward_condition": {
          "condition": "End condition",
          "type": "llm"
        },
        "source": "tool_node_b",
        "target": "success_end"
      },
      "tool_b_to_phone": {
        "forward_condition": {
          "expression": {
            "children": [
              {
                "name": "force_phone_transfer",
                "type": "dynamic_variable"
              },
              {
                "prompt": "Phone condition",
                "type": "llm",
                "value_schema": {
                  "description": "Phone condition",
                  "type": "boolean"
                }
              },
              {
                "left": {
                  "name": "mode",
                  "type": "dynamic_variable"
                },
                "right": {
                  "type": "string_literal",
                  "value": "dev"
                },
                "type": "eq_operator"
              }
            ],
            "type": "or_operator"
          },
          "type": "expression"
        },
        "source": "tool_node_b",
        "target": "success_phone"
      }
    },
    "nodes": {
      "entry_node": {
        "additional_knowledge_base": [],
        "additional_prompt": "",
        "additional_tool_ids": [],
        "conversation_config": {},
        "edge_order": [
          "entry_to_tool_a"
        ],
        "entry_behavior": "auto",
        "label": "Entry",
        "position": {
          "x": 0,
          "y": 0
        },
        "type": "override_agent"
      },
      "failure_node": {
        "additional_knowledge_base": [],
        "additional_prompt": "",
        "additional_tool_ids": [],
        "conversation_config": {},
        "edge_order": [],
        "entry_behavior": "auto",
        "label": "Failure",
        "position": {
          "x": 0,
          "y": 0
        },
        "type": "override_agent"
      },
      "start_node": {
        "edge_order": [
          "start_to_entry"
        ],
        "position": {
          "x": 0,
          "y": 0
        },
        "type": "start"
      },
      "success_conversation": {
        "additional_knowledge_base": [],
        "additional_prompt": "",
        "additional_tool_ids": [],
        "conversation_config": {},
        "edge_order": [],
        "entry_behavior": "auto",
        "label": "Success A",
        "position": {
          "x": 0,
          "y": 0
        },
        "type": "override_agent"
      },
      "success_end": {
        "edge_order": [],
        "outcome": "success",
        "position": {
          "x": 0,
          "y": 0
        },
        "type": "end"
      },
      "success_phone": {
        "custom_sip_headers": [],
        "edge_order": [],
        "position": {
          "x": 0,
          "y": 0
        },
        "require_acceptance": false,
        "sip_refer_play_dialtone": true,
        "transfer_destination": {
          "phone_number": "+1234567890",
          "type": "phone"
        },
        "transfer_type": "conference",
        "type": "phone_number"
      },
      "success_transfer": {
        "agent_id": "success_transfer_agent",
        "delay_ms": 0,
        "drop_history": false,
        "edge_order": [],
        "enable_transferred_agent_first_message": false,
        "isolate_history": false,
        "position": {
          "x": 0,
          "y": 0
        },
        "preserve_client_tts_overrides": false,
        "preserve_voice_settings": false,
        "type": "standalone_agent"
      },
      "tool_node_a": {
        "edge_order": [
          "tool_a_to_failure",
          "tool_a_to_tool_b"
        ],
        "position": {
          "x": 0,
          "y": 0
        },
        "tools": [
          {
            "tool_id": "tool_a"
          },
          {
            "tool_id": "tool_b"
          }
        ],
        "type": "tool"
      },
      "tool_node_b": {
        "edge_order": [
          "tool_b_to_conversation",
          "tool_b_to_end",
          "tool_b_to_phone",
          "tool_b_to_agent_transfer"
        ],
        "position": {
          "x": 0,
          "y": 0
        },
        "tools": [
          {
            "tool_id": "tool_a"
          }
        ],
        "type": "tool"
      }
    },
    "prevent_subagent_loops": false,
    "subgraphs": {}
  }
}

Changes

  • 47dc9e66d680Revision changes
    • info

      added the optional property // to the response with the status

  • 54c5819bbe5dRevision changes
    • breaking

      added to the ////// response property oneOf list for the response status

    • breaking

      added to the ///////////// response property oneOf list for the response status

    • warning

      removed the request property ///////////////

    • warning

      removed the request property ///////////////

    • warning

      removed the optional property //////// from the response with the status

    • warning

      removed the optional property //////// from the response with the status

    • warning

      removed the optional property /////////////// from the response with the status

    • warning

      removed the optional property /////////////// from the response with the status

    • info

      added the new optional request property ///////////////

    • info

      added the new optional request property ///////////////

    • info

      added owner_get_client_appointments owner_list_assets owner_list_locations owner_list_products owner_list_services owner_list_staff discriminator mapping keys to the ///////////// request property

    • info

      added to the ///////////// request property oneOf list

    • info

      added the optional property //////// to the response with the status

    • info

      added the optional property //////// to the response with the status

    • info

      added the optional property /////////////// to the response with the status

    • info

      added the optional property /////////////// to the response with the status

    • info

      added owner_get_client_appointments owner_list_assets owner_list_locations owner_list_products owner_list_services owner_list_staff discriminator mapping keys to the ////// response property for the response status

    • info

      added owner_get_client_appointments owner_list_assets owner_list_locations owner_list_products owner_list_services owner_list_staff discriminator mapping keys to the ///////////// response property for the response status