0
# AI Agent Integration
1

2
Parse Dashboard includes an AI-powered assistant that provides natural language interface for database operations and Parse Server management. The agent uses OpenAI's models to interpret user requests and perform database operations safely.
3

4
## Capabilities
5

6
### AI Agent Configuration
7

8
Configuration for integrating AI models with Parse Dashboard:
9

10
```javascript { .api }
11
interface AgentConfig {
12
  /**
13
   * Available AI models for the agent
14
   */
15
  models: ModelConfig[];
16
}
17

18
interface ModelConfig {
19
  /**
20
   * Model identifier/name
21
   * Used to reference the model in requests
22
   */
23
  name: string;
24
  
25
  /**
26
   * AI provider (currently only "openai" supported)
27
   */
28
  provider: string;
29
  
30
  /**
31
   * Specific model name from the provider
32
   * Examples: "gpt-4", "gpt-3.5-turbo", "gpt-4-turbo"
33
   */
34
  model: string;
35
  
36
  /**
37
   * API key for the provider
38
   * Should be kept secure and not committed to version control
39
   */
40
  apiKey: string;
41
}
42
```
43

44
### AI Agent API Endpoint
45

46
HTTP endpoint for interacting with the AI agent:
47

48
```javascript { .api }
49
// POST /apps/:appId/agent
50
interface AgentRequest {
51
  /**
52
   * User's natural language query or request
53
   * Examples: "Show me all users created today"
54
   *          "Delete all posts with empty content"
55
   *          "Create a new class called Product"
56
   */
57
  message: string;
58
  
59
  /**
60
   * Name of the AI model to use
61
   * Must match a configured model name
62
   */
63
  modelName: string;
64
  
65
  /**
66
   * Optional conversation ID for context
67
   * Allows multi-turn conversations with context
68
   */
69
  conversationId?: string;
70
  
71
  /**
72
   * Operation permissions for this request
73
   * Controls what the AI agent is allowed to do
74
   */
75
  permissions: AgentPermissions;
76
}
77

78
interface AgentPermissions {
79
  /**
80
   * Allow creating new objects/records
81
   */
82
  createObject: boolean;
83
  
84
  /**
85
   * Allow updating existing objects/records
86
   */
87
  updateObject: boolean;
88
  
89
  /**
90
   * Allow deleting objects/records
91
   */
92
  deleteObject: boolean;
93
  
94
  /**
95
   * Allow creating new classes/tables
96
   */
97
  createClass: boolean;
98
  
99
  /**
100
   * Allow deleting classes/tables
101
   */
102
  deleteClass: boolean;
103
}
104

105
interface AgentResponse {
106
  /**
107
   * AI-generated response to the user
108
   */
109
  response: string;
110
  
111
  /**
112
   * Conversation ID for continued context
113
   */
114
  conversationId: string;
115
  
116
  /**
117
   * Debug information including operations performed
118
   */
119
  debug: {
120
    timestamp: string;
121
    appId: string;
122
    modelUsed: string;
123
    operations: OperationLog[];
124
  };
125
}
126

127
interface OperationLog {
128
  operation: string;
129
  className?: string;
130
  resultCount?: number;
131
  timestamp: string;
132
}
133
```
134

135
### Database Function Tools
136

137
The AI agent has access to sophisticated database function tools for Parse Server operations:
138

