Chuyển đến nội dung chính
CloudThinker không có REST API tổng quát để đọc tài nguyên hay đề xuất; nếu bạn cần, hãy email support@cloudthinker.io kèm trường hợp sử dụng. CloudThinker hỗ trợ năm cách để mã bên ngoài truy cập workspace của bạn, mỗi cách cho một mục đích khác nhau, liệt kê bên dưới.

Chọn cách tích hợp

Webhook chỉ nhận vào. CloudThinker không POST sự kiện tới endpoint của bạn. Để gửi kết quả ra ngoài, hãy dùng thông báo, Slack hoặc Microsoft Teams.

A2A API cho bên gọi ngoài

A2A API cho phép một hệ thống bên ngoài CloudThinker hỏi một agent qua giao thức Agent2Agent (A2A). Bên gọi xác thực bằng OAuth 2.0 client credentials grant, nên không cần ai đăng nhập. Ví dụ điển hình: đội platform muốn ServiceNow hỏi CloudThinker về một sự cố. Bạn đăng ký ServiceNow làm bên gọi ngoài, chọn agent trả lời, rồi ServiceNow gửi câu hỏi tới agent URL.

Trước khi bắt đầu

  • Tổ chức đang dùng gói Scale hoặc Enterprise. Xem Bảng giá.
  • Bạn có vai trò workspace Developer hoặc Admin, là vai trò được sửa agent. Xem Người dùng workspace.
  • Bạn biết agent nào sẽ trả lời: chính CloudThinker hoặc một Custom Agent của bạn. Mỗi bên gọi ngoài gắn với một agent trong một workspace.

Đăng ký bên gọi ngoài

1

Mở cài đặt chia sẻ

Vào Agents → Sharing → Outside callers.
2

Thêm bên gọi

Nhấn Add an outside caller. Nhập Name mà đội bạn dễ nhận ra (ví dụ “ServiceNow”), chọn Agent that answers, và có thể đặt Monthly credit limit. Để trống nếu không giới hạn. Nhấn Create client.
3

Sao chép thông tin xác thực

CloudThinker hiển thị bốn giá trị: Client ID, Client secret, Token URL và Agent URL. Sao chép secret ngay. Secret chỉ hiển thị một lần, và CloudThinker chỉ lưu bản hash của secret.Hai URL có dạng như sau:
Mọi bên gọi dùng chung một agent URL. Token quyết định workspace và agent nào trả lời.
4

Lưu vào hệ thống gọi

Đặt client ID và secret vào kho secret của hệ thống bên ngoài, cùng với token URL và agent URL.

Lấy token và đặt câu hỏi

Luồng gồm ba lệnh gọi:
1

Yêu cầu token

POST tới token URL bằng HTTP Basic auth (client ID làm user, secret làm password) với grant client_credentials.
Phản hồi thành công:
Token có hiệu lực 1 giờ. Khi hết hạn, hãy yêu cầu token mới. Lỗi dùng định dạng OAuth 2.0 (RFC 6749), ví dụ {"error": "invalid_client", "error_description": "..."}.
2

Gửi câu hỏi

POST một request JSON-RPC 2.0 SendMessage tới agent URL, kèm token dạng Bearer. Mỗi câu hỏi cần một messageId duy nhất. Gửi lại cùng messageId sẽ trả về task đầu tiên thay vì bắt đầu lượt chạy mới, nên thử lại luôn an toàn.
CloudThinker trả về task ngay lập tức. Hãy giữ lại id của task:
3

Poll để lấy câu trả lời

Gọi GetTask với task ID cho tới khi trạng thái là trạng thái cuối. CloudThinker không bao giờ đẩy kết quả tới bên gọi ngoài, nên poll là cách duy nhất để nhận kết quả. Một lượt chạy agent mất vài phút, vì vậy hãy poll mỗi 10 đến 30 giây.
Dừng poll khi status.state là TASK_STATE_COMPLETED, TASK_STATE_FAILED, TASK_STATE_REJECTED hoặc TASK_STATE_CANCELED. Với TASK_STATE_COMPLETED, câu trả lời là text trong result.artifacts[].parts[]. Xem Các trường của task để biết mọi trạng thái.

Kết quả mong đợi

Xoay vòng, tạm dừng hoặc thu hồi

Trong Agents → Sharing → Outside callers, dòng của mỗi bên gọi có các điều khiển sau:
Thu hồi bên gọi là vĩnh viễn. Để chặn lưu lượng mà không mất bên gọi, hãy tạm dừng thay vì thu hồi.

Tham chiếu A2A

