Skip to content

docs: align AI guides + ADR-0040 with the ask/build two-agent model (ADR-0063/0064)#2206

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xuyushun441-sys merged 1 commit into from
Jun 22, 2026
Merged

docs: align AI guides + ADR-0040 with the ask/build two-agent model (ADR-0063/0064) #2206

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 45 additions & 11 deletions content/docs/guides/ai-capabilities.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -42,27 +42,52 @@ ObjectStack provides a comprehensive AI platform:

## AI Agents

AI agents are autonomous actors that perform tasks on behalf of users.

### How agents are shaped

An agent is plain metadata validated by `AgentSchema` and created with the
`defineAgent()` factory. The key fields are:
Per [ADR-0063](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0063-two-kernel-agents-skills-are-the-extension-primitive.md)
the kernel ships **exactly two** platform agents, bound by the *surface* the user
is in — the user never picks from a roster:

| Agent | Surface | Does | Edition |
|---|---|---|---|
| **`ask`** | data console | Read / query / explore records + run the business **actions** the app exposes. RLS-bounded. | open-source · free |
| **`build`** | Studio | Author *metadata* (objects, fields, views, flows) via plan → draft → verify → publish. | cloud · paid |

There is no per-turn intent classifier and no agent dropdown: the surface binds
the agent (data console → `ask`, Studio → `build`). A `build`-shaped request that
reaches `ask` is declined and redirected to the Builder, never silently re-routed.

### You extend the platform with **skills**, not agents

`*.agent.ts` is **closed to third parties** — the `agent` metadata type is
`allowRuntimeCreate:false, allowOrgOverride:false`, reserved for the two platform
agents and platform-owned subagents (ADR-0063 §2). To give the `ask` agent a new
capability you author a **skill** (`*.skill.ts`) whose `tools` reference your
Actions / Flows / queries; it then attaches to `ask`. Every skill declares
`surface: 'ask' | 'build' | 'both'`, and an agent's tool set is the **union of its
surface-compatible skills' tools** — there is no global fall-through, so a skill
reaches an agent only when their surfaces match
([ADR-0064](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0064-tool-scoping-to-agent.md)).
`surface:'build'` skills are inert on the open-source framework (the `build` agent
is cloud-only) — intentional tiering, not a bug.

### The shape of an agent

An agent is metadata validated by `AgentSchema` (the platform's own `ask` / `build`
records use exactly these fields):

| Field | Meaning |
|------|---------|
| `surface` | `'ask'` \| `'build'` — the product surface this agent binds (ADR-0063 §1) |
| `role` | Free-text **persona** string (e.g. `"Senior Support Engineer"`) — not an enum |
| `instructions` | System prompt / prime directives |
| `model` | Provider + model config (`provider`: `openai` \| `azure_openai` \| `anthropic` \| `local`) |
| `skills` | Skill names to attach (the primary Agent → Skill → Tool capability model) |
| `tools` | Direct tool **references** `{ type, name, description }` — `type` is `action` \| `flow` \| `query` \| `vector_search`; `name` points at an existing Action/Flow/query |
| `knowledge` | RAG access: `{ topics: string[], indexes: string[] }` |

There is no `type` field and no fixed agent "type" taxonomy — the way an agent
behaves comes from its persona, instructions, skills, and tools. Likewise there
are no `triggers` or `schedule` fields on an agent; drive agents from
[Flows/Workflows](./automation) or invoke them via the chat endpoint when you
need event- or time-based behaviour.
There is no `type` field and no fixed agent "type" taxonomy — behaviour comes from
persona, instructions, skills, and tools. There are no `triggers` / `schedule`
fields on an agent; drive agents from [Flows/Workflows](./automation) or invoke
them via the chat endpoint.

<Callout type="info">
Agent tools are **references** to existing Actions, Flows, or queries — you do
Expand All@@ -71,6 +96,15 @@ not define ad-hoc tool names with inline parameter schemas here. See
LLM-callable.
</Callout>

<Callout type="warning">
The agent definitions below illustrate agent **anatomy** — they show how an
`AgentSchema` record is shaped, *not* a tenant-authoring tutorial. On today's
platform you do not ship your own agents (`*.agent.ts` is platform-internal); you
add capability by authoring a **skill** that attaches to the built-in `ask` agent.
Read the examples for structure, then express your own capability as a skill plus
the Actions/Flows its tools reference.
</Callout>

### Sales Assistant Agent

```typescript
Expand Down
4 changes: 2 additions & 2 deletions content/docs/guides/plugin-chatbot-integration.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -35,7 +35,7 @@ verified in step 3):

```bash
curl http://localhost:3000/api/v1/ai/agents
# → { "agents": [{ "name": "data_chat", ... }, ...] }
# → { "agents": [{ "name": "ask", ... }, ...] }

curl http://localhost:3000/api/v1/ai/models
# → { "models": [...] } ← may be empty until the adapter lists models
Expand DownExpand Up@@ -82,7 +82,7 @@ import { useObjectChat } from '@object-ui/plugin-chatbot';
const chat = useObjectChat({
api: 'http://localhost:3000/api/v1/ai/assistant/chat',
headers: { 'X-Environment-Id': 'env_local' },
body: { agent: 'data_chat' },
body: { agent: 'ask' },
});
```

Expand Down
4 changes: 3 additions & 1 deletion docs/adr/0040-unified-assistant-and-agent-binding.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
# ADR-0040: Unified Assistant — the end user never picks an agent

**Status**: Proposed (2026-06-11)
> **⚠️ Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** (2026-06-22). Its core decision — a *single* unified assistant carrying all skills, switched by a per-turn intent classifier — was **reversed**: the kernel now ships two agents (`ask` / `build`) bound by *surface*, and `*.agent.ts` is closed to third parties (skills are the extension primitive). The UX win it established (the user never picks from a roster) is kept, re-grounded as surface binding. Kept below as a historical record of the decision and the incident that motivated it.

**Status**: **Superseded by [ADR-0063](./0063-two-kernel-agents-skills-are-the-extension-primitive.md)** — original: Proposed (2026-06-11)
**Deciders**: ObjectStack Protocol Architects
**Builds on**: [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (draft-gated authoring tools the assistant drives), [ADR-0038](./0038-build-verification-loop.md) (the verify-fix-reverify discipline carried by skills), ADR-0037 / [framework#1694](https://github.com/objectstack-ai/framework/pull/1694) (Live Canvas — the surface the unified assistant builds into)
**Consumers**: `@objectstack/spec` (agent/skill types — clarified, not changed), `@objectstack/service-ai` (default agent composition), `../cloud/service-ai-studio` (authoring skills attach to the platform assistant), `../objectui` (chat surfaces drop the agent picker)
Expand Down