139
```javascript { .api }
140
/**
141
 * Query objects from a Parse class/table
142
 */
143
interface QueryClassFunction {
144
  name: 'queryClass';
145
  parameters: {
146
    className: string;                    // Parse class name
147
    where?: Record<string, any>;          // Query constraints
148
    limit?: number;                       // Max results (default 100, max 1000)
149
    skip?: number;                        // Skip results for pagination
150
    order?: string;                       // Sort field (prefix with '-' for desc)
151
    include?: string[];                   // Pointer fields to populate
152
    select?: string[];                    // Fields to select
153
  };
154
}
155

156
/**
157
 * Create a new object in a Parse class
158
 * Requires user confirmation via confirmed parameter
159
 */
160
interface CreateObjectFunction {
161
  name: 'createObject';
162
  parameters: {
163
    className: string;
164
    objectData: Record<string, any>;      // Required: Field values for new object
165
    confirmed: boolean;                   // Must be true after user confirmation
166
  };
167
}
168

169
/**
170
 * Update an existing object
171
 * Requires user confirmation via confirmed parameter
172
 */
173
interface UpdateObjectFunction {
174
  name: 'updateObject';
175
  parameters: {
176
    className: string;
177
    objectId: string;                     // Parse object ID
178
    objectData: Record<string, any>;      // Fields to update
179
    confirmed: boolean;                   // Must be true after user confirmation
180
  };
181
}
182

183
/**
184
 * Delete a single object by ID
185
 * Requires user confirmation via confirmed parameter
186
 */
187
interface DeleteObjectFunction {
188
  name: 'deleteObject';
189
  parameters: {
190
    className: string;
191
    objectId: string;                     // Parse object ID to delete
192
    confirmed: boolean;                   // Must be true after user confirmation
193
  };
194
}
195

196
/**
197
 * Get schema information for Parse classes
198
 */
199
interface GetSchemaFunction {
200
  name: 'getSchema';
201
  parameters: {
202
    className?: string;                   // Optional: specific class, or all if omitted
203
  };
204
}
205

206
/**
207
 * Count objects in a Parse class
208
 */
209
interface CountObjectsFunction {
210
  name: 'countObjects';
211
  parameters: {
212
    className: string;
213
    where?: Record<string, any>;          // Optional query constraints
214
  };
215
}
216

217
/**
218
 * Create a new Parse class/table
219
 * Requires user confirmation via confirmed parameter
220
 */
221
interface CreateClassFunction {
222
  name: 'createClass';
223
  parameters: {
224
    className: string;
225
    fields?: Record<string, string>;      // Field definitions (name -> type)
226
    confirmed: boolean;                   // Must be true after user confirmation
227
  };
228
}
229

230
/**
231
 * Delete an entire Parse class/table and all its data
232
 * Requires user confirmation via confirmed parameter
233
 */
234
interface DeleteClassFunction {
235
  name: 'deleteClass';
236
  parameters: {
237
    className: string;
238
    confirmed: boolean;                   // Must be true after user confirmation
239
  };
240
}
241
```
242

243
**AI Agent Configuration Examples:**
244

245
```javascript
246
// Basic OpenAI integration
247
const dashboardWithAI = new ParseDashboard({
248
  apps: [{
249
    serverURL: 'http://localhost:1337/parse',
250
    appId: 'myAppId',
251
    masterKey: 'myMasterKey',
252
    appName: 'My App'
253
  }],
254
  agent: {
255
    models: [
256
      {
257
        name: 'gpt-4',
258
        provider: 'openai',
259
        model: 'gpt-4',
260
        apiKey: process.env.OPENAI_API_KEY
261
      }
262
    ]
263
  }
264
});
265

266
// Multiple AI models
267
const multiModelConfig = {
268
  apps: [{ /* app config */ }],
269
  agent: {
270
    models: [
271
      {
272
        name: 'gpt-4-turbo',
273
        provider: 'openai',
274
        model: 'gpt-4-turbo',
275
        apiKey: process.env.OPENAI_API_KEY
276
      },
277
      {
278
        name: 'gpt-3.5',
279
        provider: 'openai', 
280
        model: 'gpt-3.5-turbo',
281
        apiKey: process.env.OPENAI_API_KEY
282
      }
283
    ]
284
  }
285
};
286

287
// Environment-based configuration
288
const envAgentConfig = {
289
  apps: [{ /* app config */ }],
290
  agent: JSON.parse(process.env.PARSE_DASHBOARD_AGENT || '{}')
291
};
292
```
293

294
### Environment Variable Configuration
295

296
```bash
297
# AI Agent configuration via environment variable
298
export PARSE_DASHBOARD_AGENT='{
299
  "models": [
300
    {
301
      "name": "gpt-4",
302
      "provider": "openai",
303
      "model": "gpt-4",
304
      "apiKey": "sk-your-openai-api-key-here"
305
    }
306
  ]
307
}'
308

309
# Or using separate environment variables
310
export OPENAI_API_KEY=sk-your-openai-api-key-here
311
```
312

313
## Usage Examples
314

315
### JavaScript Client Code
316

317
```javascript
318
// Example of calling the AI agent from frontend code
319
async function queryAIAgent(appId, message, permissions) {
320
  const response = await fetch(`/apps/${appId}/agent`, {
321
    method: 'POST',
322
    headers: {
323
      'Content-Type': 'application/json',
324
      'X-Requested-With': 'XMLHttpRequest'
325
    },
326
    body: JSON.stringify({
327
      message: message,
328
      modelName: 'gpt-4',
329
      permissions: permissions
330
    })
331
  });
332
  
333
  return await response.json();
334
}
335

336
// Safe read-only query
337
const readOnlyResult = await queryAIAgent('myAppId', 
338
  'Show me all users created in the last 7 days', 
339
  {
340
    createObject: false,
341
    updateObject: false,
342
    deleteObject: false,
343
    createClass: false,
344
    deleteClass: false
345
  }
346
);
347

348
// Query with write permissions
349
const writeResult = await queryAIAgent('myAppId',
350
  'Create a new user with username "john_doe" and email "john@example.com"',
351
  {
352
    createObject: true,
353
    updateObject: false,
354
    deleteObject: false,
355
    createClass: false,
356
    deleteClass: false
357
  }
358
);
359

360
// Administrative query
361
const adminResult = await queryAIAgent('myAppId',
362
  'Create a new class called "Product" with fields: name (string), price (number), category (string)',
363
  {
364
    createObject: true,
365
    updateObject: true,
366
    deleteObject: false,
367
    createClass: true,
368
    deleteClass: false
369
  }
370
);
371
```
372

