Tạo quy trình có cấu trúc cho ElevenAgents

Quy trình có cấu trúc là quy trình thực hiện một chuỗi các bước cố định. Free-form Procedures (Quy trình dạng tự do) là hướng dẫn bằng ngôn ngữ tự nhiên mà agent sẽ diễn giải và điều chỉnh tùy theo tình huống. Quy trình có cấu trúc là một danh sách các bước được phân loại và sắp xếp theo thứ tự; agent sẽ thực hiện lần lượt các bước này mỗi khi quy trình được áp dụng.

Hãy sử dụng quy trình có cấu trúc khi các bước cụ thể cần được thực hiện theo cùng một cách trong mọi cuộc gọi: Chẳng hạn như xác minh danh tính người gọi, chuyển tiếp yêu cầu hỗ trợ lên cấp cao hơn, hoặc xử lý thanh toán. Bạn có thể soạn thảo quy trình này dưới dạng một danh sách ngắn gọn gồm các bước được mô tả bằng ngôn ngữ thông thường.

Giống như mọi quy trình khác, quy trình có cấu trúc có một "điều kiện kích hoạt" (trigger) mô tả thời điểm áp dụng quy trình đó. Khi một cuộc hội thoại khớp với điều kiện kích hoạt, agent sẽ thực hiện lần lượt các bước của quy trình, sau đó quay lại xử lý phần còn lại của cuộc hội thoại.

Khi nào nên sử dụng quy trình có cấu trúc?

Hãy sử dụng quy trình có cấu trúc khi các bước cụ thể cần được thực hiện theo cùng một cách mỗi lần, nhưng bạn vẫn muốn soạn thảo nhanh chóng bằng các bước đơn giản, dễ hiểu. Quy trình có cấu trúc dễ viết hơn so với workflow nhưng lại có khả năng diễn đạt hạn chế hơn.

Một quy trình có cấu trúc bao gồm những gì?

Một quy trình có cấu trúc bao gồm 3 phần: Tên, điều kiện kích hoạt và danh sách các bước được sắp xếp theo thứ tự.

Tên

Một nhãn ngắn gọn dùng để nhận diện quy trình trên dashboard. Tên này không bao giờ được gửi đến mô hình ngôn ngữ lớn (LLM), do đó nó không ảnh hưởng đến hành vi của agent.

Điều kiện kích hoạt (Trigger)

Một mô tả bằng ngôn ngữ thông thường về thời điểm agent nên thực hiện quy trình này, ví dụ: "Khi người dùng yêu cầu hoàn tiền cho đơn hàng". Agent sẽ so sánh ý định của người dùng với điều kiện kích hoạt của từng quy trình và thực hiện quy trình phù hợp nhất; vì vậy, các điều kiện kích hoạt cần phải cụ thể và khác biệt rõ ràng. Agent chỉ nhìn thấy văn bản mô tả điều kiện kích hoạt chứ không bao giờ thấy tên hay ID của quy trình. Cơ chế hoạt động của điều kiện kích hoạt này cũng giống như đối với bất kỳ quy trình nào khác.

Hãy để trống phần điều kiện kích hoạt nếu bạn muốn biến quy trình này thành một quy trình con (sub-procedure) – loại quy trình chỉ chạy khi được một quy trình khác gọi đến.

Các bước thực hiện

Phần thân của quy trình là một danh sách các bước được phân loại và sắp xếp theo thứ tự. Có nhiều loại bước khác nhau, và bạn có thể kết hợp chúng để mô tả nhiệm vụ cần thực hiện.

Không phải bước nào cũng có thể xuất hiện ở mọi vị trí. Bên trong nhánh If, bạn có thể sử dụng bất kỳ bước nào ngoại trừ một bước If khác hoặc bước Retry. Bên trong trình xử lý lỗi của bước Tool, bạn có thể sử dụng bất kỳ bước nào ngoại trừ bước If hoặc một bước Tool khác.

Tham chiếu bước API

Nội dung quy trình có cấu trúc là một tài liệu được mã hóa JSON chứa mảng các bước. Mỗi bước là một đối tượng được xác định bởi loại (type) của nó. Trigger (trình kích hoạt) là một trường cấp cao nhất riêng biệt của quy trình, không nằm trong phần nội dung. Payload API và SDK sử dụng type: "deterministic" cho chính quy trình đó.

Ask 

