Edition boundary (

service-ai

→ cloud; open = MCP-only). The in-UI AI runtime — the

ask

/

build

agents, in-product chat, and the

/api/v1/ai/*

routes (

@objectstack/service-ai

) — ships in the cloud / Enterprise distribution, not the open framework. The agent / skill / tool schemas in

@objectstack/spec/ai

stay open, so you author

*.skill.ts

/

*.tool.ts

as source either way (

*.agent.ts

is platform-internal) — but they only execute in a cloud / EE host. On the open edition there is no in-product agent: expose the app to your own AI via

@objectstack/mcp

(BYO-AI) for data query, and author metadata in source mode with an AI coding agent (Claude Code, Cursor).

• You need to define skills — bundles of related tools bound to the

  ask

  /

  build

  surfaces.
• You are configuring tools for data queries, actions, or integrations.
• You want to index ObjectStack data as a knowledge source for RAG retrieval.
• You are choosing and configuring LLM models (model registry).
• You need to read or review agent configuration — platform-internal; third parties extend agents via skills, not by authoring them.

Best practice: Always model via Skills first. Direct tool assignment to agents is supported but considered legacy. Skills provide better discoverability, instruction scoping, and reuse.

• ask

  — the data product (≈ Claude Chat). Conversational read / query / explore over records, plus running the business actions the app already exposes. End-user audience, RLS-bounded. Canonical id

  ask

  (

  ASK_AGENT_NAME

  ). Cloud / Enterprise — the

  ask

  runtime ships in the closed cloud AI runtime (

  @objectstack/service-ai

  ); it is the implicit copilot for any cloud / EE app that does not pin

  app.defaultAgent

  . (Open editions have no in-product

  ask

  ; use MCP.)

• build

  — the authoring product (≈ Claude Code). Agentic authoring of metadata (objects, fields, views, flows) through plan → draft → verify → publish. Builder audience, governance-gated. Canonical id

  build

  . Cloud-only · paid — ships in the cloud AI Studio plugin; Studio pins it via

  app.defaultAgent

  .

build

ask

Legacy names are aliases only.

data_chat

→

ask

and

metadata_assistant

→

build

resolve through the alias table for old bookmarks and persisted

agent_id

s; they are not vocabulary — always write

ask

/

build

.

*.agent.ts

is closed to third parties (

agent

type is

allowRuntimeCreate:false, allowOrgOverride:false

): you extend the platform with skills, never by authoring an agent (ADR-0063 §2).

surface: 'ask' | 'build' | 'both'

'ask'

'both'

resolveActiveSkills

ask

surface

schema_reader

both

list_objects

describe_object

query_data

data_explorer

ask

query_records

get_record

aggregate_data

visualize_data

actions_executor

ask

action_*

metadata_authoring

solution_design

build

data_explorer

schema_reader

skills[]

active: false

surface:'build'

skills are inert on OSS — by design, not a bug. The open single-env framework ships only the

ask

agent;

metadata_authoring

/

solution_design

(and any third-party

surface:'build'

skill) are supplied by the cloud AI Studio plugin and simply do not resolve in OSS. A

build

-intent turn on OSS degrades gracefully ("authoring lives in the cloud Build assistant") instead of dead-ending — this is intentional tiering. Do not assume authoring tools resolve in the open framework.

visualize_data

: the only built-in tool that draws a chart — it aggregates an object and emits an inline

data-chart

part. Auto-registered only when an analytics service (

IAnalyticsService

) is wired;

query_data

/

aggregate_data

return numbers, not charts.

Ops: set

AI_DAILY_USER_MESSAGES=<N>

to cap user turns per user per day (backed by the

ai_usage_daily

object; no-op if unset). Adapter health is observable at

GET /api/v1/ai/status

; invalid

ai

settings are rejected at save time.

Reference only — third parties do not author agents. The

agent

type is closed (

allowRuntimeCreate:false

; ADR-0063 §2): the platform ships exactly

ask

and

build

, maintained by platform / cloud plugin authors. You extend the platform with skills + tools (and knowledge sources) — never by adding an agent. This section documents

AgentSchema

for reading existing agents and for platform-internal work.

surface

'ask' | 'build' | 'both'

'ask'

description

instructions

triggerPhrases

triggerConditions

active

true

A skill has no

permissions

key — it was removed in 16.x. Skill invocation was never gated by it (the registry reads only

active

/

triggerConditions

/

tools

), and a security-shaped field that enforces nothing is worse than no field at all. Gate access at the agent instead —

access

/

permissions

on

defineAgent

are enforced at the chat route — or on the underlying actions the skill's tools call (permission sets, ADR-0066).

type: 'tool'

*.tool.ts

ToolSchema

name

label

description

parameters

objectName

outputSchema

ToolSchema

category

permissions

active

builtIn

permissions

active: false

requiresConfirmation

import { defineTool } from '@objectstack/spec';

export default defineTool({
  name: 'create_case',
  label: 'Create Support Case',
  description: 'Creates a new support case record',
  parameters: {
    type: 'object',
    properties: {
      subject: { type: 'string', description: 'Case subject' },
      priority: { type: 'string', enum: ['low', 'medium', 'high'] },
    },
    required: ['subject'],
  },
  objectName: 'support_case',
});

action.requiredPermissions

action.ai.category

Tool metadata is a read-only projection — not an execution entry point.

ToolSchema

has no

handler

/

implementation

field, and no framework executor loads a metadata-authored tool. The runtime executes a separately-registered

AIToolDefinition

(cloud

@objectstack/service-ai

); tool metadata is a one-way projection for Studio / discovery. Do not expect a hand-authored tool to run in the open edition (liveness audit #1878/#1892).

Cloud / EE runtime.

registerActionsAsTools()

,

AIServicePlugin

, and the HITL approval queue below ship in

@objectstack/service-ai

— the closed cloud / Enterprise runtime, not an open package. On the open edition, expose actions to your own AI via

@objectstack/mcp

instead.

Action

defineObject({ actions: [...] })

action_<actionName>

registerActionsAsTools()

AIServicePlugin

action.type

script

IDataEngine.executeAction(object, target, ctx)

api

action.target

fetch

AIServicePlugin({ apiActionBaseUrl, apiActionHeaders })

apiClient

flow

IAutomationService.execute(target, { triggerData })

automation

• UI-only types (

  url

  ,

  modal

  ,

  form

  ).
• Dangerous variants (

  confirmText

  set,

  mode: 'delete'

  ,

  variant: 'danger'

  ) — unless the plugin is started with

  enableActionApproval: true

  , in which case they route through the HITL approval queue (see below).
• Owner opt-outs (

  aiExposed: false

  ).

type:'api'

recordIdParam

recordIdField

'id'

bodyExtra

bodyShape: { wrap: 'data' }

data

recordIdParam

actionSkipReason(action, ctx)

@objectstack/service-ai

actionRequiresApproval(action)

Cloud / EE runtime. The HITL approval queue is part of

@objectstack/service-ai

and is not available in the open framework.

kernel.use(new AIServicePlugin({
  enableActionApproval: true,   // opt in; default is false
  apiActionBaseUrl: process.env.OS_AI_ACTION_API_BASE_URL,
}));

1. LLM picks

   action_delete_task

   → runtime persists an

   ai_pending_actions

   row and returns

   { status: 'pending_approval', pendingActionId }

   .
2. Operator triages via Studio's AI Pending Actions inbox (or the REST endpoints:

   GET/POST /api/v1/ai/pending-actions/...

   ).
3. Approve → service re-runs the action via the pre-registered bypass-approval dispatcher; row transitions to

   executed

   /

   failed

   .
4. Reject → row transitions to

   rejected

   with an optional reason.

IAIService

proposePendingAction

approvePendingAction

rejectPendingAction

listPendingActions

IDataEngine

import { KnowledgeSourceSchema, type KnowledgeSource } from '@objectstack/spec/ai';

export const supportKb: KnowledgeSource = KnowledgeSourceSchema.parse({
  id: 'support_kb',
  label: 'Support Knowledge Base',
  adapter: 'ragflow',                       // or 'memory' for dev/test
  source: {
    kind: 'object',
    object: 'kb_article',
    contentFields: ['title', 'body'],       // concatenated into document content
    metadataFields: ['category', 'owner_id'], // projected for search-time filtering
    where: { published: true },             // index published articles only
  },
  refresh: { onRecordChange: true },        // re-index on record.* events
});

Chunking, top-K, score thresholds, and rerankers are NOT platform metadata. The spec deliberately scopes them out (

embedding.zod.ts

): chunking strategies, retrieval pipelines, and RAG orchestration belong to the adapter (

adapterConfig

) or application code. The platform only carries the embed + vector primitives so any RAG strategy can be built on top.

1. Filter with

   where

   . Index only published/active records (

   where: { published: true }

   ) so draft or archived content never enters the index.
2. Index only meaningful text via

   contentFields

   . Do not include system fields or IDs; use

   *

   (all readable text fields) sparingly.
3. Project filter fields into

   metadataFields

   (e.g.

   status

   ,

   owner_id

   ,

   tags

   ) so searches can be narrowed at query time.
4. Hide with

   aiExposed: false

   when a source should be indexed but not agent-searchable.
5. Tune relevance in the adapter, not the metadata. Top-K, thresholds, and reranking are configured in your RAG backend (via

   adapterConfig

   ), not in ObjectStack metadata.

openai

anthropic

azure_openai

local

The inline agent

model.provider

enum is the narrow set above (

openai

/

azure_openai

/

anthropic

/

local

). Model-registry entries (

ModelProviderSchema

) accept a wider set: also

google

,

cohere

,

huggingface

,

custom

.

1. Overly broad instructions. Agents with vague instructions hallucinate more. Be specific about what the agent should and should not do.
2. Too many tools per skill. Keep skills focused (3–8 tools). If a skill has 15+ tools, split it.
3. Missing guardrails and approval gates. Define

   blockedTopics

   (plus the token / time budgets) in agent

   guardrails

   ; for destructive operations put a human in the loop with a gate that is actually enforced —

   enableActionApproval: true

   (HITL queue, cloud) for auto-exposed actions,

   ai.requiresConfirmation

   on the action, or

   approval: 'always'

   on an MCP tool binding. AI metadata edits are already gated: they land as drafts a human must publish (ADR-0033). ⚠️

   requiresConfirmation

   on the tool was REMOVED (#3715, ADR-0033 §2) — it was read by no execution path, so it produced no pause.

   ToolSchema

   is strict, so authoring it now fails the parse with the migration attached. There is no

   requireApprovalFor

   field.
4. Ignoring tool descriptions. The LLM uses tool

   description

   to decide when to call it. Poor descriptions = wrong tool selection.
5. Not testing trigger phrases. Ambiguous trigger phrases cause skill conflicts. Test with edge-case inputs.
6. Indexing everything. A knowledge source without a

   where

   filter and curated

   contentFields

   fills the index with drafts and boilerplate that pollute retrieval. Source hygiene is the metadata's job; relevance tuning (top-K, thresholds, reranking) belongs to the adapter.