Glean Agent Specification

The Glean agent specification is a human-readable file system format for defining a Glean agent — its instructions, tools, knowledge sources, skills, dependencies, and subagents — as a directory of files. It is the source format consumed by the Glean Agents MCP tools and the GitHub Action, so Glean agents can be authored and version-controlled outside the UI.

Once authored, pass the specification directory to the Glean Agents MCP tools or the GitHub Action to create or update agents in Glean.

Directory layout

A typical agent directory looks like this:

<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 as well as for all the subagents.
• skills/ is optional.
• subagents/ is optional.
• Skills should have SKILL.md file.
• Subagents can have skills, but cannot contain nested subagents.
• Published skills and agents can be referenced with dependencies.
• The directory names should use kebab-case.
• The display name of agents / subagents 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.
instructionFile	No	Path to the instructions file. Defaults to instructions.md.
model	No	Which agentic model the agent runs on and how hard it reasons.
trigger	No	How the agent is invoked. Defaults to CHAT_MESSAGE when omitted.
skills	No	List of skill directory paths to include.
subagents	No	List of subagent directory paths to include.
dependencies	No	Published skills or agents referenced by platform ID.
tools	No	Tool providers and selected tools exposed to the agent.
gleanSearchConfig	No	Company-knowledge access configuration.

Example:

id: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
name: Travel Agent
description: >
  What this agent does, in a sentence or two.
instructionFile: instructions.md

model:
  name: GPT_5_4_MS
  mode: ADVANCED
  autoUpgrade: true

trigger:
  type: CHAT_MESSAGE

skills:
  - skills/lead-qualification/
  - skills/deal-analysis/

subagents:
  - subagents/research-subagent/

dependencies:
  - type: skill
    id: f1e2d3c4b5a697887766554433221100
  - type: agent
    id: 0f1e2d3c4b5a697887766554433221100

tools:
  - toolProviderId: a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
    customisationData:
      skipConfirmation: true
    selectedTools:
      - name: create-doc
      - name: update-doc
      - name: search-doc
  - toolProviderId: 7e9f1a3b5c7d9e1f3a5b7c9d1e3f5a7b
    selectedTools:
      - name: send-email

gleanSearchConfig:
  datasourceInstances:
    - asana
    - confluence
  urls:
    - https://drive.google.com/file/d/document/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

Model

The model block configures which agentic model the agent runs on and how hard it reasons. All keys are optional.

Key	Description
name	Model Name
mode	Reasoning effort per turn. ADVANCED (default) or FAST.
autoUpgrade	Boolean. When true, Glean rolls the agent onto newer models as they ship.

mode values:

• ADVANCED — high reasoning effort. The default when mode is omitted.
• FAST — low reasoning effort. This should be used only for simple tasks.

Prefer autoUpgrade: true. Set it to false only when the agent is intentionally pinned to a named model set. autoUpgrade: false must not be used without also specifying name.

Example:

model:
  name: GPT_5_4_MS
  mode: ADVANCED
  autoUpgrade: true

Trigger

trigger controls how the top-level agent is invoked. It is optional and defaults to CHAT_MESSAGE when omitted. Subagents are never triggered directly and must not declare a trigger.

Supported type values:

type	Description
CHAT_MESSAGE	The user converses with the agent. This is the default when trigger is omitted.
INPUT_FORM	The agent receives a typed set of trigger.inputFields provided by the user at invocation time. When inputFields is empty, the agent runs without any user input.
CONTENT_TRIGGER	The agent runs in response to a document event declared in trigger.content.triggers.

Examples:

# Chat trigger (default)
trigger:
  type: CHAT_MESSAGE

# Input form trigger
trigger:
  type: INPUT_FORM
  inputFields:
    - displayName: Account Name
      description: Target account for outreach
      type: TEXT
    - displayName: Region
      type: SELECT
      defaultValue: AMER
      options:
        - value: AMER
        - value: EMEA
        - value: APJ
    - displayName: Due Date
      type: DATE
      optional: true

No-input trigger

An agent that runs without user-supplied input uses INPUT_FORM with no inputFields:

trigger:
  type: INPUT_FORM

There is no separate MANUAL trigger type.

Content-triggered agent

Content-triggered agents run in response to document events. Declare events under trigger.content.triggers. Entries in triggers are ORed; conditions within one entry are ANDed, and values within one condition are ORed.