Bước Ask yêu cầu agent hỏi thông tin và chờ cho đến khi người dùng cung cấp phản hồi phù hợp.

• Loại API: ask
• instruction: Bắt buộc, chuỗi ký tự không rỗng.

{
  "type": "ask",
  "instruction": "Ask the user for their order ID."
}

Tell 

Bước Tell yêu cầu agent tạo ra một thông điệp bằng ngôn ngữ của chính nó. Nó không chờ phản hồi từ người dùng trước khi tiếp tục.

• Loại API: tell
• instruction: Bắt buộc, chuỗi ký tự không rỗng.

{
  "type": "tell",
  "instruction": "Explain that the refund normally takes five to ten business days."
}

Say

Bước Say phát nội dung văn bản được cung cấp chính xác như đã viết, sau đó tiếp tục thực hiện bước kế tiếp. Cung cấp message_translations để chỉ định thông điệp chính xác cho từng ngôn ngữ bổ sung mà agent hỗ trợ, sử dụng mã ngôn ngữ làm key.

• Loại API: say
• message: Bắt buộc, chuỗi ký tự không rỗng.
• message_translations: Đối tượng tùy chọn ánh xạ mã ngôn ngữ tới { "value": "..." }.

{
  "type": "say",
  "message": "Your refund has been submitted.",
  "message_translations": {
    "es": { "value": "Su reembolso ha sido enviado." }
  }
}

If, else if và else

Bước If chứa một hoặc nhiều nhánh điều kiện được sắp xếp theo thứ tự. Nhánh phù hợp đầu tiên sẽ được thực thi. Mảng dự phòng (fallback) tùy chọn đóng vai trò là nhánh Else.

• Loại API: branch 
• branches: Danh sách bắt buộc (không được để trống) gồm các nhánh điều kiện.
• fallback: Danh sách tùy chọn gồm các bước xử lý mặc định (Else).
• Mỗi nhánh yêu cầu phải có một condition và một danh sách steps (không được để trống).

{
  "type": "branch",
  "branches": [
    {
      "condition": {
        "type": "llm",
        "condition": "The user is on an annual plan."
      },
      "steps": [
        {
          "type": "say",
          "message": "Your annual plan is eligible for a prorated refund."
        }
      ]
    }
  ],
  "fallback": [
    {
      "type": "tell",
      "instruction": "Explain that the account's plan could not be determined."
    }
  ]
}

Cơ chế hoạt động của nó tương tự như cấu trúc if/else-if/else:

1. Các điều kiện được đánh giá theo thứ tự.
2. Nhánh đầu tiên thỏa mãn điều kiện sẽ được thực thi.
3. Nếu không có điều kiện nào thỏa mãn, phần fallback sẽ được thực thi.
4. Sau khi một nhánh hoàn tất, quy trình sẽ quay trở lại luồng xử lý chính.

Ví dụ trên sử dụng điều kiện dạng văn bản, được mô hình đánh giá bằng ngôn ngữ tự nhiên. Các điều kiện cũng có thể là biểu thức dựa trên các biến động:

{
  "type": "expression",
  "expression": {
    "type": "eq_operator",
    "left": {
      "type": "dynamic_variable",
      "name": "plan_tier"
    },
    "right": {
      "type": "string_literal",
      "value": "annual"
    }
  }
}

Điều kiện biểu thức (expression condition) kiểm tra các biến động (dynamic variables) - những biến được điền giá trị từ kết quả của công cụ hoặc được thiết lập khi cuộc hội thoại bắt đầu. Nó không thể đọc nội dung phản hồi gần nhất của người dùng. Để phân nhánh dựa trên những gì người dùng đã nói, hãy sử dụng điều kiện văn bản (text condition).

Tất cả các nhánh trong cùng một bước "If" phải sử dụng cùng một loại điều kiện: hoặc là `llm` hoặc là `expression`.

Tool

Bước Tool thực hiện gọi một công cụ cụ thể.

• Loại API: tool_call
• tool_id: Bắt buộc; ID công cụ (không được để trống). Công cụ này phải được gắn với agent.
• tool_name: Bắt buộc; tên công cụ, phải khớp với tên công cụ thực tế.
• instruction: Tùy chọn; hướng dẫn mô tả cách gọi công cụ.
• schema_overrides: Tùy chọn; các giá trị cố định cho tham số của công cụ.
• on_failure: Tùy chọn; trình xử lý khi xảy ra lỗi.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "instruction": "Look up the order using the order ID provided by the user."
}

