Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: the agent in the editor had no page anywhere

yhh4ef74dfab722
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index d57e3da5e..d40ef47f2 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -139,6 +139,7 @@ export default defineConfig({
{ label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'guides/minigame-platforms' },
{ label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },
{ label: 'Editor Plugins', translations: { 'zh-CN': '编辑器插件' }, slug: 'guides/editor-plugins' },
+ { label: 'The Built-in Agent', translations: { 'zh-CN': '内置 Agent' }, slug: 'guides/agent' },
{ label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },
],
},
diff --git a/docs/astro/src/assets/guides/en/agent-preview.png b/docs/astro/src/assets/guides/en/agent-preview.png
new file mode 100644
index 000000000..8be44f690
Binary files /dev/null and b/docs/astro/src/assets/guides/en/agent-preview.png differ
diff --git a/docs/astro/src/assets/guides/en/agent-settings.png b/docs/astro/src/assets/guides/en/agent-settings.png
new file mode 100644
index 000000000..40971793c
Binary files /dev/null and b/docs/astro/src/assets/guides/en/agent-settings.png differ
diff --git a/docs/astro/src/assets/guides/en/agent-turn.png b/docs/astro/src/assets/guides/en/agent-turn.png
new file mode 100644
index 000000000..804f00047
Binary files /dev/null and b/docs/astro/src/assets/guides/en/agent-turn.png differ
diff --git a/docs/astro/src/assets/guides/zh/agent-preview.png b/docs/astro/src/assets/guides/zh/agent-preview.png
new file mode 100644
index 000000000..2711a38ff
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-preview.png differ
diff --git a/docs/astro/src/assets/guides/zh/agent-settings.png b/docs/astro/src/assets/guides/zh/agent-settings.png
new file mode 100644
index 000000000..7adbcb664
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-settings.png differ
diff --git a/docs/astro/src/assets/guides/zh/agent-turn.png b/docs/astro/src/assets/guides/zh/agent-turn.png
new file mode 100644
index 000000000..649d7f204
Binary files /dev/null and b/docs/astro/src/assets/guides/zh/agent-turn.png differ
diff --git a/docs/astro/src/content/docs/guides/agent.mdx b/docs/astro/src/content/docs/guides/agent.mdx
new file mode 100644
index 000000000..09b97f1ae
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/agent.mdx
@@ -0,0 +1,135 @@
+---
+title: The Built-in Agent
+description: Ask the editor to do something in plain language. The agent reads your scene and edits it through the same tools the editor's own UI uses — with an Undo checkpoint around every turn and a confirmation before anything Undo cannot reach.
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+The editor ships with an agent of its own. You type a sentence; it reads the scene,
+calls the same tools the editor's UI calls, and shows you every one of them as it
+goes. Nothing about it is a separate copy of the editor: it drives the exact tool
+catalog an [external MCP client](/docs/guides/mcp/) drives, so what it can do and
+what the editor can do are one list.
+
+<Aside type="tip">
+It is the same window you were already working in. Its edits land in your scene,
+your Undo takes them back, and you can take the mouse at any moment.
+</Aside>
+
+## Give it a model
+
+The editor ships no key and calls nothing on its own. Open **Settings ▸ AI Agents**
+and configure one provider — that is the whole setup.
+
+![Settings ▸ AI Agents — a key field per provider, plus the custom endpoint and model list](../../../assets/guides/en/agent-settings.png)
+
+<Steps>
+
+1. Paste an **API key** for Anthropic or DeepSeek. Each provider keeps its own, so
+ switching back to one you used last week costs nothing.
+
+2. Or fill in the **Custom Provider**: any Anthropic-compatible endpoint, plus the
+ model names it offers. Those names become choices in the composer.
+
+3. Close Settings. The model picker sits next to the box you type in — it is a
+ per-message choice, not a preference buried in a dialog.
+
+</Steps>
+
+<Aside type="tip" title="Where the key lives">
+In the system keychain. It is never written to the project, never written to the
+settings file, and never handed back to the editor window — only to the client that
+has to send it.
+</Aside>
+
+## Ask it something
+
+Open the command palette (`Ctrl/Cmd+Shift+P`) and run **Agent: Open**. Or skip that:
+type your question straight into the palette. Anything that reads as a sentence
+rather than a command offers **Hand to Agent**, and `Enter` sends it.
+
+![A finished agent run: the question, two tool calls, and the answer](../../../assets/guides/en/agent-turn.png)
+
+A run reads top to bottom:
+
+- **The question**, with the model that answered it, how long it took, and the
+ tokens it cost.
+- **A row per tool call** — `get_scene_tree`, `get_event_bindings` — with its
+ arguments and how much came back. This is the part worth reading: it is the
+ difference between an answer about your scene and an answer about scenes in
+ general.
+- **The answer.**
+
+In the composer, `@` references an entity by name so you do not have to describe
+which one you mean. You can drop or paste an **image** — a mock-up, a screenshot of
+the bug — and it is sent along with the question, where the endpoint accepts images.
+While it works, the status bar carries a live segment with a **Stop** button, so a
+long run is visible and interruptible with the drawer closed.
+
+## What it may do without asking
+
+The tiers are drawn where **Undo stops working**, which is what makes them worth
+knowing:
+
+| Tier | Examples | What happens |
+| --- | --- | --- |
+| Read | `get_scene_tree`, `get_inspector`, `capture_viewport` | Runs. Never asks. |
+| Undoable | create, delete, `set_field`, re-parent, paint tiles | Runs. The whole turn is bracketed by one checkpoint, so a single **Undo** takes all of it back. |
+| Irreversible | writing a file, exporting a build, saving, `run_editor_command` | **Always asks first.** Undo cannot rescue you afterwards. |
+
+So the approval you give is not per edit — it is the Undo button, and it applies to
+the turn as a whole. When a run finishes having changed something, the transcript
+leaves a bar behind offering **Undo** or **Keep**, and it tells you if you have
+edited since (because then Undo would take your own work back too).
+
+## Before a large edit
+
+One undoable tool still stops to ask, and not for safety: `apply_scene_ops` authors
+a whole subtree in a single call, and a hundred-node edit is worth seeing before it
+lands rather than reading back afterwards.
+
+![The preview of a bulk scene edit: six changes listed, each strikeable, with Apply all / Allow for this run / Skip](../../../assets/guides/en/agent-preview.png)
+
+Every line is one change. Click one to **strike it out** — striking a new entity also
+strikes whatever refers to it — then **Apply** the rest. **Allow for this run** stops
+the asking until the turn ends, which is what keeps a long build from becoming a
+hundred prompts; the next run asks again.
+
+Declining is not a dead end: the agent is told it was skipped and works around it.
+
+## The conversation is kept with the project
+
+A finished run is saved alongside the project — the transcript and the model's memory
+of it. **Earlier conversations** lists them; pick one and it carries on where it
+stopped. The next question in an open conversation still has everything the previous
+one established.
+
+Two things are worth knowing about a long one:
+
+- **The context gauge** in the drawer's header says how full the model's window is.
+ Past a threshold the earliest runs are *folded out of its memory*: what you asked is
+ kept word for word, the tool calls and their results are not. The transcript still
+ shows them — the model can no longer read them. When that happens the drawer says
+ so, on the line where it happened.
+- **A conversation belongs to the model that answered it.** Switching models ends it
+ and starts a new one. What it changed in the scene stays.
+
+You can also **ask a run again** in different words: it discards that run and
+everything after it, then re-asks. Useful when a turn went the wrong way three
+messages ago and you would rather not talk it back.
+
+<Aside type="caution">
+It can be confidently wrong, like any model — most often about state it read several
+runs ago. When an answer describes your scene rather than reasoning about it, ask it
+to re-read rather than trusting the summary. That is also why the tool rows are on
+screen: they show what it actually looked at.
+</Aside>
+
+## See also
+
+- [AI Agents (MCP)](/docs/guides/mcp/) — the same tool catalog, driven from Claude
+ Code, Cursor, or your own agent instead of from inside the editor.
+- [Event Binding](/docs/guides/events/) — what the agent reaches for when you ask
+ for behaviour without code.
+- [Prefabs](/docs/guides/prefab/) — in Prefab Mode the agent edits the prefab, not
+ the scene. Check the document it is working on before asking for a big change.
diff --git a/docs/astro/src/content/docs/zh-cn/guides/agent.mdx b/docs/astro/src/content/docs/zh-cn/guides/agent.mdx
new file mode 100644
index 000000000..ae4810333
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/agent.mdx
@@ -0,0 +1,121 @@
+---
+title: 内置 Agent
+description: 用一句话让编辑器干活。Agent 会读你的场景,并通过编辑器 UI 自己用的那套工具来改动它——每一轮外面都套着一个撤销检查点,撤销够不到的事情则一律先问过你。
+---
+
+import { Aside, Steps } from '@astrojs/starlight/components';
+
+编辑器自带一个 Agent。你打一句话,它读场景、调用编辑器 UI 调用的同一批工具,
+并把每一次调用都摊在你眼前。它不是编辑器的另一份复制品:它驱动的工具目录,
+和[外部 MCP 客户端](/docs/zh-cn/guides/mcp/)驱动的是同一份——它能做什么,
+和编辑器能做什么,是一张清单。
+
+<Aside type="tip">
+它就在你原本工作的那个窗口里。它的改动落在你的场景上,你的撤销能收回它们,
+你随时可以把鼠标拿回来。
+</Aside>
+
+## 先给它一个模型
+
+编辑器不附带任何密钥,也不会自己发起任何调用。打开**设置 ▸ AI 代理**,
+配好一个提供方,配置就算做完了。
+
+![设置 ▸ AI 代理——每个提供方一个密钥字段,外加自定义接口地址与模型列表](../../../../assets/guides/zh/agent-settings.png)
+
+<Steps>
+
+1. 填入 Anthropic 或 DeepSeek 的 **API 密钥**。每个提供方各存各的,
+ 所以切回上周用过的那个不用重新输入。
+
+2. 或者填**自定义提供方**:任何兼容 Anthropic 的接口地址,加上它提供的模型名。
+ 这些名字会出现在输入框旁边的模型选择器里。
+
+3. 关掉设置。模型选择器就在你打字的那个框旁边——它是**逐条消息**的选择,
+ 而不是埋在对话框里的偏好设置。
+
+</Steps>
+
+<Aside type="tip" title="密钥存在哪">
+存在系统钥匙串里。它不写进项目、不写进设置文件,也不会交回给编辑器窗口——
+只交给那个必须发送它的客户端。
+</Aside>
+
+## 问它点什么
+
+打开命令面板(`Ctrl/Cmd+Shift+P`)执行 **Agent:打开**。或者干脆跳过这一步:
+直接把问题打进命令面板。凡是读起来像一句话而不像命令的输入,面板都会给出
+**交给 Agent**,按 `Enter` 就发出去了。
+
+![一轮跑完的 Agent 对话:问题、两次工具调用,以及回答](../../../../assets/guides/zh/agent-turn.png)
+
+一轮对话从上往下读:
+
+- **问题**,旁边是回答它的模型、耗时,以及花掉的 token。
+- **每次工具调用一行**——`get_scene_tree`、`get_event_bindings`——带上参数和
+ 返回的条数。这部分才是值得读的:它决定了你拿到的是**关于你这个场景**的回答,
+ 还是一段泛泛而谈。
+- **回答**。
+
+在输入框里,用 `@` 可以按名字引用实体,省得你去描述指的是哪一个。你也可以
+拖入或粘贴**图片**——一张设计稿、一张 bug 截图——在接口支持图片时它会随问题
+一起发出去。它干活期间,状态栏上会有一条实时的段落,带**停止**按钮,
+所以抽屉关着也看得见进度、也随时能叫停。
+
+## 哪些事它不用问就能做
+
+分级是按**撤销在哪里失效**划的,这也是它值得你知道的原因:
+
+| 层级 | 例子 | 会发生什么 |
+| --- | --- | --- |
+| 只读 | `get_scene_tree`、`get_inspector`、`capture_viewport` | 直接跑,从不询问。 |
+| 可撤销 | 新建、删除、`set_field`、改父子、刷瓦片 | 直接跑。整一轮外面套着一个检查点,一次**撤销**就能全退。 |
+| 不可逆 | 写文件、导出构建、保存、`run_editor_command` | **一定先问**。事后撤销救不了你。 |
+
+所以你给出的许可并不是逐条改动的许可——它就是撤销按钮,而且作用于**整一轮**。
+一轮跑完且确实改了东西时,记录下面会留一条**撤销 / 保留**的横条;
+如果你自己之后又编辑过,它会提示你——因为那时撤销会把你自己的活也一并退回。
+
+## 大批改动落地之前
+
+有一个可撤销的工具仍然会停下来问,而且不是出于安全:`apply_scene_ops`
+一次调用就能搭出一整棵子树,上百个节点的改动值得在落地**之前**看一眼,
+而不是事后再读回来。
+
+![一批场景改动的预览:列出 6 项改动,每一行都能划掉,下面是全部应用 / 本轮都允许 / 跳过](../../../../assets/guides/zh/agent-preview.png)
+
+每一行就是一项改动。点一行可以**划掉**它——划掉一个新建实体时,
+引用它的行会一并划掉——然后应用剩下的。**本轮都允许**会让它在这一轮里
+不再询问,这正是让一次长时间搭建不至于变成一百次弹窗的东西;下一轮会重新问。
+
+拒绝也不是死路:Agent 会被告知这一步被跳过了,然后绕开它继续。
+
+## 对话跟着项目一起保存
+
+跑完的对话会和项目存在一起——记录,以及模型对它的记忆。**历史对话**里列着它们,
+挑一段就能从当时停下的地方接着聊。在一段打开的对话里继续提问,
+前面建立起来的东西都还在。
+
+一段长对话里有两件事值得知道:
+
+- 抽屉顶部的**上下文刻度**表示模型的窗口用掉了多少。超过阈值后,
+ 最早的几轮会被*折叠出它的记忆*:你问过的话原样保留,工具调用和结果不保留。
+ 记录里仍然显示着它们——只是模型读不到了。发生这件事时,抽屉会在发生的那一行说出来。
+- **一段对话属于回答它的那个模型。** 切换模型会结束当前这段并重新开始。
+ 它对场景做过的改动仍然保留。
+
+你还可以**换个说法重新提问**某一轮:它会丢弃那一轮以及之后的所有内容,然后重问。
+当三条消息之前就跑偏了、而你不想再靠聊天把它拉回来时,这个很好用。
+
+<Aside type="caution">
+和任何模型一样,它可能非常自信地说错——最常见的是关于它好几轮之前读到的状态。
+当一个回答是在**描述**你的场景而不是在推理时,让它重新读一遍,别信那段转述。
+这也正是工具调用行摆在明面上的原因:它们显示的是它真正看过的东西。
+</Aside>
+
+## 参见
+
+- [AI 代理 (MCP)](/docs/zh-cn/guides/mcp/) —— 同一份工具目录,
+ 只不过是从 Claude Code、Cursor 或你自己的代理去驱动,而不是从编辑器内部。
+- [事件绑定](/docs/zh-cn/guides/events/) —— 你要求"不写代码的行为"时,Agent 会去用的东西。
+- [预制体](/docs/zh-cn/guides/prefab/) —— 在预制体模式下,Agent 编辑的是预制体而不是场景。
+ 要它做大改动之前,先确认它正在编辑的是哪个文档。