Claix Retrieve · Agents
Agents: one endpoint, one job, only the data you allow
A Claix agent is the endpoint that your application or your own AI agent calls to get answers from your database. It has a name that becomes its URL, a business prompt that explains its job, the routes it can use, and a response mode. You create it once and call it from anywhere.
No code to write and nothing to host. Your AI agent decides what to do. A Claix agent only retrieves data for it, within the limits you set.
Definition
What is an agent?
A Claix agent is the identity that asks your database questions through Claix. It is not the same as the AI agent you build. Your agent decides what to do. A Claix agent only retrieves data for it, within the limits you set.
Every agent has five parts.
- A name. It becomes the agent's own URL: /retrieve/ followed by the name you choose.
- A description. What the agent is for.
- A business prompt. Its job, and when to use each route.
- Routes. The routes the agent can use, which decide the tables and columns it can reach.
- A response mode. Whether you get the raw result of the query, or a reasoned answer.
Runtime
What an agent does when your application asks a question
- 01
Your application sends questions to the agent's URL
One or several, each with the type of answer you expect.
- 02
Claix chooses a route
Among the routes attached to that agent. If no route fits, it doesn't guess.
- 03
One read-only query
Using only the tables and columns of that route.
- 04
Response mode decides the shape
The raw result of the query, or a reasoned answer in the type you asked for.
- 05
Answers come back in order
With a log_id you can look up in Traces.
Why agents
Why use agents
One endpoint per job
A support bot, an internal assistant and a workflow check each get their own agent, with their own URL.
Different agents, different data
Each agent only uses the routes attached to it, so two agents on the same database can see different tables and columns.
Your rules in plain language
The business prompt is text you can read and change.
Raw data or a reasoned answer
You choose what comes back, for each agent.
Several questions in one request
Send a list and get a list of answers.
Test before you connect
Try an agent with real questions in the Sandbox, and review requests in Traces.
Setup
How to create an agent
- 01
Connect your database, publish your Data Map and create your routes
An agent uses the routes you have prepared.
- 02
Create the agent
Give it a name and a description. The name is the last part of its URL.
- 03
Write the business prompt
Explain what the agent does and when to use each route.
- 04
Attach routes
Choose the routes this agent can use.
- 05
Choose the response mode
The raw result of the query, or a reasoned answer.
- 06
Test it in the Sandbox
Then call it from your application.
Response
What you get back
This is a response from an agent that was asked three questions. Each question says the type of answer expected, and the answers come back in the same order, with a log_id.
The first answer is null because the phone number is not in the data the agent can use. Claix doesn't invent a value.
[
{
"user_ask": [
{
"question": "What is the phone number of the employee named Carlos?",
"format": "string"
},
{
"question": "Has the customer Javier Perez accepted marketing consent?",
"format": "boolean"
},
{
"question": "What is Marta's job title?",
"format": "string"
}
],
"ia_response": [
null,
true,
"Waiter"
],
"log_id": "9ff38974-1392-4c1a-83e5-3b2f09bb43dc"
}
]Modes
Response modes
Each agent has a response mode. In Answer mode, the rows returned by the query are sent to the model so it can write the answer. If your data is sensitive, take that into account when you choose the mode.
| Mode | What you get | Good for |
|---|---|---|
| Data | The result of the query, as it comes out of your database | Code and other agents that process the result themselves |
| Answer | A reasoned answer in the type you asked for: text, number, true or false, date, list or JSON | Results that go straight to a person or to a workflow that needs a single value |
Business prompt
Writing a good business prompt
The business prompt tells the agent what its job is and when to use each route. It also helps the agent interpret your data, for example what a code means. What the agent can actually reach is decided by the routes attached to it.
You are the reservations assistant for a restaurant group. Use the Bookings route for questions about reservations and tables. Use the Staff route for questions about shifts and roles. Do not answer questions about payments. Status C means confirmed, P means pending and X means cancelled.
- What the agent is for, and who it serves.
- When to use each route.
- What it should not answer.
- What your terms and codes mean.
Roles
Agents and routes
You create the route once, and attach it to the agents that need it. A support agent and an internal assistant can work on the same database and still see different data, because each has different routes.
| Agent | Route |
|---|---|
| Decides who asks, and which routes it can use | Decides what data can be used, and how to read it |
| Contains name, description, business prompt, routes and response mode | Contains name, description, tables, columns and a guide |
| Has its own URL: yes | Has its own URL: no |
Examples
How you could set up agents
These are examples of how you could set up agents. They are not customer stories.
An HR assistant
An agent with a Staff route, and a business prompt that says it answers questions about employees' roles. Question: What is Marta's job title? Mode: Answer, with a text answer.
A consent check for a workflow
An agent with a Customers route that includes only the name and marketing consent. Question: Has the customer Javier Perez accepted marketing consent? Mode: Answer, with a true or false answer your workflow can use.
A reservations assistant
An agent with a Bookings route and a Tables route. Question: What is Javier Perez's next reservation? Mode: Answer, with an object containing the details, or Data, if your own code builds the reply.
A support agent for orders
An agent with an Orders route. Question: How many orders have been shipped this month? Mode: Data, if another system will process the result.
Limits
Good to know
- An agent can only use its attached routes, so what it can reach is defined by them and by the role Claix uses to connect to your database. Use a read-only role.
- Access is by agent, not by end user. An agent can read everything its routes include, for every person or system that calls it.
- Keep your API key on the server. Your API key authenticates the requests. Don't put it in browser or mobile code.
- If the data isn't there, the answer is empty. Claix doesn't invent a value.
- You choose the model. In LLM Keys, use Claix Managed AI or your own provider key.
Frequently asked questions
- What is an agent in Claix?
- A named endpoint with a business prompt, a set of routes and a response mode, which answers questions from your database.
- Is a Claix agent the same as my AI agent?
- No. Your AI agent decides what to do. A Claix agent retrieves data for it, and only from the routes attached to it.
- How do I call an agent?
- Send your questions to the agent's URL, which is /retrieve/ followed by its name, and authenticate with your API key.
- Can one agent use several routes?
- Yes. The business prompt tells it when to use each route.
- Can I ask several questions at once?
- Yes. Send a list of questions in one request and get the answers back in the same order.
- What is the difference between Data and Answer?
- Data returns the result of the query as it is. Answer returns a reasoned answer in the type you asked for, and the rows are sent to the model to produce it.
- How do I test an agent?
- Use the Sandbox to ask real questions, and check the requests in Traces.
Create your first agent
Connect your database, prepare your routes and give your AI agents a controlled way to get answers.