AI Overview

AI in ObjectStack is a cross-protocol capability layer: agents, tools, and knowledge retrieval sit on top of the same objects, actions, permissions, and automation that power the rest of the platform. This module covers the architecture and each of its moving parts.

What's in this module

• Connect an MCP Client — point Claude Code, Claude Desktop, or any MCP client at the /api/v1/mcp server every deployment already runs, over OAuth or an API key
• AI Agents — the two platform agents (ask / build), skills as the extension primitive, and agent anatomy
• Actions as Tools — explicit opt-in exposure of Actions to the LLM, HITL approval, permission-aware execution
• Tool Records — the three ways a capability reaches an agent, and the narrow case where authoring a tool record is the right answer
• Knowledge & RAG — the Knowledge Protocol and its adapter plugins
• Natural Language Queries — the built-in data tools that turn questions into ObjectQL
• AI Skills System — structured knowledge modules for AI coding assistants
• AI Skills Reference — the per-skill catalog
• Spec: Knowledge Protocol
• Schema reference: AI

AI Architecture

ObjectStack provides a comprehensive AI platform:

flowchart TD
    A["<b>AI Agents</b> — persona + skills/tools"] --> T["<b>Skills &amp; Tools</b><br/>Actions / Flows exposed to the LLM"]
    T --> K["<b>Knowledge Protocol</b> — search_knowledge via adapters<br/>memory / ragflow / custom · permission-aware retrieval"]
    K --> R["<b>Model Registry</b> — LLM management<br/>openai · azure_openai · anthropic · local · token accounting / cost"]

Best Practices

1. AI Agent Design

✅ DO:

• Define clear agent roles and responsibilities
• Provide detailed instructions
• Use appropriate temperature settings
• Test with real-world scenarios
• Monitor agent performance

❌ DON'T:

• Give agents conflicting instructions
• Use high temperatures for factual tasks
• Deploy without testing
• Ignore cost implications

2. Knowledge & Data Access

✅ DO:

• Declare knowledge sources via the Knowledge Protocol and pick the adapter (memory, ragflow, custom) that fits your data
• Rely on the built-in data tools (query_records / get_record / aggregate_records) for live record access
• Let permission-aware retrieval and RLS scope what each user's agent can see
• Keep indexed objects in sync via the protocol's event sync

❌ DON'T:

• Reinvent a vector DB — let the adapter engine handle chunking/embedding/rerank
• Bypass ExecutionContext, which would leak rows past row-level security
• Expose objects to agents that the calling user can't read

3. Prompt Engineering

✅ DO:

• Be specific and clear
• Provide examples
• Use role-playing ("You are a...")
• Include constraints
• Test variations

❌ DON'T:

• Be vague or ambiguous
• Assume context
• Use complex jargon
• Write overly long prompts

4. Cost Management

✅ DO:

• Choose appropriate models (GPT-3.5 vs GPT-4)
• Implement caching
• Set token limits
• Monitor usage
• Use cheaper models for simple tasks

❌ DON'T:

• Always use the most expensive model
• Skip caching
• Allow unlimited tokens
• Ignore cost metrics

5. Security & Privacy

✅ DO:

• Implement access controls
• Mask sensitive data
• Log AI interactions
• Review outputs
• Follow data privacy regulations

❌ DON'T:

• Expose PII to external APIs
• Skip output validation
• Ignore audit trails
• Trust AI blindly

Real-World Integration

Complete Sales AI Workflow

Agents are metadata, not classes — there are no .enrich() / .predict() / .query() methods to call. Enrichment, scoring, and email drafting are implemented as Actions/Flows exposed as tools, and the LLM calls them while reasoning over the conversation. In the open edition, your own AI reaches those same tools over MCP (@objectstack/mcp), and you drive them on a trigger or schedule from a Flow or Workflow.

// Invoke an agent over the REST chat endpoint.
// POST /api/v1/ai/agents/:agentName/chat
const res = await fetch('/api/v1/ai/agents/sales_assistant/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
  body: JSON.stringify({
    message: `A hot lead just came in (id ${lead.id}). Qualify it, suggest the
              next best action, and draft a professional intro email.`,
  }),
});
const { reply } = await res.json();
// The agent calls its `analyze_lead` / `suggest_next_action` / `generate_email`
// tools (the Actions/Flows you wired) and returns its summary in `reply`.

Server-side, the same flow runs through chatWithTools, threading the end-user's ExecutionContext so tool calls respect row-level security:

const reply = await aiService.chatWithTools(messages, {
  toolExecutionContext: {
    actor: { id: currentUser.id, name: currentUser.displayName, positions: currentUser.positions, permissions: currentUser.permissions },
    conversationId,
    environmentId,
  },
});

To run any of this on lead creation or on a schedule, drive the agent from a Flow or Workflow rather than expecting trigger/schedule fields on the agent itself.

Next: AI Agents →