trigger:
  type: CONTENT_TRIGGER
  content:
    triggers:
      - datasource: JIRA
        templateId: JIRA_TICKET_CREATED
        docType: task
        conditions:
          - fieldName: priority
            operator: IS_ONE_OF
            values: [High, Critical]
      - datasource: GOOGLECALENDAR
        templateId: GOOGLECALENDAR_EVENT_SCHEDULED
        docType: event
        timeOffset: 1800

Each content trigger requires datasource and templateId. docType, timeOffset, and conditions are optional. A conditions entry requires fieldName, operator, and values (except for FIELD_CHANGED). Supported operators are IS_ONE_OF, CONTAINS, IS_NOT_ONE_OF, and FIELD_CHANGED. Use TITLE or CONTENT for document title/body matching; only IS_ONE_OF and CONTAINS apply to those fields. At most 20 trigger entries are allowed.

Do not declare trigger.schedule for content-triggered agents. Runtime fields such as content, eventTime, and system.event are managed internally and must not be declared as input fields.

Scheduled execution

Chat and input-form agents can also run on a wall-clock schedule:

trigger:
  type: INPUT_FORM
  schedule:
    frequency: "0 9 * * 1-5"
    timezone: America/Los_Angeles
    startTime: "2026-03-02 09:00:00"

• frequency is a required five-field Unix cron expression. Cron descriptors and six-field expressions with seconds are not supported.
• timezone is a required IANA timezone name.
• startTime is optional and uses YYYY-MM-DD HH:MM:SS in the specified timezone.

inputFields entry schema

Each entry in trigger.inputFields accepts the following keys:

Key	Required	Type	Default	Description
displayName	Yes	string	—	Human-readable label, and the identifier referenced from instructions.md as [[displayName]]. Must be unique within the agent.
description	No	string	—	Helper text describing the field.
type	Yes	enum	—	One of TEXT, SELECT, or DATE.
optional	No	boolean	false	When true, the field may be left empty.
defaultValue	No	string	—	Pre-filled value. For SELECT, must match one of options[*].value. For DATE, use YYYY-MM-DD.
options	For SELECT	list	—	List of { value: <choice> } entries. Required when type is SELECT.

Supported type values:

type	Description
TEXT	Free-form string. Use for open-ended values the agent reads or interpolates verbatim.
SELECT	Single choice from a closed set declared via options.
DATE	Calendar date in YYYY-MM-DD format.

displayName is also the placeholder identifier used in instructions.md, for example [[Account Name]], and must be unique within the agent. For SELECT, defaultValue must match an option. For DATE, use YYYY-MM-DD.

Trigger authoring rules

• CHAT_MESSAGE must not declare inputFields.
• INPUT_FORM with fields is an input-form agent; INPUT_FORM without fields is a no-input agent.
• inputFields is valid for INPUT_FORM and CONTENT_TRIGGER.
• schedule is valid for CHAT_MESSAGE and INPUT_FORM.
• content is valid only for CONTENT_TRIGGER and requires at least one content trigger.

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: Glean internal identifier for tool provider which can also be MCP server.
• selectedTools : list of selected tools for the specified provider
• customisationData : optional provider-level configuration passed to all tools in the provider

customisationData

Provider-level customization is optional. Users should set skipConfirmation: true only when they want the provider to run without confirmation.

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. The display name on the UI is derived from the folder name, converted from kebab-case to title case.

Dependencies

Dependencies reference published skills or agents by platform ID. They are not copied into the agent directory and must not also be listed under skills/ or subagents/:

dependencies:
  - type: skill
    id: f1e2d3c4b5a697887766554433221100
  - type: agent
    id: 0f1e2d3c4b5a697887766554433221100

Use type: skill for a published skill and type: agent for a published agent that the parent can dispatch as a reusable subagent. Inline subagents listed under subagents are authored as folders in the agent directory; published agent dependencies are referenced by ID instead. Dependency IDs must be unique for each dependency type.

The top-level agent may declare both dependency types. A subagent may declare skill dependencies, but must not declare an agent dependency because nested subagents are not supported.

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 subagents or trigger; nested subagents are not supported and subagents are never invoked directly.
• A subagent may reference published skills with dependencies.
• The parent agent receives only the subagent's final result.

Subagent spec.yaml uses the same fields as the parent except for trigger and subagents.

Minimal example

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.