gleanwork · rishabh-chawla-glean · May 28, 2026
@@ -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.
@@ -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

@@ -0,0 +1,170 @@
+---
+title: Glean Auto Mode Agent Specification
+description: A human-readable file system format for defining Glean Auto Mode agents.
+---
+
+# Glean Auto Mode Agent Specification
+
+The Glean Auto Mode agent specification is a human-readable file system format for defining a Glean Auto Mode agent — its instructions, tools, knowledge sources, skills, and subagents — as a directory of files. It is the source format consumed by the Glean Agents MCP tools and the GitHub Action, so agents can be authored and version-controlled outside the Glean UI.
+
+## Directory layout
+
+A typical agent directory looks like this:
+
+```text
+<agent-name>/
+├── spec.yaml
+├── instructions.md
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md
+└── subagents/
+    └── <subagent-name>/
+        ├── spec.yaml
+        ├── instructions.md
+        └── skills/
+```
+
+Notes:
+
+- `spec.yaml` and `instructions.md` are required for the root agent.
+- `skills/` is optional.
+- `subagents/` is optional.
+- Skills do not have their own `spec.yaml`.
+- Subagents can have skills, but cannot contain nested subagents.
+- The directory names should use kebab-case.
+- The display name shown to users is defined in `spec.yaml`.
+
+## Required files
+### `spec.yaml`
+
+`spec.yaml` is the main configuration file for the agent.
+
+Common top-level fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `id` | Yes | Stable unique agent identifier. Do not change it after creation. |
+| `name` | Yes | Human-readable agent name shown to users. |
+| `description` | Yes | Short description of what the agent does. |
+| `instruction_file` | No | Path to the instructions file. Defaults to `instructions.md`. |
+| `skills` | No | List of skill directory paths to include. |
+| `subagents` | No | List of subagent directory paths to include. |
+| `tools` | No | Tool providers and selected tools exposed to the agent. |
+| `gleanSearchConfig` | No | Company-knowledge access configuration. |
+
+
+Example:
+
+```yaml
+id: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
+name: Travel Agent
+description: >
+  What this agent does, in a sentence or two.
+instruction_file: instructions.md
+
+skills:
+  - skills/lead-qualification/
+  - skills/deal-analysis/
+
+subagents:
+  - subagents/research-subagent/
+
+tools:
+  - toolProviderId: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
+    selectedTools:
+      - name: create-doc
+        customisationData:
+          skipUserInteraction: true
+      - name: update-doc
+      - name: search-doc
+  - toolProviderId: 7e9f1a3b5c7d9e1f3a5b7c9d1e3f5a7b
+    selectedTools:
+      - name: send-email
+
+gleanSearchConfig:
+  datasourceInstances:
+    - asana
+    - confluence
+  urls:
+    - https://drive.google.com/file/d/1F2MN8DfBTOEFxFzS3BA6OU7eQWpbEm3MLtpRtpDh0/view
+```
+
+### `instructions.md`
+
+`instructions.md` contains the agent's system prompt.
+
+Guidelines:
+
+- Use Markdown for structured workflows.
+- Start with a clear role statement.
+- Keep instructions precise and complete.
+- Preserve exact step order when the workflow is rigid.
+- Do not repeat tool descriptions unnecessarily.
+
+
+## Optional configuration
+
+### Tools
+
+Tools are optional. Add them when the agent needs to perform actions outside its instructions and built-in knowledge, such as search, email, or API calls. If you declare tools, make sure every instructed external action has a corresponding tool.
+
+Each tool entry includes:
+
+- `toolProviderId`: this is the id of the MCP server / Action Pack
+- `selectedTools` : list of actions
+
+### `gleanSearchConfig`
+
+`gleanSearchConfig` controls company-knowledge access.
+
+Supported fields:
+
+| Field | Description |
+| --- | --- |
+| `datasourceInstances` | Restrict search to specific datasource instances. |
+| `urls` | Restrict search to specific documents or folders. Folder URLs apply transitively to contained documents. |
+
+
+Valid states:
+
+| State | Meaning |
+| --- | --- |
+| Omitted | No company knowledge access. |
+| `{}` | Unrestricted company knowledge access for the invoking user. |
+| Populated | Restricted to the listed datasources and/or URLs. |
+
+### Skills
+
+A skill defines:
+
+- what the skill does
+- when to use it
+- how it works
+
+Each skill directory must contain a `SKILL.md` file.
+
+### Subagents
+
+Subagents are optional isolated execution units.
+
+Rules:
+
+- A subagent has its own `spec.yaml` and `instructions.md`.
+- A subagent may have its own `skills/` directory.
+- A subagent must not declare its own `subagents` field.
+- Subagents cannot be nested.
+- The parent agent receives only the subagent's final result.
+
+## Minimal example
+
+```text
+my-agent/
+├── spec.yaml
+├── instructions.md
+└── skills/
+    └── domain-knowledge/
+        └── SKILL.md
+```
+
+This is a minimal useful agent with one skill. More advanced agents can also include tools, knowledge restrictions, and subagents.
@@ -171,6 +171,16 @@ const baseSidebars: SidebarsConfig = {
               id: 'guides/agents/nvidia-example',
               label: 'NVIDIA NIM Example',
             },
+            {
+              type: 'doc',
+              id: 'guides/agents/specification',
+              label: 'Auto Agent Specification',
+            },
+            {
+              type: 'doc',
+              id: 'guides/agents/from-ai-assistants',
+              label: 'Build from AI Assistants',
+            },
           ],
         },
         {