agents

Name: agents
Author: elevenlabs

ElevenLabs Agents 平台

使用自然對話、多種 LLM 供應商、自訂工具及簡易網頁嵌入，打造語音 AI 代理。

設定： 請參閱安裝指南了解 CLI 與 SDK 設定。

使用 CLI 快速開始

ElevenLabs CLI 是建立與管理代理的推薦方式：

# 安裝 CLI 並進行驗證
npm install -g @elevenlabs/cli
elevenlabs auth login

# 初始化專案並建立代理
elevenlabs agents init
elevenlabs agents add "我的助理" --template complete

# 推送至 ElevenLabs 平台
elevenlabs agents push

可用模板： complete、minimal、voice-only、text-only、customer-service、assistant

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

agent = client.conversational_ai.agents.create(
    name="我的助理",
    conversation_config={
        "agent": {
            "first_message": "你好！有什麼可以幫你的嗎？",
            "language": "zh-TW",
            "prompt": {
                "prompt": "你是一個樂於助人的助理。請保持簡潔且友善。",
                "llm": "gemini-2.0-flash",
                "temperature": 0.7
            }
        },
        "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}
    }
)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient();

const agent = await client.conversationalAi.agents.create({
  name: "我的助理",
  conversationConfig: {
    agent: {
      firstMessage: "你好！有什麼可以幫你的嗎？",
      language: "zh-TW",
      prompt: {
        prompt: "你是一個樂於助人的助理。",
        llm: "gemini-2.0-flash",
        temperature: 0.7
      }
    },
    tts: { voiceId: "JBFqnCBsd6RMkjVDRZzb" }
  }
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/agents/create" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "我的助理", "conversation_config": {"agent": {"first_message": "你好！", "language": "zh-TW", "prompt": {"prompt": "你是一個樂於助人的助理。", "llm": "gemini-2.0-flash"}}, "tts": {"voice_id": "JBFqnCBsd6RMkjVDRZzb"}}}'

開始對話

暫時的 LiveKit WebSocket 固定版本

在 ElevenLabs LiveKit 伺服器支援 /rtc/v1 之前，使用 WebRTC 的瀏覽器用戶端可能會在底層 LiveKit WebSocket 握手過程中失敗或停滯，特別是使用 livekit-client 版本新於 2.16.1 時。對於使用 connectionType: "webrtc" 或連線到 wss://livekit.rtc.elevenlabs.io/rtc/v1 的 React、Next.js、Electron 或其他 @elevenlabs/client / @elevenlabs/react 整合，請在 package.json 中加入此暫時固定版本：

{
  "overrides": {
    "livekit-client": "2.16.1"
  }
}

當應用程式在會話啟動期間記錄 /rtc/v1 404、v1 RTC path not found 或 could not establish pc connection 時，請使用此固定版本。這是針對 WebRTC 會話的 LiveKit 伺服器相容性解決方案，而非 ElevenLabs 的 connectionType: "websocket" 傳輸方式。待上游 LiveKit 伺服器或 SDK 問題修復後，即可移除。

伺服器端 (Python)： 取得用戶端連線的簽署 URL：

signed_url = client.conversational_ai.conversations.get_signed_url(
    agent_id="your-agent-id",
    environment="staging",
)

用戶端 (JavaScript)：

import { Conversation } from "@elevenlabs/client";

const conversation = await Conversation.startSession({
  agentId: "your-agent-id",
  environment: "staging",
  overrides: { asr: { keywords: ["ElevenLabs", "TechCorp"] } },
  onMessage: (msg) => console.log("代理：", msg.message),
  onUserTranscript: (t) => console.log("使用者：", t.message),
  onPing: (event) => console.log("估計延遲：", event.ping_ms),
  onError: (e) => console.error(e)
});

React Hook： 將 hook 消費者包裹在 ConversationProvider 中。建議使用細粒度 hook，例如 useConversationControls 和 useConversationStatus 來控制會話與 UI 狀態；useConversation 仍可作為便利的全功能 hook 使用。當您希望 React 在單一位置處理會話錯誤時，請傳遞提供者層級的回呼，例如 onError。

import {
  ConversationProvider,
  useConversationControls,
  useConversationStatus,
} from "@elevenlabs/react";

function Agent({ signedUrl }: { signedUrl: string }) {
  const { startSession, endSession } = useConversationControls();
  const { status } = useConversationStatus();

  if (status === "connected") {
    return <button onClick={endSession}>結束對話</button>;
  }

  return (
    <button onClick={() => startSession({ signedUrl })}>
      開始對話
    </button>
  );
}

function App({ signedUrl }: { signedUrl: string }) {
  return (
    <ConversationProvider
      onError={(error) => console.error("會話錯誤：", error)}
      onPing={(event) => console.log("估計延遲：", event.ping_ms)}
    >
      <Agent signedUrl={signedUrl} />
    </ConversationProvider>
  );
}

設定

供應商	模型
OpenAI	`gpt-5.5`, `gpt-5.5-2026-04-23`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.4-nano`, `gpt-5.4-2026-03-05`, `gpt-5.4-mini-2026-03-17`, `gpt-5.4-nano-2026-03-17`, `gpt-5`, `gpt-5-mini`, `gpt-5-nano`, `gpt-4.1`, `gpt-4.1-mini`, `gpt-4.1-nano`, `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
Anthropic	`claude-opus-4-7`, `claude-sonnet-4-6`, `claude-sonnet-4-5`, `claude-sonnet-4`, `claude-haiku-4-5`, `claude-3-7-sonnet`, `claude-3-5-sonnet`, `claude-3-haiku`
Google	`gemini-3.1-flash-lite-preview`, `gemini-3.1-pro-preview`, `gemini-3-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-2.0-flash`, `gemini-2.0-flash-lite`
ElevenLabs	`glm-45-air-fp8`, `qwen3-30b-a3b`, `qwen36-35b-a3b`, `qwen35-35b-a3b`, `qwen35-397b-a17b`, `gpt-oss-120b`
自訂	`custom-llm` (自備端點)

使用 GET /v1/convai/llm/list 查看當前模型目錄，包括棄用狀態、Token/上下文限制、功能標誌 (如圖片輸入支援) 以及特定模型的推理努力支援。

熱門語音： JBFqnCBsd6RMkjVDRZzb (George)、EXAVITQu4vr4xnSDxMaL (Sarah)、onwK4e9ZLuTAKqWW03F9 (Daniel)、XB0fDUnXU5powFXDhCwa (Charlotte)

回應積極度： patient (等待使用者說完較久)、normal 或 eager (快速回應)

請參閱代理設定了解所有選項。

系統提示結構

使用 Markdown 標題分段提示——模型會更可靠地優先處理和解釋指令 (提示指南)：

# 個性   – 命名角色，2-3 個特質
# 環境   – 工作場所，交談對象
# 語氣   – 語音風格，4-5 個要點
# 目標   – 成功的定義 (多步驟流程請使用編號)

保持指令簡短且以行動為導向。將關鍵步驟標記為「此步驟很重要」。對於關鍵的拒絕/安全規則，請在提示中包含簡潔的指令，並同時透過 platform_settings.guardrails 設定獨立的客製護欄 (請參閱護欄)。

工具

透過 Webhook、用戶端或內建系統工具擴展代理。工具定義在 conversation_config.agent.prompt 中：

工作區環境變數可以解析每個環境的伺服器工具 URL、標頭和驗證連線，而執行時期系統變數 (例如 {{system__conversation_history}}) 可以在需要時將完整的對話上下文傳遞給工具呼叫。

"prompt": {
    "prompt": "你是一個可以查詢天氣的樂於助人助理。",
    "llm": "gemini-2.0-flash",
    "tools": [
        # Webhook：伺服器端 API 呼叫
        {"type": "webhook", "name": "get_weather", "description": "取得天氣",
         "api_schema": {"url": "https://api.example.com/weather", "method": "POST",
             "request_body_schema": {"type": "object", "properties": {"location": {"type": "string"}}, "required": ["location"]}}},
        # 用戶端：在瀏覽器中執行
        {"type": "client", "name": "show_product", "description": "顯示產品",
         "parameters": {"type": "object", "properties": {"productId": {"type": "string"}}, "required": ["productId"]}}
    ],
    "built_in_tools": {
        "end_call": {},
        "transfer_to_number": {"transfers": [{"transfer_destination": {"type": "phone", "phone_number": "+1234567890"}, "condition": "使用者要求真人客服"}]},
        "start_procedure": {}
    }
}

用戶端工具 在瀏覽器中執行：

clientTools: {
  show_product: async ({ productId }) => {
    document.getElementById("product").src = `/products/${productId}`;
    return { success: true };
  }
}

請參閱用戶端工具參考了解完整文件。

內建系統工具

在 conversation_config.agent.prompt.built_in_tools 下設定。{} 啟用預設值；提供 description 以自訂；省略則停用。

工具	啟用時機
`end_call`	所有代理
`language_detection`	多語言代理
`transfer_to_number`	電話轉接真人客服
`transfer_to_agent`	多代理工作流程
`start_procedure`	程序引導對話
`end_procedure`	完成進行中的程序
`skip_turn`	教學/輔導 (靜默聆聽)
`voicemail_detection`	外撥電話
`play_keypad_touch_tone`	IVR 導航

run_subagent 是一個系統工具，用於將任務委派給另一個已設定的代理。將其加入 conversation_config.agent.prompt.tools，並使用 params.system_tool_type: "run_subagent" 和一個 agents 陣列。每個項目需要 agent_id 和 description；branch_id 和 JSON schema 的 parameters 物件為選填。

整合工具

由平台管理的預建連接器。建立包含憑證的連線，然後透過 tool_ids 附加：

整合	使用案例
`calcom`	預約排程
`salesforce`	CRM 查詢、案件建立
`hubspot`	CRM、行銷、聯絡人
`zendesk`	支援工單

三步驟流程：POST /v1/convai/api-integrations/{id}/connections → GET /v1/convai/api-integrations/{id}/tools → POST /v1/convai/tools，並帶入 api_integration_id 和 api_integration_connection_id。使用 "prompt": {"tool_ids": ["tool_xxxx"]} 附加到代理。內聯 tools 和 tool_ids 可以共存——建議優先使用整合工具而非重複的自訂 Webhook。

公開 API Webhook 範例

適用於原型開發的無驗證 API (URL 必須為 HTTPS)：

工具	URL	用途
`get_weather`	`https://wttr.in/{location}?format=j1`	目前天氣
`search_wikipedia`	`https://en.wikipedia.org/api/rest_v1/page/summary/{topic}`	主題摘要
`get_exchange_rate`	`https://open.er-api.com/v6/latest/{base_currency}`	匯率

工作流程

透過分支邏輯將對話路由到離散步驟。在代理頂層的 workflow 欄位中定義。參考：代理工作流程。

節點類型： start (ID 必須為 "start_node")、end、override_agent (子代理步驟，包含 label + additional_prompt)、dispatch_tool (執行工具，包含成功/失敗路由)、agent_transfer、transfer_to_number。

邊緣類型： unconditional、llm (自然語言條件)、expression (確定性資料檢查)。工具節點有獨立的成功/失敗邊緣。

為每個步驟限定工具範圍，在節點上使用 additional_tool_ids——防止錯誤工具在錯誤步驟觸發。在對話路由節點 (例如問候和 classify_intent) 上設定 additional_tool_ids: []，使其僅進行對話：

{
  "type": "override_agent",
  "label": "預約掛號",
  "additional_prompt": "討論偏好的日期和醫生。達成共識後顯示預約表單。",
  "entry_behavior": "wait_for_user",
  "additional_tool_ids": ["show_booking_form", "display_appointment_card"],
  "position": {"x": 0, "y": 400}
}

在每個節點上包含 position ({x, y})，以便編輯器能乾淨呈現。從 y=0 開始，將 end 放在底部，並將分支水平間隔在 x=-150 和 x=150；建議的間距為垂直層級之間 200px，水平分支之間 300px。保持工作流程在 4-7 個節點，並始終確保有通往 end 的路徑。

在 override_agent 節點上使用 entry_behavior 來選擇子代理是立即發言 (generate_immediately)、等待使用者輸入 (wait_for_user)，還是讓平台決定 (auto)。

對於巢狀代理轉移，請在 standalone_agent 節點上設定 enable_nesting，並在應將控制權返回給父工作流程的 end 節點上設定 return_when_nested。

護欄

獨立於 LLM 運行的分層安全執行——在 platform_settings.guardrails 下設定，而非系統提示中。參考：護欄。

"platform_settings": {
  "guardrails": {
    "version": "1",
    "focus": {"is_enabled": true},
    "prompt_injection": {"is_enabled": true},
    "content": {"config": {"harassment": {"is_enabled": true, "threshold": 0.5}}},
    "custom": {
      "config": {
        "configs": [{
          "is_enabled": true,
          "name": "禁止醫療診斷",
          "prompt": "阻止代理提供醫療診斷或治療建議。",
          "execution_mode": "blocking",
          "model": "gemini-2.5-flash-lite",
          "history_message_count": 1,
          "trigger_action": {"type": "retry", "feedback": "原因：{{trigger_reason}}"}
        }]
      }
    }
  }
}

類型： focus (主題相關)、prompt_injection (防範提示注入)、content (內容類別過濾)、custom (LLM 評估的領域規則)。內容類別包括 harassment、profanity、sexual、violence、self_harm 和 medical_and_legal_information——閾值範圍 0.0–1.0 (預設 0.3)。自訂規則使用 execution_mode: "blocking"，並搭配 model、history_message_count 和 trigger_action (例如 retry 加上回饋)。自訂護欄會並行評估，並以容錯方式運作。

按垂直領域： 醫療/金融/法律 → 啟用 medical_and_legal_information；教育/青少年 → sexual/violence/self_harm/profanity；客服/銷售 → harassment/profanity。所有代理都受益於 focus + prompt_injection + 2-4 條自訂規則。

測試代理

透過 POST /v1/convai/agent-testing/create 建立三種測試類型，然後使用 PATCH 附加到代理。參考：代理測試。

類型	用途
`llm`	情境測試——代理是否對訊息做出適當回應？
`tool`	工具呼叫測試——正確的工具、正確的參數？
`simulation`	使用模擬使用者角色的多輪對話流程

// 工具呼叫測試 (全程使用 snake_case；chat_history 的 role 為 "user" 或 "agent")
{
  "name": "使用正確醫生和日期進行預約",
  "type": "tool",
  "chat_history": [
    {"role": "user", "message": "3 月 5 日下午 2 點，史密斯醫生", "time_in_call_secs": 10}
  ],
  "tool_call_parameters": {
    "referenced_tool": {"id": "show_booking_form", "type": "client"},
    "parameters": [
      {"path": "doctor_name", "eval": {"type": "llm", "description": "應提及史密斯醫生"}},
      {"path": "date", "eval": {"type": "regex", "pattern": "2025-03-05|3 月 5 日"}}
    ]
  }
}

評估策略：exact、regex、llm。提示評估標準可以使用二元評分或數值評分，搭配 scoring_mode: "numeric_uniform"、max_score 和 score_instructions；數值分數會正規化為整體對話成功百分比。透過 PATCH 附加：

curl -s -X PATCH "https://api.elevenlabs.io/v1/convai/agents/{agent_id}" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"platform_settings": {"testing": {"attached_tests": [{"test_id": "test_xxxx"}]}}}'

使用 POST /v1/convai/agents/{agent_id}/run-tests 執行選定的測試。請求主體需要 tests，並可接受 repeat_count 從 1 到 50 以進行重複執行。模擬測試最多可定義 30 個 success_conditions 提示；所有標準都會被評估並合併到最終結果中。
對於已完成的對話，使用 POST /v1/convai/conversations/{conversation_id}/analysis/evaluations/run 重新執行一個評估標準，請求主體包含 evaluation_id。

Widget 嵌入

<elevenlabs-convai agent-id="your-agent-id"></elevenlabs-convai>
<script src="https://unpkg.com/@elevenlabs/convai-widget-embed" async type="text/javascript"></script>

使用屬性自訂：avatar-image-url、action-text、start-call-text、end-call-text。

請參閱 Widget 嵌入參考了解所有選項。

外撥電話

透過 Twilio 或 Exotel 整合，使用您的代理撥打外撥電話：

以下範例使用 Twilio。請參閱參考文件了解 Exotel REST 用法。

Python

response = client.conversational_ai.twilio.outbound_call(
    agent_id="your-agent-id",
    agent_phone_number_id="your-phone-number-id",
    to_number="+1234567890",
    call_recording_enabled=True
)
print(f"通話已發起：{response.conversation_id}")

JavaScript

const response = await client.conversationalAi.twilio.outboundCall({
  agentId: "your-agent-id",
  agentPhoneNumberId: "your-phone-number-id",
  toNumber: "+1234567890",
  callRecordingEnabled: true,
});

cURL

curl -X POST "https://api.elevenlabs.io/v1/convai/twilio/outbound-call" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "agent_phone_number_id": "your-phone-number-id", "to_number": "+1234567890", "call_recording_enabled": true}'

