docs(agents): Build from AI Assistants

docs/guides/agents/from-ai-assistants.mdx

@@ -0,0 +1,144 @@
+---
+title: Build Agents from AI Assistants
+description: Build, save, run, evaluate, and mine Glean Auto Mode agents from inside your AI assistant using the Glean plugin and the /glean_run entry point.
+---
+
+# Build Agents from AI Assistants
+
+The Glean plugin for AI assistants lets you build, save, run, evaluate, and mine [Glean Auto Mode agents](https://docs.glean.com/agents/auto-mode-agent) from natural language inside your assistant — without leaving your editor and without going through the Glean UI. Every agent the plugin authors is a directory of files in the [Glean Auto Mode Agent Specification](./specification) format, so you can inspect, edit, version-control, and review agents like any other code.
+
+## Prerequisites
+
+- An AI assistant that supports plugins (e.g. Claude Code, Claude Cowork, Cursor).
+- The Glean plugin installed in your assistant. For Claude Code, see the [Glean Plugin for Claude Code](../mcp/claude-code) guide.
+
+## The single entry point: `/glean_run`
+
+All agent-building features are reached by prompting `/glean_run`. Describe what you want in natural language and the plugin routes your request to the right feature — build, save, run, evaluate, or mine.
+
+```text
+/glean_run build an agent named daily-task-planner that helps users plan and prioritize their daily tasks
+/glean_run save the agent in ./daily-task-planner
+/glean_run run daily-task-planner with input "plan my Monday around two design reviews and a 1:1"
+/glean_run evaluate daily-task-planner against the seeded eval set
+/glean_run mine candidate agents from my recent work
+```
+
+## Features
+
+### Build
+
+Creates a new agent or refines an existing one. Use it both to scaffold from a fresh prompt and to iterate on an agent that already exists on disk — point it at the same `agent_name` with new instructions and the plugin will update `spec.yaml`, `instructions.md`, tool selections, and knowledge sources in place.
+
+What it does:
+
+- Generates or updates `spec.yaml`, `instructions.md`, and optional `skills/` and `subagents/` directories under `<agent_name>/`, following the [Glean Auto Mode Agent Specification](./specification).
+- Discovers the right tools — actions and MCP servers — for what you asked the agent to do, scoped to your access permissions.
+- Pulls in relevant company-knowledge sources via `gleanSearchConfig` when the instructions imply they're needed.
+- Flags any instructed action that has no backing tool, so you can decide whether to add a tool, remove the action, or refine the prompt.
+- When you prompt against an existing agent, preserves the agent's `id` and any fields you didn't ask to change, so iterative edits don't reset state.
+
+Inputs you provide:
+
+- `agent_name` — kebab-case directory name (e.g. `daily-task-planner`). Use the same name in subsequent prompts to edit the existing agent.
+- A free-form description of what the agent should do, or what to change.
+- Optional `directory` — parent directory under which the agent folder is created or located. Defaults to the current working directory.
+
+The output is a plain directory of files. Edit them by hand or prompt the assistant again with new instructions, then commit them to Git like any other code.
+
+### Save
+
+Validates the local spec against the Glean schema and pushes a new version of the agent to Glean.
+
+What it does:
+
+- Validates `spec.yaml` and `instructions.md` against the platform schema.
+- Translates the file-system representation into the internal autonomous-agent config.
+- Publishes a new version under the agent's stable `id`. The `id` is fixed at first save and reused on every subsequent save.
+- Preserves UI-only fields (e.g. trigger schedules, channel-specific filters) on the server when they aren't part of the file-system format.
+- Saved agents appear in the Glean UI as read-only — the file system is the source of truth.
+
+Inputs you provide:
+
+- `agent_name` — the folder containing the agent.
+- Optional `directory` — parent directory under which the agent folder lives.
+
+### Run
+
+Runs the agent and returns a Glean preview URL.
+
+Two modes:
+
+1. **Preview run** — converts the local spec and runs it transiently. Use this while iterating, before you save.
+2. **Published run** — looks up the saved `id` from `spec.yaml` and runs the published version.
+
+Inputs you provide:
+
+- `agent_name` — the folder containing the agent.
+- `input` — the user query or task to send to the agent.
+- Optional `type` — `local` (preview) or `published`. Defaults to `local`.
+- Optional `eval_mode` — runs with eval-safe semantics (e.g. read-only tool variants).
+
+### Evaluate
+
+Runs an eval set against the agent and produces a structured report.
+
+What it does:
+
+- Executes the agent against an existing eval set (or one generated by the mine feature).
+- Polls each session to capture outputs and tool calls.
+- Reports per-case results covering correctness, tool selection, and drift against expectations.
+- Emits an HTML report you can open locally to step through cases.
+
+Use this to validate changes before saving, or to gate iteration in CI.
+
+### Mine
+
+Suggests candidate agents from your existing work patterns and seeds an eval set.
+
+What it does:
+
+- Surfaces candidate workflows from your recent activity surfaced via Glean search, meetings, and connected datasources.
+- Produces an agent-brief template you can hand straight to the build feature.
+- Seeds an eval set of likely user inputs the candidate agent should handle, ready for the evaluate feature.
+
+Use this to bootstrap new agents without starting from a blank prompt.
+
+## Typical workflow
+
+A full build → ship loop using only `/glean_run`:
+
+```text
+1. /glean_run mine candidate agents from my last week of work
+   → surfaces candidates and seeds an eval set for one.
+
+2. /glean_run build daily-task-planner in ./agents using that brief
+   → writes ./agents/daily-task-planner/{spec.yaml, instructions.md, ...}.
+
+3. Inspect and edit the files manually as needed.
+
+4. /glean_run run daily-task-planner with input "plan my Monday around two design reviews and a 1:1"
+   → preview-runs the local spec and returns a preview URL.
+
+5. /glean_run evaluate daily-task-planner against the seeded eval set
+   → reports pass/fail per case.
+
+6. /glean_run save daily-task-planner
+   → validates and publishes a new version.
+```
+
+Once saved, the agent is available in the Glean app like any other Auto Mode agent. To iterate, edit the local files and prompt the assistant to save again — the platform diffs and updates the published version.
+
+## Working in Git
+
+Because an agent is a directory of files, you can:
+
+- Commit it alongside your code.
+- Open PRs for changes and review them with diffs.
+- Roll back by reverting commits and prompting the assistant to save again.
+- Drive saves from CI by prompting the same features from a non-interactive runner.
+
+## See also
+
+- [Glean Auto Mode Agent Specification](./specification) — the file-system schema this plugin authors and consumes.
+- [Glean Plugin for Claude Code](../mcp/claude-code) — install the plugin in Claude Code.

docs/guides/agents/overview.mdx

@@ -44,6 +44,15 @@ Glean provides multiple ways to build AI agents that can search and reason over
   >
     Pre-built Glean tools that work across multiple agent frameworks
   </Card>
+
+  <Card
+    title="Build from AI Assistants"
+    icon="sparkles"
+    iconSet="glean"
+    href="/guides/agents/from-ai-assistants"
+  >
+    Build, save, run, evaluate, and mine Glean Auto Mode agents from inside your AI assistant
+  </Card>
 </CardGroup>
 
 ## Comparison & Decision Guide

sidebars.ts

@@ -171,6 +171,11 @@ const baseSidebars: SidebarsConfig = {
               id: 'guides/agents/nvidia-example',
               label: 'NVIDIA NIM Example',
             },
+            {
+              type: 'doc',
+              id: 'guides/agents/from-ai-assistants',
+              label: 'Build from AI Assistants',
+            },
           ],
         },
         {