Giá trị tham số cố định

Sử dụng schema_overrides khi một tham số luôn cần nhận một giá trị cụ thể. Mô hình sẽ không nhìn thấy hoặc tự chọn tham số đã được ghi đè (override) này. Các key là đường dẫn tham số trong schema của công cụ; mỗi giá trị sẽ chỉ định một nguồn dữ liệu:

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "update_ticket",
  "schema_overrides": {
    "request_body.status": { "source": "constant", "constant_value": "pending" },
    "request_body.ticket_id": { "source": "dynamic_variable", "dynamic_variable": "ticket_id" }
  }
}

Xử lý lỗi

Nếu không có on_failure, việc gọi công cụ bị lỗi sẽ chấm dứt cuộc hội thoại. Hãy thêm on_failure để thực hiện các bước khắc phục thay vì dừng lại.

• fallback: Bắt buộc; danh sách các bước (không được để trống) sẽ được thực thi khi công cụ gặp lỗi.
• branches: Dành riêng cho việc xử lý lỗi có điều kiện. Hãy để trống mục này.

{
  "type": "tool_call",
  "tool_id": "tool_abc123",
  "tool_name": "lookup_order",
  "on_failure": {
    "branches": [],
    "fallback": [
      {
        "type": "tell",
        "instruction": "Explain that the order could not be retrieved and offer to connect the user with support."
      }
    ]
  }
}

Trình xử lý lỗi (failure handler) có thể bao gồm các bước Ask, Tell, Say, Sub-procedure, System tool và Retry. Nó không được chứa các bước Tool hoặc If. Sau khi trình xử lý chạy xong, quy trình sẽ tiếp tục với bước nằm ngay sau bước Tool ban đầu.

Retry 

Bước Retry thực hiện lại trình xử lý lỗi chứa nó, bao gồm cả việc gọi công cụ (tool call). Mỗi lần thử sẽ gọi lại công cụ; nếu tiếp tục thất bại, toàn bộ các bước trong trình xử lý sẽ được chạy lại. Khi đã dùng hết số lần thử cho phép, cuộc hội thoại sẽ kết thúc.

• Loại API: retry
• max_retries: Số nguyên tùy chọn từ 1 đến 3. Mặc định là 1.
• Giá trị này tính số lần thử sau lần gọi công cụ ban đầu.
• Retry chỉ hợp lệ khi nằm trong on_failure.
• Retry phải là bước cuối cùng trong trình xử lý lỗi chứa nó vì các bước phía sau sẽ không thể thực thi được.

{
  "type": "retry",
  "max_retries": 2
}

Sub-procedure

Bước Sub-procedure thực thi một quy trình có cấu trúc khác. Khi các bước của quy trình đó hoàn tất, việc thực thi sẽ quay lại bước nằm ngay sau bước Sub-procedure.

• Loại API: sub_procedure
• procedure_id: Bắt buộc; ID quy trình không được để trống.
• Quy trình đích phải tồn tại trên cùng một agent.
• Quy trình đích phải là một quy trình có cấu trúc.
• Một quy trình không được tự gọi chính nó.

{
  "type": "sub_procedure",
  "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
}

System tool

Bước System tool thực hiện một hành động hệ thống có sẵn.

• Loại API: system_tool
• system_tool_name: Tên công cụ hệ thống (bắt buộc).
• Hiện tại, chỉ hỗ trợ end_call. Các công cụ hệ thống khác có thể được bổ sung sau này.
• Vì end_call là hành động kết thúc, nó phải là bước cuối cùng trong chuỗi (sequence), nhánh (arm) hoặc trình xử lý lỗi chứa nó.

{
  "type": "system_tool",
  "system_tool_name": "end_call"
}

Các quy tắc xác thực

Việc xuất bản hoặc lưu bản nháp của agent sẽ dẫn đến việc từ chối bất kỳ quy trình có cấu trúc nào vi phạm các quy tắc sau. Thông báo lỗi sẽ chỉ rõ bước vi phạm thông qua đường dẫn của nó.

