mirror of
https://github.com/abhinavxd/libredesk.git
synced 2026-09-23 19:06:35 +00:00
Abhinav Raut
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# AI assistant custom tools test server
|
|
|
|
A small HTTP server for trying out custom tools without wiring up a real backend.
|
|
It holds two fake accounts and looks them up by the contact's external user id,
|
|
which libredesk sends in the `X-Libredesk-Contact-External-Id` header. Add your
|
|
own test users by editing the `users` map in `main.go`.
|
|
|
|
Custom tools are only called by AI assistants. Copilot gets the built-in tools
|
|
and never touches these.
|
|
|
|
## Run
|
|
|
|
```
|
|
go run ./scripts/tools-server
|
|
```
|
|
|
|
It listens on `:7070`, or pass `-addr` to change that. Every request logs the contact
|
|
headers and the raw args JSON the model sent, which is usually enough to work out
|
|
why a tool call did not do what you expected.
|
|
|
|
## Headers libredesk sends
|
|
|
|
Libredesk injects the contact and conversation context on every custom tool call.
|
|
This happens server-side, so the model cannot see or change any of it:
|
|
|
|
| Header | Value |
|
|
| --------------------------------- | -------------------------------------------------- |
|
|
| `X-Libredesk-Contact-Id` | internal contact id |
|
|
| `X-Libredesk-Contact-External-Id` | external user id (from the livechat JWT), if any |
|
|
| `X-Libredesk-Contact-Type` | `contact` or `visitor` |
|
|
| `X-Libredesk-Contact-Email` | contact email, if known |
|
|
| `X-Libredesk-Contact-Verified` | `true` only after OTP/JWT identity verification |
|
|
| `X-Libredesk-Conversation-UUID` | conversation uuid |
|
|
| `X-Libredesk-Inbox-Id` | inbox id |
|
|
|
|
A visitor can type any email address into a chat, so only trust
|
|
`X-Libredesk-Contact-Email` for account data when `X-Libredesk-Contact-Verified`
|
|
is `true`. This server returns a 403 otherwise.
|
|
|
|
Work out who the customer is from these headers and nothing else. The request body
|
|
holds the model's arguments, written from whatever the customer typed, so it must
|
|
never decide which account you return.
|
|
|
|
## Endpoints
|
|
|
|
| Endpoint | Returns |
|
|
| ---------- | ----------------------------- |
|
|
| `/account` | name, email, plan, KYC status |
|
|
| `/orders` | recent orders with status |
|
|
| `/balance` | account balance |
|
|
|
|
## Tool setup (Admin -> AI -> Tools)
|
|
|
|
Create one tool per endpoint:
|
|
|
|
- Method: `POST`
|
|
- Auth header: `X-Api-Key`
|
|
- Auth value: `test-secret-token`
|
|
- Parameters: leave empty
|
|
|
|
For example, name `get_account`, URL `http://localhost:7070/account`, description
|
|
"Get the customer's account details: name, email, plan, and KYC status."
|
|
|
|
Grant the tools to an assistant under **Admin -> AI -> Assistants**, then assign a
|
|
conversation to that assistant. Nothing gets called until you do both.
|
|
|
|
## Test contacts
|
|
|
|
Set the contact's external user id and email to one of:
|
|
|
|
- `USR1001` / alice@example.com - pro plan, KYC verified, has orders
|
|
- `USR1002` / bob@example.com - free plan, KYC pending, no orders
|
|
|
|
Error paths: bad API key -> 401, unverified contact -> 403, missing external id -> 400,
|
|
unknown id -> 404, email mismatch -> 403.
|