請參閱外撥電話參考了解供應商特定端點、設定覆寫和動態變數。

管理代理

使用 CLI (推薦)

# 列出代理並檢查狀態
elevenlabs agents list
elevenlabs agents status

# 從平台匯入代理至本地設定
elevenlabs agents pull                      # 匯入所有代理
elevenlabs agents pull --agent <agent-id>   # 匯入特定代理

# 將本地變更推送至平台
elevenlabs agents push              # 上傳設定
elevenlabs agents push --dry-run    # 預覽變更

# 新增工具
elevenlabs tools add-webhook "天氣 API"
elevenlabs tools add-client "UI 工具"

專案結構

CLI 會建立用於管理代理的專案結構：

your_project/
├── agents.json       # 代理定義
├── tools.json        # 工具設定
├── tests.json        # 測試設定
├── agent_configs/    # 個別代理設定
├── tool_configs/     # 個別工具設定
└── test_configs/     # 個別測試設定

SDK 範例

# 列出
agents = client.conversational_ai.agents.list()

# 取得
agent = client.conversational_ai.agents.get(agent_id="your-agent-id")

# 更新 (部分更新 - 僅包含要變更的欄位)
client.conversational_ai.agents.update(agent_id="your-agent-id", name="新名稱")
client.conversational_ai.agents.update(agent_id="your-agent-id",
    conversation_config={
        "agent": {"prompt": {"prompt": "新指令", "llm": "claude-sonnet-4"}}
    })

