> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

Agents are the entry point for AI and
[deep analysis](/docs/integration/context-layer/deep-analysis) in Honeydew.
Each agent defines which domain the AI can access and which context
it loads into analysis sessions.

## Creating an Agent

Agents can be created in a few ways:

* **Honeydew Studio** — use the agent builder in the UI
* **Git repository** — commit a file to the `ai/agents/` directory in your workspace
* **Coding agent** — use a coding agent connected via MCP to create and manage agents
  (see [MCP agent tools](/docs/integration/mcp#agents))

```markdown theme={null}
---
type: agent
name: growth-analyst
display_name: Growth Analysis Specialist
description: Analyzes user growth, acquisition, and activation metrics
welcome_message: |
  Ask me about user growth, acquisition, and activation.
sample_questions: []  # auto-generated in Honeydew Studio if empty
domain: sales
context:
  - general/*
  - skills/analysis/*
  - knowledge/marketing/*
  - skills/reporting/growth-dashboard
owner: growth-team
---

This agent specializes in growth analysis for the sales domain.
Use it to investigate user acquisition funnels, activation rates,
and cohort-level retention trends.
```

The Markdown body after the frontmatter is the agent's AI context.
It is injected into the prompt before every analysis session,
giving the AI additional guidance specific to this agent —
its purpose, analytical focus, or any constraints on how it should respond.

## Context References

The `context` field accepts
[context item](/docs/integration/context-layer/context-management) names
and glob patterns.

| Pattern                           | Matches                                     |
| --------------------------------- | ------------------------------------------- |
| `skills/analysis/funnel-analysis` | Exact item by full name                     |
| `skills/analysis/*`               | All items directly under `skills/analysis/` |
| `knowledge/**`                    | All items with the `knowledge/` prefix      |
| `*`                               | All context items                           |

Items matching multiple patterns are deduplicated automatically.

## Access Control

Users are granted access to specific agents.
Access to an agent grants access to the underlying domain
and all referenced context items.

The same domain can be exposed through multiple agents with different
context sets — for example, a `finance-analyst` agent and a
`sales-analyst` agent can both access the `revenue` domain while
loading different context.

## YAML Schema

Each agent is defined by a Markdown file with YAML frontmatter in Git.

```yaml theme={null}
type: agent                           # required
name: <name>                          # required
display_name: <display name>          # optional
description: <description>           # optional
welcome_message: |                    # optional
  <welcome message>
sample_questions:                     # optional; auto-generated in Honeydew Studio if empty
  - <question>
domain: <domain name>                 # required
context:                              # optional
  - <context item name or glob pattern>
owner: <owner>                        # optional
model: <model id>                     # optional
```

Fields:

* `type`: Required. Must be `agent`
* `name`: Required. Unique identifier for the agent within the workspace
* `display_name`: Human-readable name shown in the UI
* `description`: What this agent does
* `welcome_message`: Text shown to users at the start of a session
* `sample_questions`: Suggested questions; auto-generated in Honeydew Studio if empty
* `domain`: Required. The domain the agent has access to
* `context`: List of context item names or glob patterns (see
  [Context References](#context-references))
* `owner`: Team or user responsible for this agent
* `model`: Overrides the default LLM for deep analysis sessions started by this agent.
  Accepts a Honeydew model ID or a provider-specific model ID (e.g., `claude-sonnet-4-6`).
  Both forms resolve to the same model, and only the models listed below are accepted —
  a model that is not suitable for deep analysis is rejected in either form.
  When not set, the workspace default model is used.
  The model must be supported by the workspace's LLM provider.

  Supported Honeydew model IDs:

  | Model ID                | Display name         |
  | ----------------------- | -------------------- |
  | `CLAUDE_4_6_SONNET`     | Claude Sonnet 4.6    |
  | `CLAUDE_4_8_OPUS`       | Claude Opus 4.8      |
  | `CLAUDE_5_SONNET`       | Claude Sonnet 5      |
  | `CLAUDE_5_OPUS`         | Claude Opus 5        |
  | `OPEN_AI_GPT_5_4`       | OpenAI GPT-5.4       |
  | `OPEN_AI_GPT_5_5`       | OpenAI GPT-5.5       |
  | `OPEN_AI_GPT_5_6_SOL`   | OpenAI GPT-5.6 Sol   |
  | `OPEN_AI_GPT_5_6_TERRA` | OpenAI GPT-5.6 Terra |
  | `GEMINI_3_1_PRO`        | Gemini 3.1 Pro       |