• Không được đặt hai bước "If" nối tiếp nhau.
• Không được lồng các bước "If" vào nhau.
• Bước "If" có điều kiện dạng biểu thức không được nằm ngay sau bước "Ask".
• Tất cả các điều kiện trong một bước "If" phải cùng loại: hoặc là "llm" hoặc là "expression".
• Thao tác retry chỉ được xuất hiện bên trong khối on_failure và phải là bước cuối cùng của khối đó.
• end_call phải là bước cuối cùng trong danh sách chứa nó.
• Cơ chế dự phòng (fallback) của trình xử lý lỗi phải bao gồm ít nhất một bước.
• Quy trình con (Sub-procedure) phải trỏ đến một quy trình có cấu trúc hiện có trên cùng một agent, chứ không phải trỏ vào chính nó.
• tool_id phải tương ứng với một công cụ trên agent, tool_name phải khớp, và schema_overrides phải phù hợp với schema của công cụ đó.
• Danh sách các bước, mọi chỉ dẫn và mọi thông điệp đều không được để trống.

Ví dụ đầy đủ về API

Ví dụ này xử lý việc hủy đơn hàng dựa trên trạng thái vận chuyển. Nó cố định một tham số công cụ, xử lý tình huống gọi công cụ thất bại, kích hoạt một quy trình có cấu trúc khác, sau đó kết thúc cuộc gọi.

{
  "steps": [
    {
      "type": "ask",
      "instruction": "Ask the user for their order ID."
    },
    {
      "type": "branch",
      "branches": [
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has already shipped."
          },
          "steps": [
            {
              "type": "tell",
              "instruction": "Explain that shipped orders must be returned before they can be refunded."
            }
          ]
        },
        {
          "condition": {
            "type": "llm",
            "condition": "The user says the order has not shipped."
          },
          "steps": [
            {
              "type": "tool_call",
              "tool_id": "tool_abc123",
              "tool_name": "cancel_order",
              "instruction": "Cancel the order using the order ID provided by the user.",
              "schema_overrides": {
                "request_body.notify_customer": { "source": "constant", "constant_value": true }
              },
              "on_failure": {
                "branches": [],
                "fallback": [
                  {
                    "type": "tell",
                    "instruction": "Apologize that the cancellation did not go through and say you will try once more."
                  },
                  {
                    "type": "retry",
                    "max_retries": 1
                  }
                ]
              }
            }
          ]
        }
      ],
      "fallback": [
        {
          "type": "ask",
          "instruction": "Ask whether the order has already shipped."
        }
      ]
    },
    {
      "type": "sub_procedure",
      "procedure_id": "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3"
    },
    {
      "type": "say",
      "message": "Thank you for contacting us. Goodbye.",
      "message_translations": {
        "es": { "value": "Gracias por contactarnos. Adiós." }
      }
    },
    {
      "type": "system_tool",
      "system_tool_name": "end_call"
    }
  ]
}

Cách thức vận hành của một quy trình có cấu trúc

Quá trình chuyển đổi các bước của một quy trình có cấu trúc thành dạng mà agent có thể thực thi được gọi là biên dịch. Nền tảng sẽ tự động biên dịch mọi quy trình có cấu trúc khi bạn xuất bản (publish); bạn không cần phải tự thực hiện việc biên dịch. Kết quả sau khi biên dịch hiện hiển thị dưới dạng các node chỉ đọc (read-only) trong tab Workflow.

Khi yêu cầu của người dùng khớp với điều kiện kích hoạt (trigger) của một quy trình, agent sẽ bắt đầu thực hiện quy trình đó và chạy các bước theo thứ tự. Trong quá trình thực hiện quy trình có cấu trúc, agent tập trung xử lý từng bước một cách độc lập. Khi hoàn tất quy trình, agent sẽ quay trở lại phần còn lại của cuộc hội thoại.

Các quy tắc dưới đây mô tả cách thức hoạt động của các bước trong runtime.

Chỉ bước "Ask" mới chờ phản hồi từ người dùng

Mọi bước khác ngoài "Ask" đều được thực thi ngay lập tức, và quyền điều khiển sẽ chuyển sang bước tiếp theo ngay trong cùng một lượt hội thoại (turn). Bước "Tell" hoặc "Say" sẽ gửi thông điệp và tiếp tục thực hiện bước kế tiếp. Không có bước nào khác ngoài "Ask" có khả năng tạm dừng cuộc hội thoại, và cũng không có bước nào tự động kết thúc lượt hội thoại hiện tại. Nếu cần thông tin đầu vào từ người dùng, hãy sử dụng bước "Ask". Nếu muốn kết thúc cuộc hội thoại, hãy sử dụng công cụ hệ thống end_call.

