Tổng quan API
API REST công khai của AgentFlow — địa chỉ gốc, ai gọi được thao tác nào, tài liệu tham chiếu nằm ở đâu và AgentFlow giữ tương thích ra sao.
API công khai là gì?
AgentFlow có một API REST để hệ thống khác làm việc với nó: khởi chạy quy trình và theo dõi lượt chạy, đọc và ghi hồ sơ, tải tệp đính kèm, đọc bảng điều khiển. Mọi yêu cầu đi tới một địa chỉ gốc có kèm phiên bản:
{origin}/api/v1{origin} là địa chỉ bản triển khai của bạn, ví dụ https://agentflow.example.com. Các ví dụ trong mục này viết nó là $ORIGIN.
Thao tác công khai và điểm cuối nội bộ
Thao tác công khai là đúng những thao tác có trong tài liệu API được công bố — không hơn. Ứng dụng web AgentFlow còn gọi nhiều điểm cuối khác; đó là điểm cuối nội bộ. Chúng không nằm trong cam kết tương thích, và từ chối thông tin xác thực của chủ thể dịch vụ cũng như token bearer của một người với 403 ENDPOINT_NOT_PUBLIC.
| Ai gọi | Xác thực bằng | Gọi được gì |
|---|---|---|
| Một tích hợp | Khóa của một chủ thể dịch vụ: Authorization: Bearer afk_… | Các thao tác công khai, trong giới hạn vai trò của chủ thể và quyền của khóa. |
| Một người, qua trợ lý AI bên ngoài | Token của chính người đó, chỉ tại điểm cuối MCP | Các công cụ MCP. |
| Ứng dụng web AgentFlow | Cookie phiên đăng nhập | Chỉ dành cho chính ứng dụng AgentFlow. |
Chi tiết từng cách nằm ở Xác thực.
Tài liệu tham chiếu nằm ở đâu
Tài liệu tham chiếu mô tả từng thao tác: đường dẫn, tham số, thân yêu cầu và các phản hồi. Nó được công bố ở hai nơi:
- Trong bộ hướng dẫn này, ở nhóm AgentFlow API trong mục API của thanh bên (
/guides/api/tham-chieu/), cho phiên bản sản phẩm mà bộ hướng dẫn đi kèm. - Trên từng bản triển khai, tại
{origin}/api/docs(trang tương tác, dựng bằng Scalar) và{origin}/api/openapi.json(tài liệu OpenAPI). Cả hai không cần đăng nhập. Một bản triển khai có thể tắt hai địa chỉ này.
Những dấu hiệu trong tài liệu
| Dấu hiệu | Nghĩa là gì |
|---|---|
x-person-only: true | Thao tác làm việc trên công việc của chính một người: My Work; nhận, trả lại, giao lại và giao việc; gửi một bước; thông báo. Chủ thể dịch vụ gọi sẽ nhận 403 USER_IDENTITY_REQUIRED. |
x-app-only: true | Thao tác trả lời một ứng dụng đã cài đặt về chính nó, như GET /app/objects. Một yêu cầu không đi qua ứng dụng đã cài đặt sẽ nhận 403 APP_CALLER_REQUIRED. Thành công của nó mang header AgentFlow-App-Revision. Xem Xác thực. |
x-stored-shape | Hình dạng được lưu nguyên văn, nên giữ đúng cách viết lúc được lưu. |
x-extensible-enum | Danh sách giá trị có thể được bổ sung về sau. Mã của bạn phải chịu được một giá trị chưa gặp bao giờ. |
x-idempotent: true | Thao tác nhận header Idempotency-Key: gửi lại với cùng khóa không làm việc hai lần. Xem Thử lại an toàn. |
Ngoài ra, một phản hồi có thể có thêm trường mới bất cứ lúc nào. Hãy bỏ qua những trường bạn không nhận ra, đừng coi chúng là lỗi.
Cam kết tương thích
- Trước khi v1 được công bố, thay đổi không tương thích vẫn có thể xảy ra. Mỗi thay đổi như vậy được khai báo trong hợp đồng API trước.
- Sau khi v1 được công bố, không có thay đổi không tương thích nào trong v1.
- Một thao tác chỉ bị gỡ ở phiên bản chính mới, sau ít nhất 6 tháng báo trước. Cách nhận biết một thao tác sắp bị gỡ nằm ở Ngừng hỗ trợ.
Đọc tiếp
- Xác thực — khóa, phạm vi quyền và
GET /caller. - Lỗi và Mã lỗi — đọc một lỗi và biết khi nào nên thử lại.
- Phân trang — duyệt danh sách bằng con trỏ.
- Thử lại an toàn — gửi lại một yêu cầu tạo hay khởi chạy mà không làm việc hai lần.
- Sự kiện và webhook — nhận sự kiện qua HTTP thay vì hỏi đi hỏi lại.
- Ví dụ theo từng mảng: quy trình và lượt chạy, hồ sơ, công việc, tệp đính kèm, bảng điều khiển, thông báo, danh bạ.