# 刪除
client.conversational_ai.agents.delete(agent_id="your-agent-id")

請參閱代理設定了解所有設定選項和 SDK 範例。

錯誤處理

try:
    agent = client.conversational_ai.agents.create(...)
except Exception as e:
    print(f"API 錯誤：{e}")

常見錯誤：401 (金鑰無效)、404 (找不到)、422 (設定無效)、429 (速率限制)

參考資料

安裝指南 - SDK 設定與遷移
代理設定 - 所有設定選項與 CRUD 範例
用戶端工具 - Webhook、用戶端與系統工具
Widget 嵌入 - 網站整合
外撥電話 - 電話整合

您可能也喜歡

kubernetes-patterns

240Kbackend-api

Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments. Use when writing or reviewing Kubernetes manifests, or debugging probes, RBAC, autoscaling, or resource limits.

affaan-m

獲取

flox-environments

237Kbackend-api

使用宣告式 Nix 架構的環境管理工具 Flox，打造可重現且跨平台（macOS/Linux）的開發環境。適用於以下情境：建置任何語言的專案工具鏈、安裝系統級相依套件（編譯器、資料庫、openssl/BLAS 等原生函式庫）、為團隊固定精確的套件版本、執行本機服務（PostgreSQL、Redis、Kafka）、一行指令讓新開發者快速上手，或解決「在我的電腦上明明可以執行」的問題——包含需要專案專用工具且免 sudo 權限的 agent/vibe-coding 設定。當使用者提及 .flox/、manifest.toml、flox activate 或 FloxHub 時亦可使用。

