AI Builder

AI Builder 是客戶擴充套件 ObjectOS 的主要方式。開啟 ObjectOS，用自然語言描述你的需求，它就會為你構建後設資料 —— 物件、欄位、檢視、儀表盤、流程，乃至完整的應用。在你批准計劃之前什麼都不會構建，而它構建的一切都是普通的 ObjectStack 後設資料，你可以閱讀、修改和打包。

兩個 Agent：Builder 與 Assistant

ObjectOS 自帶兩個 AI Agent。你不需要在它們之間選擇：在哪裡提問決定由哪一個回答。

兩者都以已登入的人的身份執行。每次工具呼叫都會對照此人的許可權、記錄訪問和欄位級安全進行檢查，因此 AI 能看到或修改的永遠不會超過此人自己能做的。

**誰可以使用 Builder。**僅有 AI 席位還不夠：Builder 會修改你應用的後設資料，所以還需要 manage_metadata 或 studio.access 許可權。兩者都沒有的成員只能看到 Assistant，直接向 Builder 發出的請求會以 403 PERMISSION_DENIED 被拒絕，並且每個構建工具在執行時都會再次檢查該許可權。

試一試

You: I need to track customer support tickets.
     Each ticket has a subject, description, priority (low/medium/high/urgent),
     status (new/open/pending/resolved/closed), and assignee.

AI:  Here's the plan:
     • Object `support_ticket` with 5 fields
     • A kanban view grouped by status
     • A dashboard of open tickets by priority
     • A few sample tickets to try it with

     Shall I build it?

You: Yes

AI:  ✓ Object created
     ✓ Kanban view and dashboard created
     ✓ Sample data added
     Published — open Support Tickets to try it.

現在你就有了一個可用的工單應用 —— REST 端點、生成的檢視、審計日誌條目、許可權檢查點，一應俱全。沒有編輯任何檔案；也沒有發生重啟。

構建如何執行

1. 計劃。對於任何大於單個變更的需求 —— "幫我構建一個招聘系統" —— Builder 會先提出一份藍圖：它打算建立的物件、欄位、關係、檢視、儀表盤和示例資料，以及它的假設。這一步不會建立任何東西。
2. **批准。**你在對話中回答：批准它，或要求修改並得到一份修訂後的計劃。Builder 只在你於該對話中批准之後才進行變更。
3. 構建為草稿。批准的變更被寫為草稿 —— 已暫存，尚未生效。
4. **校驗。**Builder 對照平臺規則檢查草稿，並在任何內容生效之前修復它能修復的問題。
5. **釋出。**草稿被髮布到你正在構建的環境中，應用連同其示例資料出現在那裡。狀態面板會顯示實際已釋出的內容；Builder 從不會把未釋出的變更報告為已交付。

要擴充套件現有應用，直接說明即可 —— "給支援應用加一個滿意度調查" —— Builder 會把新部分設計為關聯到該應用的物件，並把它們加入其導航，而不是另建一個獨立的應用。

你可以要求什麼

如果 AI 做不到，它會直說 —— 並給你指出手動操作的路徑。

Agent 呼叫的工具

Agent 的能力就是它的工具。檢視某個環境的即時目錄：GET /api/v1/ai/tools。

Builder 的創作工具作用於包及其後設資料，並依據 @objectstack/spec 進行校驗：

Assistant 的資料工具讀取記錄並對其執行操作：

aggregate_data 屬於產品內建的 AI。通過 MCP 從外部接入的 Agent 有自己的工具集，在那裡有說明。

動作即工具

當動作的作者把它暴露給 AI 時，它就成為一個名為 action_<name> 的工具 —— ai: { exposed: true } 加上不少於 40 個字元的 ai.description，且型別可以在無 UI 的情況下執行（script、flow 或 api）。一旦暴露，AI 就可以像呼叫任何內建工具一樣呼叫它，並受呼叫者許可權約束；未暴露的動作永遠不會成為工具。參見動作。

動作執行前的審批。聲明瞭 ai.requiresConfirmation: true 的動作 —— 或看起來具有破壞性且未另行宣告的動作 —— 不會立即執行。AI 會把它登記為一個待處理動作，只有獲得批准後才會執行：

待處理動作屬於提出它的那次對話的主人：只有此人可以讀取、批准或拒絕它。其他任何人，包括管理員，得到的回應都如同它不存在一樣。

通過 API 對話

按名稱（ask 或 build）向 Agent 傳送一段對話：

curl -X POST https://your-environment-host/api/v1/ai/agents/ask/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "How many open opportunities over $50k?" }],
    "context": { "appName": "crm", "objectName": "opportunity" }
  }'

• messages —— 到目前為止的對話。客戶端只能提交 user 和 assistant 輪次。
• context —— 此人所在的位置：appName、objectName、viewName、recordId。Skill 用它來判斷什麼是相關的。
• conversationId（可選）—— 繼續一段已有對話。

回答預設以 Server-Sent Events 流式返回（Vercel AI 資料流協議，x-vercel-ai-ui-message-stream: v1）；圖表以 data-chart 部分出現在流中。傳送 "stream": false 則改為返回單個 JSON 回答。

對話儲存在 /api/v1/ai/conversations 下，每個人只能看到自己的對話。

限制

• 資料訪問遵循此人自己的許可權，讀取和動作都一樣。
• **系統包不可觸碰。**要求 AI 修改系統包（sys_*）會被拒絕。
• 大型構建分步進行效果更好。"構建一個完整的 HR 應用"是可行的，但一系列較小的對話、每次落地一個領域，更便於評審。
• 在 ObjectOS Cloud 上，AI 消耗環境的 AI 額度，並且一個環境最多容納 500 個未釋出的草稿（儲存與限制）。在自管理的 Enterprise 部署上，模型由你自己提供，在 AI 服務中配置。

超越構建期 AI

同一套 AI 基礎設施也為面向終端使用者的執行時 Agent 提供支援 —— 支援助手、銷售副駕駛、內部問答機器人 —— 它們構建在相同的 Agent → Skill → Tool 架構之上。參見 Agent。

下一步

• Agent —— 基於你資料的終端使用者助手
• 資料模型 —— AI 實際生成的是什麼
• 動作 —— AI 作為執行時工具暴露的單元
• AI 點數與限制 —— ObjectOS Cloud 上的 AI 額度
• AI 服務 —— Provider 配置（OpenAI / Anthropic / Google / DeepSeek / …）