Hoàn tất quy trình không đồng nghĩa với việc kết thúc lượt hội thoại

Khi bước cuối cùng hoàn tất, quy trình kết thúc và agent quay lại phần còn lại của cuộc hội thoại trong khi lượt hội thoại vẫn đang mở, cho phép agent tiếp tục phản hồi thêm. Khi một quy trình con (sub-procedure) hoàn tất, quyền điều khiển sẽ quay lại bước tiếp theo của quy trình đã gọi nó.

Các bước Tool chỉ phân biệt giữa thành công và thất bại

Bước "Tool" không thể phân nhánh dựa trên mã trạng thái (status code) hoặc nội dung phản hồi (response body). Nếu công cụ thực thi thành công, quy trình sẽ tiếp tục. Nếu thất bại và bước đó không có trình xử lý lỗi (failure handler), cuộc hội thoại sẽ kết thúc. Nếu có trình xử lý lỗi, các bước trong trình xử lý sẽ được thực thi và quy trình tiếp tục sang bước kế tiếp. Hành động "Retry" (thử lại) bên trong trình xử lý sẽ chạy lại công cụ; nếu tiếp tục thất bại, toàn bộ các bước trong trình xử lý sẽ chạy lại cho đến khi công cụ thành công hoặc hết số lần thử cho phép. Nếu đã dùng hết số lần thử, cuộc hội thoại sẽ kết thúc.

Xử lý khi không có điều kiện nào khớp (trường hợp rơi vào nhánh mặc định)

Các điều kiện được đánh giá theo thứ tự và điều kiện khớp đầu tiên sẽ được thực thi. Nhánh "Else" sẽ chạy khi không có điều kiện nào khớp. Nếu không có nhánh "Else" và không có điều kiện nào khớp, quy trình sẽ tiếp tục với bước nằm ngay sau khối "If". Trường hợp không được xử lý không phải là lỗi.

Nếu các nhánh không chuyển tiếp trạng thái

Mọi kết quả bên trong một nhánh của câu lệnh If sẽ không được ghi nhớ ở các bước tiếp theo. Nếu thông tin thu được trong một nhánh cần thiết cho các bước sau, hãy lưu trữ nó một cách tường minh bằng cách sử dụng lệnh gọi công cụ (tool call) hoặc biến động (dynamic variable).

Các bước Ask, Tell và Say không sử dụng công cụ

Chỉ các bước Tool mới có thể gọi công cụ. Không cần thiết phải yêu cầu bước Ask, Tell hay Say không được gọi công cụ, vì bản thân chúng không thể thực hiện việc đó.

Quản lý quy trình có cấu trúc

Xây dựng qua dashboard

Mở agent của bạn trong dashboard, sau đó chọn mục Procedures. Sử dụng nút + để tạo một quy trình có cấu trúc. Thêm trình kích hoạt (trigger), chọn loại cho từng bước và xuất bản (publish) các thay đổi của agent.

Dashboard sẽ kiểm tra tính hợp lệ của các quy trình có cấu trúc ngay trong quá trình bạn chỉnh sửa. Nếu một quy trình vi phạm quy tắc kiểm tra, nút Publish sẽ hiển thị trạng thái lỗi, tab Procedures sẽ hiện biểu tượng báo lỗi và tính năng xem trước (preview) sẽ không thể khởi chạy cho đến khi quy trình được sửa lỗi. Hãy nhấp vào chỉ báo lỗi để xem quy trình và bước nào đang gặp vấn đề.

Quản lý qua giao diện dòng lệnh (CLI)

ElevenLabs CLI tạo và xuất bản các quy trình có cấu trúc bằng cách sử dụng cùng các lệnh như đối với quy trình dạng tự do. Hãy đặt type là deterministic và truyền các bước dưới dạng chuỗi đã mã hóa JSON trong phần nội dung (content).

CONTENT=$(jq -n '{
  trigger: "When the user asks to refund an order",
  steps: [{ type: "ask", instruction: "Ask for the order ID." }]
}')

elevenlabs agents procedures create \
  --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \
  --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \
  --json "$(jq -n --arg content "$CONTENT" '{
    name: "Refund request",
    type: "deterministic",
    trigger: "When the user asks to refund an order",
    content: $content
  }')"

elevenlabs agents update \
  --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \
  --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \
  --json '{"version_description": "Publish refund procedure"}'