affaan-m

獲取

cloud

107Kbackend-api

Browser Use Cloud 技術參考文件 — 這是用於瀏覽器自動化的雲端託管 API 與 SDK。當使用者需要關於 Cloud REST API (v2 或 v3)、browser-use-sdk (Python 或 TypeScript)、X-Browser-Use-API-Key 身份驗證、雲端 Session、瀏覽器設定檔 (profiles)、設定檔同步、CDP WebSocket 連線、隱形瀏覽器 (stealth browsers)、住宅代理 (residential proxies)、驗證碼處理 (CAPTCHA)、webhooks、工作區 (workspaces)、Skill 市集、liveUrl 即時串流、價格計費，或整合模式（聊天 UI、子 Agent、為現有 Agent 新增瀏覽器工具）等協助時，請使用此 Skill。當詢問有關 n8n/Make/Zapier 整合、於雲端基礎架構執行 Playwright/Puppeteer/Selenium，或 1Password 保險箱整合等問題時亦可觸發。請注意：切勿將此 Skill 用於開源版 Python 函式庫（Agent、Browser、Tools 設定）— 請改用開源版 Skill。

browser-use

獲取

繼續探索

瀏覽 backend-api 熱門 Skills 最近更新

agents

相關技能

ElevenLabs Agents 平台

使用 CLI 快速開始

Python

JavaScript

cURL

開始對話

暫時的 LiveKit WebSocket 固定版本

設定

系統提示結構

工具

內建系統工具

整合工具

公開 API Webhook 範例

工作流程

護欄

測試代理

Widget 嵌入

外撥電話

Python

JavaScript

cURL

管理代理

使用 CLI (推薦)

專案結構

SDK 範例

錯誤處理

參考資料

您可能也喜歡

kubernetes-patterns

flox-environments

cloud

繼續探索