Custom API Tools
Tạo HTTP tool riêng để assistant gọi API của bạn — có hỗ trợ authentication.
Custom API Tools phù hợp khi bạn có một HTTP API đơn giản và muốn assistant gọi API đó khi cần. Ví dụ: lookup order, tạo support ticket, kiểm tra inventory, lấy appointment hoặc gửi data vào internal system.
Tạo Tool
- Mở Admin Panel.
- Chọn assistant.
- Vào Tools.
- Nhấn New Tool.
- Điền tool details (name, URL, method, parameters).
- Cấu hình authentication nếu API yêu cầu.
- Nhấn Create hoặc Save.
Fields
| Field | Ý nghĩa |
|---|---|
| Name | Tên ngắn gọn để assistant nhận biết tool. Nên dùng tên mô tả action, ví dụ lookup_order |
| Description | Mô tả khi nào nên dùng tool. Phần này rất quan trọng vì AI dùng nó để quyết định có call tool hay không |
| Method | HTTP method: GET, POST, PUT, PATCH hoặc DELETE |
| API URL | Endpoint mà Assistant Core sẽ call |
| Parameters | Data assistant cần lấy từ user trước khi call API |
| Strict | Khi bật, parameter schema được kiểm soát chặt hơn để giảm unexpected input |
Authentication
Nếu API của bạn yêu cầu authentication, bạn có thể cấu hình trực tiếp trên mỗi tool — không cần tạo proxy endpoint.
| Auth Type | Credential cần điền | Header được tạo |
|---|---|---|
| None | (không cần) | (không gửi header) |
| Bearer | Token (ví dụ: sk-abc123) | Authorization: Bearer sk-abc123 |
| API Key | API key value | X-API-Key: <value> (hoặc header tùy chỉnh) |
| Basic | username:password | Authorization: Basic <base64 encoded> |
| Custom Header | Giá trị header | <Header Name>: <value> |
Credential được mã hóa AES-256 trước khi lưu vào database. Admin UI chỉ hiện trạng thái "Credential saved (encrypted)" — không bao giờ hiển thị credential gốc.
Khi update tool, nếu bạn để trống credential thì credential cũ sẽ được giữ nguyên. Chỉ điền credential mới khi bạn muốn thay đổi.
Parameters
Mỗi parameter gồm:
| Field | Ý nghĩa |
|---|---|
| Name | Parameter name gửi đến API |
| Type | Data type: string, number, integer, boolean hoặc array |
| Description | Giải thích rõ parameter này là gì |
| Required | Bắt buộc hay không |
| Enum values | Allowed values nếu assistant chỉ nên chọn trong một số option |
| Items type | Item type nếu parameter là array |
Request Format
| Method | Parameter format |
|---|---|
| GET | Query string |
| DELETE | Query string |
| POST | JSON body |
| PUT | JSON body |
| PATCH | JSON body |
Ví Dụ
Order lookup tool (có authentication):
| Field | Value |
|---|---|
| Name | lookup_order |
| Description | Tìm shipping status theo order ID khi user hỏi về trạng thái giao hàng |
| Method | GET |
| API URL | https://api.example.com/orders/status |
| Auth Type | Bearer |
| Credential | your-api-token-here |
| Parameter | Required string parameter tên order_id |
Khi user hỏi "đơn hàng A123 của tôi tới đâu rồi?", assistant có thể call API với order_id=A123 và header Authorization: Bearer your-api-token-here, rồi summarize result cho user.
Security Notes
- Credential được mã hóa trước khi lưu — không cần lo bị lộ trong database.
- Nếu API cần authentication phức tạp hơn (OAuth2 flow, mutual TLS), hãy tạo proxy endpoint.
- Tool description càng rõ, assistant càng ít call nhầm.
- Nếu một tool có thể thay đổi data, hãy ghi rõ trong description để assistant chỉ call khi user thật sự muốn thực hiện action.