Quá trình xuất bản sẽ kiểm tra tính hợp lệ của mọi quy trình có cấu trúc trên nhánh đó. Nếu có quy trình nào không hợp lệ, lệnh sẽ kết thúc với exit code khác không và hiển thị các lỗi kèm theo ID quy trình tương ứng. Hãy chỉnh sửa bản nháp quy trình và thực hiện xuất bản lại.

Quản lý qua API

Các payload API và SDK sử dụng type: "deterministic" cho các quy trình có cấu trúc. Nội dung của chúng là một tài liệu được mã hóa dưới dạng JSON.

Điều kiện tiên quyết

• ElevenLabs API key được lưu trong biến môi trường ELEVENLABS_API_KEY.
• Các giá trị agent_id và branch_id đích. 
• Gói Python elevenlabs hoặc gói JavaScript @elevenlabs/elevenlabs-js phiên bản 2.60.0 trở lên.

Các chỉnh sửa qua API chỉ hiển thị với người dùng của bạn trên nhánh đã chọn cho đến khi bạn xuất bản phiên bản agent mới.

1. Tạo hoặc cập nhật bản nháp

Tạo một quy trình có cấu trúc bằng cách sử dụng POST /procedures và đặt thuộc tính type thành deterministic. Cập nhật quy trình hiện có bằng PATCH /procedures/{procedure_id}/draft, như minh họa bên dưới.

Thiết lập trigger dưới dạng một trường cấp cao nhất. Mã hóa tài liệu các bước thành JSON trong trường content thay vì gửi một đối tượng lồng nhau.

Python

import json
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.procedures.drafts.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
    procedure_id="agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3",
    name="Refund request",
    type="deterministic",
    trigger="When the user asks to refund an order",
    content=json.dumps(
        {
            "steps": [{"type": "ask", "instruction": "Ask for the order ID."}],
        }
    ),
)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.procedures.drafts.update(
  "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
  "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3",
  {
    name: "Refund request",
    type: "deterministic",
    trigger: "When the user asks to refund an order",
    content: JSON.stringify({
      steps: [{ type: "ask", instruction: "Ask for the order ID." }],
    }),
  }
);

Bash

curl -X PATCH "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures/agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3/draft" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund request",
    "type": "deterministic",
    "trigger": "When the user asks to refund an order",
    "content": "{\"steps\":[{\"type\":\"ask\",\"instruction\":\"Ask for the order ID.\"}]}"
  }'

Việc lưu bản nháp quy trình không thực hiện kiểm tra tính hợp lệ (validate) các bước của quy trình đó. Quá trình kiểm tra sẽ diễn ra khi bạn xuất bản hoặc khi bạn lưu bản nháp agent bằng POST /v1/convai/agents/{agent_id}/drafts.

2. Xuất bản các thay đổi

Xuất bản bằng cách sử dụng chức năng Update agent. Thao tác xuất bản (publish) sẽ kiểm tra tính hợp lệ của mọi quy trình có cấu trúc trên nhánh, thực hiện biên dịch chúng và lưu trữ kết quả cùng với phiên bản mới. Yêu cầu này không cần trường workflow; quá trình biên dịch diễn ra như một phần của thao tác xuất bản. 

Python

from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
)

TypeScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
});

Bash

curl -X PATCH \
  "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Nếu quy trình có cấu trúc không hợp lệ, thao tác xuất bản sẽ trả về mã lỗi 400 và không có dữ liệu nào được ghi lại:

{
  "detail": {
    "status": "procedure_validation_failed",
    "message": "Structured procedures failed validation.",
    "data": {
      "errors": {
        "agtprc_6qbpwdq8n01bxhk44bgjy6f10ck3": [
          {
            "path": "steps[0].ask.instruction",
            "message": "Step 1: Ask step requires an instruction"
          }
        ]
      }
    }
  }
}

Trường errors sử dụng ID của quy trình làm key. Mỗi mục trong đó chỉ rõ trường và bước gặp lỗi. Hãy chỉnh sửa bản nháp quy trình và thực hiện xuất bản lại.

Endpoint /procedures/compile từ các phiên bản trước của API này vẫn hoạt động, nhưng đây là tính năng cũ (legacy) và sẽ sớm bị loại bỏ. Thao tác xuất bản đã bao gồm việc biên dịch; do đó, không nên gọi endpoint biên dịch trong code mới.