Mọi thứ bên gọi ngoài có thể gửi và nhận về. Mọi lệnh gọi đều tới https://app.cloudthinker.io.

Endpoint

Bạn có thể gửi header A2A-Version (không bắt buộc) trong các lệnh gọi tới /api/a2a. CloudThinker dùng A2A 1.0 và cũng chấp nhận 1 và 1.0.0. Mọi giá trị khác đều thất bại với lỗi JSON-RPC -32009.

Yêu cầu token

POST /api/a2a/oauth/token với Content-Type: application/x-www-form-urlencoded. Client ID bắt đầu bằng cta_. Khi thành công, phản hồi trả về 200 với Cache-Control: no-store:
Lỗi trả về body OAuth 2.0, {"error": "...", "error_description": "..."}: Bên gọi đang tạm dừng vẫn lấy được token. Các lệnh SendMessage của bên gọi đó thất bại với client_inactive cho tới khi bạn bật lại.

Envelope JSON-RPC

Mọi lệnh gọi tới POST /api/a2a là một request JSON-RPC 2.0:
id có thể là chuỗi, số hoặc null, và được trả về nguyên vẹn. Phản hồi thành công có result; phản hồi lỗi có error (xem Lỗi A2A).

SendMessage

Bắt đầu một lượt chạy agent, hoặc trả về task hiện có nếu messageId đã được gửi trước đó. Câu hỏi giới hạn 8.000 ký tự; phần dài hơn bị cắt. Câu hỏi không có text, hoặc chứa secret như access key, bị từ chối với blocked_by_guardrail. result bọc task trong trường task:

GetTask

result chính là task, không có lớp bọc task. Khi trạng thái là TASK_STATE_COMPLETED, câu trả lời nằm trong một artifact:
CloudThinker che secret khỏi câu trả lời trước khi trả về. Khi lượt chạy thất bại, bị từ chối hoặc bị hủy, status.message.parts[].text cho biết lý do, và metadata.failureKind chứa một mã ngắn.

CancelTask

Dừng một task chưa hoàn tất. CancelTask nhận cùng params như GetTask và trả về task theo cùng cấu trúc. Hủy task đã ở trạng thái cuối sẽ thất bại với task_not_cancelable.

Các trường của task

Lỗi A2A

Lệnh gọi JSON-RPC thất bại trả về một đối tượng error. Lý do nằm trong error.data.reason:
Bản thân envelope có thể lỗi trước khi CloudThinker đọc tới phương thức:

Giới hạn

Webhook

Một lệnh POST JSON tới webhook URL sẽ chạy một Automation, hoặc gửi cảnh báo tới Resolve để có thể mở sự cố và bắt đầu phân tích nguyên nhân gốc. Tạo loại nào cũng cần vai trò workspace Admin. Dùng webhook khi bạn chỉ cần kích hoạt công việc rồi đi tiếp; dùng A2A API khi bên gọi cần nhận câu trả lời. Xem Webhook.

Claude connector

Claude connector là một máy chủ Model Context Protocol (MCP) từ xa tại:
Thêm connector trong claude.ai, ứng dụng Claude desktop hoặc Claude Code. Hiện chỉ client Claude kết nối được. Trên gói Claude Team hoặc Enterprise, chủ sở hữu tổ chức Claude thêm connector trước, sau đó từng thành viên kết nối. Xem Claude connector.

Cấp phát SCIM

SCIM 2.0 cho phép Okta hoặc Microsoft Entra ID thêm, tạm ngưng và gỡ thành viên CloudThinker. Bạn cần gói Scale hoặc Enterprise, một kết nối SSO đang hoạt động với domain đã xác minh, và vai trò Owner của tổ chức. Khi SCIM bật, CloudThinker tắt tính năng mời thành viên. Xem Cấp phát SCIM.

CLI

CLI cloudthinker chạy trên macOS và Linux. Chưa có bản build Windows gốc. Cài đặt và đăng nhập:
Nếu không muốn pipe script vào sh, hãy tải archive từ trang releases. Mỗi archive có checksum SHA-256 đi kèm. Với script và CI, cloudthinker chat -p "Check production health" in một câu trả lời ra stdout và dùng được trên mọi gói, kể cả Free. Agent tương tác (cloudthinker) cần gói Team, Scale hoặc Enterprise. CLI đang ở giai đoạn preview, nên tên lệnh và flag có thể thay đổi. Xem CLI.

Khắc phục sự cố

Liên quan

Webhook

Chạy một Automation hoặc gửi cảnh báo tới Resolve bằng một lệnh POST

Claude Connector

Dùng CloudThinker từ Claude qua MCP từ xa