Quy trình làm việc
Nền tảng cốt lõiworkflow_definitions_readQuy trình làm việcĐọc các workflow tự động hóa của một cơ sở: danh sách workflow, toàn bộ đồ thị của một workflow, các loại node mà đồ thị có thể dùng và các mẫu được tuyển chọn. Hãy đọc node_types trước khi xây dựng hoặc chỉnh sửa đồ thị để mọi loại và tham số đều hợp lệ tại cơ sở.
Các hành động:
- list: Liệt kê workflow. Mỗi workflow kèm trạng thái có đang hoạt động hay không, phiên bản đã xuất bản, số lần chạy, lần chạy gần nhất và các node (id, name, type). Workflow cấp thương hiệu và tổ chức không được liệt kê.
- get: Lấy workflow. Toàn bộ đồ thị bản nháp (node, kết nối, ghi chú, cài đặt) và meta: active, publishedVersionId và, sau khi xuất bản, publishedWorkflow, tức đồ thị đang hoạt động. Chỉ workflow của cơ sở này. Cần workflowId.
- node_types: Các loại node. Các mục trong bảng chọn kèm type, label, category, outputs (nhánh) và inputSchema, tức các tham số cần điền. available là false, kèm lý do, khi cơ sở thiếu mô-đun mà node cần. Công cụ MCP xuất hiện dưới dạng node mcp.
. . - templates: Mẫu. Điểm khởi đầu cho các tác vụ tự động hóa phổ biến, kèm risk và riskNote (điều gì có thể sai nếu xuất bản thiếu cẩn trọng), loại node, mô-đun bắt buộc, tình trạng khả dụng tại cơ sở này và đồ thị xem trước. Chuyển một mẫu thành đồ thị bằng workflow_definitions_write instantiate_template.
Tham số
| Tên | Loại | Mô tả |
|---|---|---|
action* | "list" | "get" | "node_types" | "templates" | Việc cần làm; mỗi hành động được mô tả trong phần mô tả công cụ. |
limit | integer | Số mục mỗi trang (mặc định 25, tối đa 100) (list, node_types, templates) |
cursor | string | nextCursor từ trang trước (list, node_types, templates) |
facilityId | string | ID cơ sở. Không bắt buộc khi cơ sở đang kết nối chính là cơ sở bạn muốn chỉ đến. |
workflowId | string | ID workflow lấy từ workflow_definitions_read list (get) |
query | string | Từ cần tìm trong loại, nhãn, mô tả hoặc từ khóa tìm kiếm (node_types) |
category | string | Chỉ danh mục này: trigger, action, logic hoặc ai (node_types) |
types | array | Các loại chính xác cần mô tả, ví dụ các loại trong workflow bạn đang chỉnh sửa. Bao gồm cả các loại đã ngừng dùng mà bảng chọn không còn hiển thị; bỏ qua query và category. (node_types) |
workflow_definitions_writeQuy trình làm việcTạo, chỉnh sửa, xuất bản, dừng và xóa các workflow tự động hóa của một cơ sở. Quy trình soạn thảo: đọc node_types bằng workflow_definitions_read, xây dựng đồ thị (hoặc bắt đầu từ instantiate_template), tạo đồ thị dưới dạng bản nháp, chạy thử bằng workflow_runs_write test (mô phỏng), rồi xuất bản. Chỉnh sửa bản nháp không bao giờ thay đổi phiên bản đang hoạt động cho đến khi được xuất bản.
Các hành động:
- create: Tạo workflow. Lưu một bản nháp mới, chưa kích hoạt, từ một đồ thị đầy đủ có ít nhất một node; name mặc định là "Untitled workflow". Các vấn đề xác thực được trả về trong errors kèm chi tiết node. Cần nodes.
- update: Lưu bản nháp. Thay thế toàn bộ bản nháp: gửi mọi node và kết nối, không chỉ các thay đổi. Phiên bản đang hoạt động vẫn tiếp tục chạy cho đến khi bạn xuất bản. Các vấn đề xác thực được trả về trong errors kèm chi tiết node. Cần workflowId, nodes.
- patch_meta: Đổi tên. Chỉ thay đổi tên hoặc mô tả; đồ thị và phiên bản đang hoạt động giữ nguyên. changed là false khi cả hai đã khớp. Cần workflowId.
- duplicate: Nhân bản. Sao chép một workflow thành bản nháp mới có tên "
(copy)" với id node mới, không bao giờ được xuất bản hoặc kích hoạt. Bản gốc không bị ảnh hưởng. Cần workflowId. - delete: Xóa. Xóa vĩnh viễn workflow: bản nháp, các phiên bản đã xuất bản, lịch sử chạy và định tuyến trigger. set_active false dừng workflow nhưng vẫn giữ lại; discard_draft chỉ đặt lại các chỉnh sửa bản nháp. Cần workflowId. Yêu cầu xác nhận.
- discard_draft: Hủy bỏ chỉnh sửa bản nháp. Đặt lại bản nháp về phiên bản đã xuất bản gần nhất, loại bỏ các chỉnh sửa kể từ đó. Phiên bản đang hoạt động không bao giờ bị ảnh hưởng; cần có một phiên bản đã xuất bản. Cần workflowId. Yêu cầu xác nhận.
- publish: Xuất bản. Xác thực bản nháp, lưu thành phiên bản đang hoạt động và bật workflow, để các trigger kích hoạt và các hành động chạy thật. Các lần chạy đang diễn ra sẽ hoàn tất trên phiên bản cũ. Nếu các bước Delay đang chờ sẽ bị tính lại thời gian, kết quả có mã WAIT_RETARGET_CONFIRMATION_REQUIRED và impacts: hãy gọi lại với confirmWaitRetargets và các impacts đó. Cần workflowId. Yêu cầu xác nhận.
- set_active: Bật hoặc tắt. active true bật lại một workflow đã xuất bản. active false dừng workflow: trigger ngừng kích hoạt và các bước Delay đang chờ bị hủy nên sẽ không bao giờ hoàn tất. Không có gì bị xóa. Hỏi trước, trừ khi workflow đã ở trạng thái đó. Cần workflowId, active. Có thể yêu cầu xác nhận.
- instantiate_template: Đồ thị từ mẫu. Chuyển một mẫu thành đồ thị sẵn sàng cho create: { name, description, nodes, connections } với id node mới. Mẫu cố ý để trống người nhận, cửa và thời gian; hãy điền trước. Không lưu gì. Cần templateId.
- generate: Tạo đồ thị. Xây dựng đồ thị từ một câu lệnh bằng ngôn ngữ thông thường với AI của cơ sở và trả về { name, description, nodes, connections } chỉ dùng các loại node hợp lệ. Truyền workflow để chỉnh sửa một workflow; toàn bộ đồ thị đã chỉnh sửa sẽ được trả về. Không lưu gì, nhưng sử dụng tín dụng AI của cơ sở. Cần prompt. Yêu cầu xác nhận.
Tham số
| Tên | Loại | Mô tả |
|---|---|---|
action* | "create" | "update" | "patch_meta" | "duplicate" | "delete" | "discard_draft" | "publish" | "set_active" | "instantiate_template" | "generate" | Việc cần làm; mỗi hành động được mô tả trong phần mô tả công cụ. |
name | string | Tên workflow (create, update, patch_meta) |
description | string | Chức năng của workflow (create, update, patch_meta) |
nodes | array | Mọi node: { id, name, type, position, parameters }. Loại và tham số lấy từ workflow_definitions_read node_types. (create, update) |
connections | object | Các kết nối theo khóa là tên node nguồn; có thể để trống khi chỉ có một node (create, update) |
notes | array | Ghi chú trên canvas (create, update) |
settings | object | Cài đặt workflow (create, update) |
facilityId | string | ID cơ sở. Không bắt buộc khi cơ sở đang kết nối chính là cơ sở bạn muốn chỉ đến. |
workflowId | string | ID workflow lấy từ workflow_definitions_read list (update, patch_meta, duplicate, delete, discard_draft, publish, set_active) |
confirmWaitRetargets | boolean | Tính lại thời gian cho các bước Delay đang chờ được liệt kê trong impacts của kết quả trước (publish) |
confirmedWaitRetargets | array | impacts từ kết quả WAIT_RETARGET_CONFIRMATION_REQUIRED, gửi lại nguyên vẹn (publish) |
active | boolean | true để bật, false để dừng (set_active) |
templateId | string | ID mẫu lấy từ workflow_definitions_read templates (instantiate_template) |
prompt | string | Điều workflow cần làm (generate) |
workflow | object | Một workflow đầy đủ lấy từ workflow_definitions_read get, để chỉnh sửa thay vì bắt đầu từ đầu (generate) |
confirm | boolean | Chỉ đặt sau khi người dùng đã xác nhận bản xem trước do lần gọi đầu tiên trả về |
workflow_runs_readQuy trình làm việcLịch sử chạy của một workflow, mới nhất trước, và chi tiết từng bước của một lần chạy. Dùng để kiểm tra một tác vụ tự động hóa đã chạy hay chưa, theo dõi lần chạy bắt đầu bằng workflow_runs_write, hoặc tìm node nào bị lỗi và vì sao.
Các hành động:
- list: Liệt kê các lần chạy. Mỗi lần chạy kèm trạng thái, chế độ (live hoặc test), tác động phụ, trigger, người bắt đầu, thời gian, số bước, node đang chờ và lỗi nếu có. Cần workflowId.
- get: Lấy lần chạy. Trạng thái của lần chạy cùng mọi bước theo thứ tự, kèm đầu vào, đầu ra, ghi chú và lỗi của từng node. Các lần chạy là bất đồng bộ: lần chạy có Delay sẽ chờ đến khi phần tiếp theo đến hạn. Cần workflowId, executionId.
Tham số
| Tên | Loại | Mô tả |
|---|---|---|
action* | "list" | "get" | Việc cần làm; mỗi hành động được mô tả trong phần mô tả công cụ. |
workflowId | string | ID workflow lấy từ workflow_definitions_read list |
limit | integer | Số mục mỗi trang (mặc định 25, tối đa 100) (list) |
cursor | string | nextCursor từ trang trước (list) |
facilityId | string | ID cơ sở. Không bắt buộc khi cơ sở đang kết nối chính là cơ sở bạn muốn chỉ đến. |
executionId | string | ID lần chạy lấy từ workflow_runs_read list (get) |
workflow_runs_writeQuy trình làm việcBắt đầu, chạy thử, hủy và chạy lại các lần chạy workflow. Nên ưu tiên test, chạy bản nháp với tác động phụ được mô phỏng; run thực thi thật workflow đã xuất bản. Các lần chạy là bất đồng bộ: hãy theo dõi bằng workflow_runs_read get.
Các hành động:
- run: Chạy ngay. Chạy workflow đã xuất bản từ trigger thủ công (custom.manualTrigger), với tác động phụ thật. Trigger theo lịch, webhook và sự kiện tự kích hoạt. Trả về executionId và trạng thái đầu tiên của lần chạy. Cần workflowId. Yêu cầu xác nhận.
- test: Chạy thử bản nháp. Chạy bản nháp đã lưu mà không xuất bản, được ghi nhận là lần chạy thử. Tác động phụ được mô phỏng theo mặc định: không gửi hoặc chuyển đổi gì, và mỗi node báo cáo những gì lẽ ra nó đã làm. sideEffects live sẽ hỏi trước. Cần workflowId. Có thể yêu cầu xác nhận.
- cancel: Hủy lần chạy đang chờ. Hủy một lần chạy đang chờ ở bước Delay: các lượt chờ đang treo được đóng và các bước sau đó không bao giờ chạy. Không thể hủy lần chạy đã hoàn tất hoặc đang thực hiện dở một bước. Cần workflowId, executionId. Yêu cầu xác nhận.
- retry: Chạy lại. Chạy lại một lần chạy đã hoàn tất từ dữ liệu đầu vào trigger đã ghi, liên kết ngược qua retryOf. published (mặc định) chạy lại thật phiên bản đã dùng và hỏi trước; draft-test chạy bản nháp hiện tại ở chế độ mô phỏng, lựa chọn phù hợp khi đang khắc phục lỗi. Cần workflowId, executionId. Có thể yêu cầu xác nhận.
Tham số
| Tên | Loại | Mô tả |
|---|---|---|
action* | "run" | "test" | "cancel" | "retry" | Việc cần làm; mỗi hành động được mô tả trong phần mô tả công cụ. |
workflowId | string | ID workflow lấy từ workflow_definitions_read list |
nodeId | string | ID node trigger để bắt đầu; bỏ qua để dùng trigger thủ công (run, test) |
payload | object | Đầu vào cho các node sau trigger, ví dụ { "visitorName": "Ada" } (run, test) |
facilityId | string | ID cơ sở. Không bắt buộc khi cơ sở đang kết nối chính là cơ sở bạn muốn chỉ đến. |
sideEffects | "simulate" | "live" | Các hành động của node có thực sự diễn ra hay không (test) |
executionId | string | ID lần chạy lấy từ workflow_runs_read list (cancel, retry) |
mode | "published" | "draft-test" | Đối tượng dùng để chạy lại (retry) |
confirm | boolean | Chỉ đặt sau khi người dùng đã xác nhận bản xem trước do lần gọi đầu tiên trả về |