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 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ụ
client_credentials.{"error": "invalid_client", "error_description": "..."}.2
Gửi câu hỏi
POST một request JSON-RPC 2.0 CloudThinker trả về task ngay lập tức. Hãy giữ lại
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.id của task:3
Poll để lấy câu trả lời
Gọi Dừng poll khi
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.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: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ớihttps://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:
{"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ớiPOST /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ếumessageId đã đượ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:
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ượngerror. 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: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
CLIcloudthinker chạy trên macOS và Linux. Chưa có bản build Windows gốc. Cài đặt và đăng nhập:
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