Skip to content

docs(ai): mark the retired agent.tools key as removed in agents.mdx#10732

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
os-zhuang merged 1 commit into from
Aug 21, 2026
Merged

docs(ai): mark the retired agent.tools key as removed in agents.mdx#10732

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
14 changes: 10 additions & 4 deletions content/docs/ai/agents.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -207,7 +207,7 @@ own `ask` / `build` records use exactly these fields):
| `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 |
| `tools` | **Removed in protocol 17 (#3894)** — typed `never`, so writing it fails `tsc`, and a value that reaches the runtime is rejected at parse. This is **not** a rename: there is no key the value moves to. Declare each tool on a **skill** instead — a platform tool by its registered name, or `action_<name>` for one of your own AI-exposed Actions — and attach that skill through `skills` (ADR-0064) |
| `knowledge` | RAG access: `{ sources: string[], indexes: string[] }`. `sources` is the only key; the `topics` alias was removed in protocol 17 (#3855) — `os migrate meta --from 16` rewrites it |

There is no `type` field and no fixed agent "type" taxonomy — behaviour comes from
Expand All@@ -217,9 +217,15 @@ the **ObjectOS** runtime — via the in-product chat endpoint
(`/api/v1/ai/*`). On the open-source framework, invoke the underlying Actions/Flows through
`@objectstack/mcp`.

<Callout type="info">
Agent tools are **references** to existing Actions, Flows, or queries — you do
not define ad-hoc tool names with inline parameter schemas here. See
<Callout type="warn">
**An agent has no tool slot of its own.** Its tool set is exactly the union of
its surface-compatible skills' tools, with no fall-through to the global
registry ([ADR-0064](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0064-tool-scoping-to-agent.md)).
The removed `tools` key was the one seam that broke that invariant: the runtime
resolved `agent.tools[].name` against the **full** registry with no surface
check, so an `ask`-surface agent could name an authoring tool and reach it. So
there is nowhere on the agent to move a reference **to** — re-declare each one
in a skill's `tools` by hand, then attach the skill. See
[Actions as Tools](/docs/ai/actions-as-tools) for how an Action becomes
LLM-callable.
</Callout>
Expand Down
Loading