Skip to main content
Agents are the entry point for AI and 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)
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 names and glob patterns. 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.

​
Agent Routing

Honeydew can route each new conversation to the agent that fits its first question. The Slack and Teams apps route when no agent is configured. Your own application routes with the agents_for_question API, as shown in the embedded UI guide. The router matches the question against the agents the user can access, skipping agents with validation errors:
  • Single match: the conversation starts with that agent.
  • Several matches: the user picks one. The agents are ranked most relevant first.
  • No match: no conversation starts, and the user is told that no agent fits the question.
When only one agent qualifies, every question routes to it. Routing picks the agent of a new conversation only; follow-up questions stay with that agent.

​
What the Router Considers

The router uses an LLM to match the question against each agent. For each agent, it looks at:
  • description and AI context — the primary signals. The description frontmatter field and the agent’s AI context (the Markdown body) are equally weighted: both should precisely describe what data, topics, or business area the agent covers, from the user’s perspective.
  • sample_questions — example questions the agent is designed to answer. These are the most direct routing hint: the closer a user’s question resembles a sample question, the more confidently the router picks that agent.
  • domain — the domain the agent is connected to, which provides additional topical scope.
The router matches semantically — an agent with a vague description and no sample questions will match inconsistently, even if the domain name is relevant.

​
Writing Routing Metadata

An agent file also needs type, name and domain (YAML Schema); the routing fields are:
  • Write description from the user’s perspective, not the data model’s. “Analyzes sales pipeline” is more useful than “accesses the orders domain.”
  • Make sample_questions representative of what real users will ask, not just technically valid queries.
  • When two agents cover adjacent topics, make their descriptions distinct enough to avoid ambiguous routing. The router offers both as choices when it cannot tell them apart.

​
YAML Schema

Each agent is defined by a Markdown file with YAML frontmatter in Git.
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)
  • 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-5). 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: