Product Guide

1. Platform overview

Each agent answers with knowledge-base context (RAG) and optional live SQL tools. You call one HTTP API with a bearer token. Plans control limits and which features are unlocked.

2. Calling the agent API

Send a POST request to /api/agent/ask with Authorization: Bearer {agent_token}.

Minimal request

curl -X POST http://localhost:8000/api/agent/ask \
  -H 'Authorization: Bearer YOUR_AGENT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"message":"What is my remaining quota?"}'

Useful parameters

• message — Required. User question.
• user_id — Optional. End-user id used in SQL tool queries (also supported as query ?user=123 or body user).
• session — Optional. Conversation id. Same value keeps memory between turns.

3. SQL Tools (live database tools)

SQL Tools are named SQL queries attached to an agent. The model can call them when the question needs live records (profile, orders, inventory). Each tool has a code like %users% used inside the agent prompt.

Setup steps

1. Attach a MySQL connection on the agent (host, database, user, password).
2. Create one or more SQL Tools with a unique code, SQL query, and description.
3. Mention the code in the system prompt so the model knows when to call it.
4. Enable SQL Tools / MySQL in agent settings (and make sure your plan allows it).

Example tool

code: %users%

SELECT id, name, email, mobile FROM users WHERE id = :user_id LIMIT 1

You are a packing assistant. When you need the current user profile, call %users%. Keep answers short.

Passing values for tools via URL/body

Pass the end-user identifier so SQL placeholders like :user_id resolve correctly.

POST /api/agent/ask?user=42
Authorization: Bearer TOKEN
{"message":"What is my email?"}

4. Database connection

The agent MySQL connection is only for SQL Tools. Vector/RAG storage uses a separate shared PostgreSQL database and is managed by the platform.

Typical fields: host, port, database, username, password, and optional SSL options.

Use a read-only DB user when possible.

5. Dedicated sessions / memory

If memory is enabled on the agent (and plan), recent turns are stored and sent again so the model remembers context.

{"message":"What did I ask earlier?","session":"web-user-42-checkout"}

How session keys work

Send session in the request. Use one key per end-user chat (widget visitor, app user, browser tab, etc.). If you omit it, the API creates an automatic fingerprint.

{"message":"What did I ask earlier?","session":"web-user-42-checkout"}

chat_memory_turns controls how many previous turns are included. Set 0 to effectively disable history for that agent.

6. Writing good prompts

Put role, rules, language, and when to call SQL Tools in the system prompt. Be explicit about short answers and when tools are optional.

Good example

You are a migration packing advisor.
Always answer briefly in the user language.
If you need the current user profile, use %users%.
If you need purchase history, use %products%.
Do not invent personal data.

Weak example

You are a helpful assistant. Answer questions.

• Name tools with clear codes: %users%, %orders%, %inventory%.
• Tell the model exactly when each tool is needed.
• Forbid inventing user-specific facts without tools.
• Keep the response style consistent (short / bullet / formal).

7. Knowledge bases

Upload documents to a knowledge base, attach it to the agent, wait for embedding, then ask questions. RAG retrieves relevant chunks before the model answers.

Plan limits control number of knowledge bases, storage size, and monthly questions.

8. Plans and limits

Plans gate features such as SQL Tools, custom agent settings, session memory, priority embedding, and support. Limits include agent count, KB count, storage MB, and monthly questions.