373
### Common AI Agent Queries
374

375
```javascript
376
// Data retrieval queries
377
const queries = [
378
  "Show me all users who signed up today",
379
  "Find posts with more than 100 likes",
380
  "List all products in the 'electronics' category",
381
  "Get the top 10 users by score",
382
  "Show me users who haven't logged in for 30 days"
383
];
384

385
// Data modification queries  
386
const modifications = [
387
  "Update all users with empty bio to have bio 'No bio provided'",
388
  "Delete all posts marked as spam",
389
  "Create a new category called 'Featured'",
390
  "Set all draft posts to published status",
391
  "Add a 'verified' field to the User class"
392
];
393

394
// Analytics and reporting queries
395
const analytics = [
396
  "How many users signed up each day this week?",
397
  "What's the average rating for products in each category?",
398
  "Show me the most popular posts by likes",
399
  "Generate a summary of user activity patterns",
400
  "What are the top 5 most common user locations?"
401
];
402
```
403

404
### Conversation Context
405

406
```javascript
407
// Multi-turn conversation with context
408
let conversationId = null;
409

410
// First query
411
const result1 = await fetch('/apps/myAppId/agent', {
412
  method: 'POST',
413
  headers: { 'Content-Type': 'application/json' },
414
  body: JSON.stringify({
415
    message: "Show me all users from New York",
416
    modelName: 'gpt-4',
417
    permissions: { /* read-only permissions */ }
418
  })
419
});
420

421
const response1 = await result1.json();
422
conversationId = response1.conversationId;
423

424
// Follow-up query with context
425
const result2 = await fetch('/apps/myAppId/agent', {
426
  method: 'POST', 
427
  headers: { 'Content-Type': 'application/json' },
428
  body: JSON.stringify({
429
    message: "Now show me only the ones who signed up this month",
430
    modelName: 'gpt-4',
431
    conversationId: conversationId,  // Maintains context
432
    permissions: { /* read-only permissions */ }
433
  })
434
});
435
```
436

437
## Security Considerations
438

439
### Permission Management
440

441
```javascript
442
// Strict read-only access
443
const readOnlyPermissions = {
444
  createObject: false,
445
  updateObject: false,
446
  deleteObject: false,
447
  createClass: false,
448
  deleteClass: false
449
};
450

451
// Limited write access (safe operations only)
452
const limitedWritePermissions = {
453
  createObject: true,   // Allow creating objects
454
  updateObject: true,   // Allow updating objects
455
  deleteObject: false,  // Prevent deletions
456
  createClass: false,   // Prevent schema changes
457
  deleteClass: false    // Prevent schema deletions
458
};
459

460
// Full administrative access (use with caution)
461
const adminPermissions = {
462
  createObject: true,
463
  updateObject: true,
464
  deleteObject: true,   // Dangerous: allows data deletion
465
  createClass: true,    // Dangerous: allows schema changes
466
  deleteClass: true     // Very dangerous: allows removing entire classes
467
};
468
```
469

470
### API Key Security
471

472
```javascript
473
// Secure API key handling
474
const secureConfig = {
475
  agent: {
476
    models: [
477
      {
478
        name: 'gpt-4',
479
        provider: 'openai',
480
        model: 'gpt-4',
481
        apiKey: process.env.OPENAI_API_KEY  // Never hardcode keys
482
      }
483
    ]
484
  }
485
};
486

487
// Environment file (.env)
488
// OPENAI_API_KEY=sk-your-secret-key-here
489
// Never commit .env files to version control
490
```
491

492
### User-based Permissions
493

494
```javascript
495
// Different AI permissions for different users
496
const userBasedAI = {
497
  users: [
498
    {
499
      user: 'admin',
500
      pass: 'adminPass',
501
      // Admin gets full AI access
502
    },
503
    {
504
      user: 'editor',
505
      pass: 'editorPass',
506
      // Editor gets limited AI access
507
    },
508
    {
509
      user: 'viewer', 
510
      pass: 'viewerPass',
511
      readOnly: true
512
      // Viewer gets read-only AI access
513
    }
514
  ]
515
};
516
```