Agent Data Store

Give your agents a real database. Each user gets an isolated PostgreSQL schema for structured business data.

Quick Start

The Database Agent is a built-in system agent. Available at ab.agent("database"). Specializes in PostgreSQL schema design.

1

Design schema with Database Agent

python
from agentbackend import AgentBackend

ab = AgentBackend("ak_YOUR_API_KEY")
conv = ab.agent("database").conversation()

conv.send("Create a customers table with name, email, phone")
conv.send("Now create an orders table linked to customers")
conv.send("Add 5 sample customers")
javascript
import AgentBackend from 'agentbackend';

const ab = new AgentBackend('ak_YOUR_API_KEY');
const conv = ab.agent('database').conversation();

await conv.send('Create a customers table with name, email, phone');
await conv.send('Now create an orders table linked to customers');
await conv.send('Add 5 sample customers');
2

Add query tools to your agent

python
agent = ab.agents.create(
    name="Customer Support",
    instructions="You are a support agent. Query the database to help users.",
    tools=[
        {"name": "tenant_query", "type": "catalog"},
        {"name": "tenant_schema_info", "type": "catalog"},
    ],
)
javascript
const agent = await ab.agents.create({
  name: 'Customer Support',
  instructions: 'You are a support agent. Query the database to help users.',
  tools: [
    { name: 'tenant_query', type: 'catalog' },
    { name: 'tenant_schema_info', type: 'catalog' },
  ],
});
3

Agent queries data

python
conv = ab.agent(agent.agent_id).conversation(session_id="user_ali")
response = conv.send("Show me Ali's recent orders")
# Agent automatically queries the orders table with a JOIN to customers
javascript
const conv = ab.agent(agent.agentId).conversation({ sessionId: 'user_ali' });
const response = await conv.send("Show me Ali's recent orders");
// Agent automatically queries the orders table with a JOIN to customers

How It Works

Architecture

text
User → Agent → tenant_query tool → SQL Validator → PostgreSQL
                                                    ↓
                                            tenant_{uuid} schema
                                            (isolated per user)
  • •Each tenant gets an isolated PostgreSQL schema (tenant_{uuid})
  • •All DDL operations are tracked as versioned migrations with rollback support
  • •Schema info is automatically injected into the agent's context at runtime

Permissions

OperationDatabase AgentRegular Agent
CREATE TABLE✓✗
ALTER TABLE✓✗
DROP TABLE✓✗
SELECT✓✓
INSERT✓✓
UPDATE✓✓
DELETE✓✓

Security

  • •Tenant isolation — agents can only access their own schema
  • •SQL validation — queries are parsed and validated before execution
  • •INSERT limits — maximum 1,000 rows per INSERT statement
  • •Query timeout — 30 second timeout on all queries
  • •Error sanitization — internal database errors are never exposed to end users

Error Handling

  • •Invalid SQL — agent receives a descriptive error and can retry with corrected query
  • •Timeout — agent is notified the query exceeded 30s and should simplify
  • •Row limit — INSERT exceeding 1,000 rows is rejected with a clear message
  • •Permission denied — regular agents attempting DDL receive a permission error

API Reference

GET/v1/tenant/status
cURL
curl https://api.agentbackend.ai/v1/tenant/status \
  -H "Authorization: Bearer ak_..."
Response
{
  "has_schema": true,
  "schema_name": "tenant_abc123...",
  "tables": [
    {"table_name": "customers", "column_count": 5},
    {"table_name": "orders", "column_count": 6}
  ],
  "migration_count": 3
}
GET/v1/tenant/migrations
cURL
curl https://api.agentbackend.ai/v1/tenant/migrations \
  -H "Authorization: Bearer ak_..."
Response
{
  "migrations": [
    {
      "version": 3,
      "description": "Create index on orders.customer_id",
      "status": "applied",
      "created_at": "2026-03-25T18:31:06Z",
      "rolled_back_at": null
    }
  ]
}
POST/v1/tenant/rollback
cURL
curl -X POST https://api.agentbackend.ai/v1/tenant/rollback \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"version": 3}'
Python SDK
ab.tenant.rollback(version=3)
JavaScript SDK
await ab.tenant.rollback({ version: 3 });

Example: Customer Support Agent

A complete example of a customer support agent that queries your data store to help users with orders and account information.

python
agent = ab.agents.create(
    name="Müşteri Destek",
    instructions="""Sen bir müşteri destek asistanısın.
    Müşteri bilgilerini ve siparişlerini sorgulayarak yardım et.
    Sipariş durumunu bildir, iade talebi oluştur.""",
    tools=[
        {"name": "tenant_query", "type": "catalog"},
        {"name": "tenant_schema_info", "type": "catalog"},
    ],
)
javascript
const agent = await ab.agents.create({
  name: 'Customer Support',
  instructions: `You are a customer support assistant.
    Query customer information and orders to help users.
    Report order status, create return requests.`,
  tools: [
    { name: 'tenant_query', type: 'catalog' },
    { name: 'tenant_schema_info', type: 'catalog' },
  ],
});

Combine with Schedules for automated reports or Channels to deploy on WhatsApp and Telegram.

Limits

ResourceFreeProEnterprise
Tables per user1050200
Rows per INSERT1,0001,0001,000
Query timeout30s30s30s
SELECT row limit1,0001,0001,000