Custom agents¶

Build agents for your own data, decide what each may read and who may call it, and HERC consults them in the chat once a reviewer approves them.

A custom agent is an agent your organisation defines in the app, next to the built-in agents that ship with Datahub. You set its instructions, tools, data and limits in a builder. Every change is a version, and a version answers only after review.

KindsSpecialist · Router · Reviewer

Goes liveOnly after review

Per chat turn6 consults · 10 min

Ceilings1,000 rows · 300 s

This page has two halves. The admin guide covers building, trying, reviewing and running an agent. The developer guide covers how HERC consults an agent, the router and reviewer contracts, the API, and the consult audit. A worked example at the end builds a three-agent flow.

When to choose this¶

Give HERC a specialist for your own data

A finance agent that asks one Genie space, a contracts agent that reads three tables. HERC consults it and writes one answer.
Send each question to the right agent

A router reads every question first and names the specialist that should answer it, or says none does.
Check an answer before anyone reads it

A reviewer checks a specialist's figures against its SQL and rows. HERC never presents a rejected answer as fact.
Answer from data the asker can't open

An agent can run with access of its own, for the role groups you name. That takes two approvals.

When not to reach for this

To change data. An agent HERC consults only looks things up. Tools that change data are never offered to it. For changes, use Flows or a governed workflow.
For a one-off question. Ask HERC directly. It already reaches Genie, the catalog and the warehouse through its built-in specialists.
To give someone access to a table. Grant their role group the right roles instead. An agent with its own access is a deliberate exception, and it is reviewed as one.

How it works¶

flowchart LR
    B["Builder: draft"] -->|"Submit for review"| R["Review"]
    R -->|approved| L(["Live version"])
    U["You"] -->|question| H["HERC"]
    H -->|"task + evidence"| L
    L -->|"answer + SQL + rows"| H
    H -->|"one answer"| U
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class L accent

Figure 1 — An administrator builds a draft and a reviewer approves it. From then on HERC can consult the live version in a chat turn. The agent answers HERC, not you, and HERC writes the reply.

HERC keeps the turn. It hands the agent a task, reads the answer, and writes the reply itself. The agent starts with nothing but that task: it never sees your earlier messages.
The agent only looks things up. It cannot change data, hand the conversation over, or ask you a question.
What it reads is narrowed twice. Once by its own data scope and limits, and once by whose access it runs with: yours, or its own.

Why teams reach for this

The knowledge of which space holds the margins, or which three tables make up a contract, lives in an agent your team owns. It is reviewed like any other governed asset. Every consult is audited, and you change an agent without a release.

Admin guide¶

Who does what¶

Role	What it allows	Held by
`aimodule.agents.read`	Open the Agents list, the builder and every version, read-only.	`CustomAgents.Viewer`, `CustomAgents.Editor`, `CustomAgents.Approver`, `Platform.Viewer` and up
`aimodule.agents.manage`	Create agents, edit and save drafts, Submit for review, Withdraw from review, Archive and Restore.	`CustomAgents.Editor`, `Platform.Contributor` and up
`aimodule.agents.approve`	Approve or reject a version in review. Never your own submission.	`CustomAgents.Approver`, `Platform.Approver`, and the Data Owner business role
`integrations.approve`	The second review of a version that runs with the agent's own access.	`Integrations.ReviewApprover`, and the Data Owner business role
`aimodule.agent.run`	Chat with HERC, and therefore with the agents it consults. Try needs it too.	`CustomAgents.Editor`, `AI.Editor` and `Administrator`, among others. Not `Platform.Contributor`.
`aimodule.agentconsult.read`	Read your own consult records, the same ones `aimodule.agent.run` reads. It lets an MCP connector with read-only access, such as Claude, read them too. Every group that held `aimodule.agent.run` when it was added has it. A role group you give `aimodule.agent.run` later needs it as well, or its members' read-only connectors cannot read their consults.	Every group that holds `aimodule.agent.run` (`Administrator` among them), and the `Platform` tiers
`aimodule.audit.admin`	Read every person's consult records, not only your own.	`Administrator`

Administrator holds all of these. AI.Editor and AI.Viewer do not hold the custom agent roles.

A builder on the platform tier alone cannot use Try

CustomAgents.Editor holds aimodule.agent.run, so its members can try their drafts. Platform.Contributor builds agents but does not hold it. A builder who has only that tier sees Try greyed out, with a note that names the missing right. Add them to CustomAgents.Editor, or to another group that holds it, such as AI.Editor.

Build an agent¶

Open Custom agents under AI & Agents in the admin menu, and choose New agent. The builder has one section per part of the agent. Create agent saves the first draft. After that, Save draft keeps your changes.

Section	Field	What to set
Identity	Name	What people read, at most 120 characters.
	Identifier	A lowercase letter, then 1 to 63 of a–z, 0–9, `-` or `_`. It is unique in your organisation, archived agents included, and fixed once created. A built-in agent's name is refused.
	When to use	One or two sentences. HERC and the router read it to decide when to call the agent, so write it for them. Required before you submit.
	Kind	Specialist, Router or Reviewer (see below).
Purpose	Purpose prompt	The instructions the agent follows on every question. Required before you submit.
Tools	Tools	What it may call, from the tool catalog. Tools marked Changes data are never offered when HERC consults it.
Consult	May consult	Other agents it may ask, built-in or custom. Name its reviewer here too.
Data scope	Genie spaces, Integrations, Tables	What it may read. A list left empty does not narrow.
Limits	Rows per query, Wait per query (seconds), Tool rounds	How much it may read and how long it may wait. Empty fields use the organisation's values.
Model	Provider, Model and parameters	Empty: the global default model.
Access	Runs as, Who may call it	The person asking or The agent itself.
Change summary	What changed	What this version changes, for the reviewer.

The platform wraps your purpose prompt in rules of its own. The agent answers in the asker's language, never invents data, only looks things up, says why it refuses, and lays out its evidence. You don't need to repeat those rules.

When a list the builder needs fails to load, such as the tool catalog or the Genie spaces, the builder says so and offers a retry. It never shows an empty list as if nothing exists.

The three kinds¶

Kind	What it does	How it is reached
Specialist	Answers questions in one area, with its own tools and data.	HERC consults it. You can pick it in the chat's `@` menu or name it in your message. Write a one-word name as `@Name`.
Router	Reads a question and names the specialist that should answer it.	The platform asks it before HERC runs. It is never in the `@` menu.
Reviewer	Checks a specialist's answer before HERC reads it.	The platform asks it when a specialist that lists it under May consult answers. It is never in the `@` menu.

An organisation has one live router. A second router is refused when it would go live, and when you restore one while another is live; the refusal names the live router, so archive that one first. If two routers were already live before this rule, only the first by identifier is asked.

A pick that can't be consulted. The @ menu offers only the agents you may ask. If the agent you picked can't be consulted for you when you send, the chat shows a step: "The agent you picked, 'identifier', can't be consulted for you; this answer does not come from it." HERC says so in one sentence and answers without it, as if you had picked nothing, so a name in your message or a live router can still choose who answers. That happens when the agent is no longer live, when you are not in its Who may call it, or when your role's tool policy leaves it no tool to answer with. Neither the step nor HERC says which.

Tools and consults¶

Changes data marks a tool that writes. You can select it, but HERC never offers it when it consults the agent. A version whose every tool changes data is not asked at all.
The tools an agent gets are those its version lists and those the asker's role tool policy allows.
May consult is the full list of agents this agent may ask. An agent may not consult itself, and a loop is refused when you submit: for example a consults b and b consults a.
An agent that lists no one under May consult cannot consult at all.

Data scope¶

List	Narrows	Example
Genie spaces	The Genie spaces it may ask.	Finance
Integrations	The connections whose data it may read.	Databricks production
Tables	Tables as `catalog.schema.table`, with `*` for any one part.	`finance.reporting.`, `finance..*`

An empty list does not narrow. An agent with no scope at all reads whatever the access it runs with allows.
Every list applies to every read. A Genie space is checked against the spaces, against the connection it reads from, and against the tables it declares. A SQL query is checked against its connection and every table it names.
A read that cannot be checked is refused. Once you set Tables, the agent's SQL has to name each table in full (catalog.schema.table). SQL that does not parse, a file path, or a Genie space Datahub has not synced is refused.
Listings leave out what is outside. A table listing or a semantic model listing shows only the tables in scope, and says that it is narrowed.
Scopes stack. When an agent consults another, each read has to pass both scopes. A reviewer reads only what its own scope and the scope of the specialist it checks both allow.

A refused read reaches no warehouse. The agent says which list refused it, so HERC can tell you why.

Limits¶

Field	Default	Range	Applies to
Rows per query	The organisation's row limits (Genie 50, SQL 50)	1 – 1,000	Genie answers and SQL results alike.
Wait per query (seconds)	The organisation's waits (Genie 90 s, Databricks SQL 65 s)	1 – 300	The Genie wait and the Databricks SQL wait alike.
Tool rounds	4	1 – 20	How many rounds of tool calls it may make on one task.

An agent's value replaces the organisation's. It is not "the lower of the two". An agent set to 500 rows gets 500 rows, even when the organisation's limit is 50.
Each source keeps its own minimum. Databricks SQL waits at least 20 seconds, so a wait of 5 seconds becomes 20 seconds for SQL and stays 5 seconds for Genie.
When agents consult each other, the tightest value wins. A limit no agent in the chain sets is the organisation's.
The organisation's values are under Result limits.

A chat turn is at most 10 minutes

Everything in a turn shares one 10-minute budget: the router, every specialist, every reviewer and HERC's own reply. A wait of 300 seconds with 4 tool rounds can use up a turn on its own. Set the wait to what the query really needs, and keep Tool rounds low on agents with long waits.

Model¶

Leave Provider empty to use the global default model. Pick a provider and you must also pick a model. The parameters (Temperature, Top P, Max tokens, Frequency penalty, Presence penalty) are optional. The model is part of the version, so a model change goes live through review like any other change. Model settings shows each custom agent's live model, read-only.

Try a draft¶

Try, in the builder's header, opens a Test run in the side panel. Type a question (at most 4,000 characters) and choose Run test. You see what the draft does as it does it: the tools it called, the SQL it ran with the number of rows it found, and its answer.

The saved draft, nothing else. With unsaved changes, save first. A version in review can't be tried: Withdraw from review to change it and try it again. Try never asks the live version.
Always with your own access. Even a draft set to The agent itself runs with your rights. A version nobody approved never runs with access of its own. Within your rights, the draft's own Data scope and Limits hold.
Not saved to any conversation. The question and answer are not stored as a chat. AI usage and guardrails count as usual, and the run is written to the consult audit with you as the person who asked.
Two things a test run does not do yet. A reviewer in the draft's May consult list does not check its answer. A draft router or reviewer is asked your question as if it were a specialist.

From draft to live¶

stateDiagram-v2
    state "In review" as InReview
    state "Data owner review" as DataOwner
    [*] --> Draft: Create agent
    Draft --> InReview: Submit for review
    InReview --> Draft: Withdraw from review, or rejected
    InReview --> Live: Agent approver approves (runs as the asker)
    InReview --> DataOwner: Agent approver approves (runs as itself)
    DataOwner --> Draft: Withdraw from review, or rejected
    DataOwner --> Live: Data owner approves
    Live --> Superseded: Next version approved
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class Live accent

Figure 2 — The life of a version. Only an approval puts a version live. A version that runs with the agent's own access needs a second approval from a data owner.

Create agent saves version 1 as a Draft. Nothing is live yet.
Submit for review validates the draft and sends it to a reviewer's task list. It needs When to use and a Purpose prompt. It refuses tools that are not in the catalog, agents that don't exist, a consult loop, and Genie spaces, integrations or role groups that no longer exist. It also refuses a model provider the platform does not know, a model name without a provider, and a draft that changes nothing against the live version. While a version waits, nobody can change it.
The reviewer opens the task, reads the version next to the live one with each change marked, and approves or rejects it. The person who submitted a version never approves it.
On approval the version is checked again, because a tool or a consulted agent may have gone in the meantime. Then it goes Live, and the version that was live before it is kept as Superseded.

Editing a live agent starts a new draft. Saving makes your changes the next draft, and the live version keeps answering until that draft is approved. Only one version of an agent is in review at a time.

Activate is shown greyed out. Approval is the only way a version goes live.
Archive takes an agent out of use and withdraws a review in progress. Before you confirm, it names the agents that consult this one: they lose it as a consult target. Restore brings it back. An agent is never deleted.
A reviewer agent that a live specialist relies on cannot be archived, and a version that makes it another kind is not approved. The refusal names the specialists.
Open any version from the history to read it as it was. The link carries ?version= and opens read-only.

Every step is on the agent's audit trail: created, updated, version forked, submitted, withdrawn, rejected, activated, archived, restored, and for an agent with its own access, the first approval.

Agents with their own access¶

By default an agent runs as The person asking. It sees only what they may see, and the rows HERC shows are rows they could have read themselves.

Set Runs as to The agent itself when people should get answers from data they can't open themselves. For example, sales managers can see margins per region without access to the ledger tables.

flowchart LR
    S["Save with 'The agent itself'"] --> A["Own account + role group 'Agent: identifier', no roles"]
    A --> G["A role-group admin grants roles"]
    G --> R1["Agent approver approves"]
    R1 --> R2["Data owner approves"]
    R2 --> L(["Live: account switched on"])
    classDef accent fill:#ff8400,stroke:#e67700,color:#ffffff,font-weight:600;
    class L accent

Figure 3 — Setting up an agent with its own access. The agent can read nothing until someone who manages role groups grants its group roles, and it answers only after two approvals.

Its own account. The first save as The agent itself creates an account for the agent and one role group for it, shown as Agent: followed by the identifier. The account can't sign in and is never synced from Entra.
Its roles come from that group only, and it starts with none. Until someone grants its group roles, the agent can read nothing, and the builder says so. Someone who may manage role groups grants them under Role Groups. Before they save, the group's page shows what the save would do: the roles the agent gains and loses, the ones Datahub adds because a chosen role needs them, and every role it would then hold. While the group is switched off (the agent is archived, or its live version runs as the asker), the page says its roles reach nobody for now. The builder and the version view list the roles the agent acts with. While a live agent with its own access has a group with no roles, whoever manages role groups is told, on the Users & Access page and in their notifications.
Who may call it. Name at least one role group. A business role is offered too, shown as the role's name followed by (business role): naming it lets everyone who holds that business role call the agent. Only those members and holders are offered the agent: in HERC's list, in the router's candidates, in the @ menu, and in a suggested name. Anyone else who asks for it is refused, and HERC names the groups that would let them in and, when another agent asked for it on their behalf, which agent. An empty list means nobody, not everybody.
What it exposes. The builder names the groups and the data in one sentence: members of those groups can see data from that scope through this agent, including data they can't open themselves. The reviewers read the same sentence on the version.
Two approvals. "It goes live only after two approvals: the agent approver's, then the data owner's." The data owner is someone who may approve integrations (integrations.approve), so CustomAgents.Approver alone can give only the first approval. The agent approver who gave the first yes can't give the second, unless nobody else may. A rejection at either review takes the version back to draft, and a resubmit starts at the agent approver again. Every version of such an agent takes both reviews, a prompt-only edit too.
The account follows the live version. It is switched on when a version with its own access goes live, and off when a version that runs as the asker goes live. Archiving the agent archives the account and switches its group off. Restore brings both back.
Databricks only through a service principal. The agent's account can't sign in to Databricks as a person. A connection that uses each person's own Databricks sign-in refuses it. A connection that signs in as a service principal works.
Still the asker's tool policy. The tools offered are those the asker's role's tool policy allows, and none that change data.

Check the roles before you approve

Today the roles on the agent's group are a role-group change. They take effect at once and do not send the agent back to review. Reviewers should read the roles the version view lists, and role-group admins should treat that group as part of the agent.

Developer guide¶

How HERC consults an agent¶

HERC, and any agent with a non-empty May consult list, gets a consult_agent tool:

consult_agent(agent, task, evidence=None)

Fresh context. The consulted agent gets its purpose prompt, the platform's rules, the task, and the evidence the caller hands it. Evidence is cut at 20,000 characters. It never gets the chat history. It is told its answer goes to an agent, not a person.
Call and return. The result comes back to the caller as a tool result: the answer (at most 8,000 characters) and the evidence the agent gathered. That evidence holds the tools it called, the SQL it ran, the columns, and the rows, cut to the row limit with the true row count kept. The caller carries on and writes its own answer.
Read-only. Tools that change data, hand-over tools (delegate_to_*) and request_user_input are withheld in a consult.
Who HERC can consult. Its built-in specialists, and the live custom specialists the asker may ask. HERC's prompt lists up to 40 of them, by identifier, name and When to use.
Who a custom agent can consult. Only the agents its version lists under May consult.

Consult limits¶

Limit	Value
Depth	2 levels below the agent that started the turn. A third level is refused.
Consults per turn	6, nested ones, the router and reviewers included. The 7th is refused.
Turn budget	10 minutes. A consult starts only while 45 seconds are left, and it ends 30 seconds before the turn does, so the caller can still answer.
Answer size	8,000 characters back to the caller.
Evidence handed in	20,000 characters.

A refusal is a tool result with a code, never an error, and the caller relays the reason:

Code	Meaning
`consult_not_allowed`	The agent is not on the caller's May consult list.
`consult_depth_exceeded`	A third level below the agent that started the turn.
`consult_limit_reached`	The 7th consult of the turn.
`consult_unavailable`	The consult could not start, for example outside a chat turn.
`consult_agent_unknown`	Your organisation has no agent by that name.
`consult_agent_archived`	The agent is archived.
`consult_agent_not_live`	The agent has no live version yet.
`consult_agent_live_next_turn`	It went live while this turn ran. Ask again.
`consult_agents_unavailable`	The custom agents could not be read.
`consult_invoker_not_allowed`	The asker is not in any role group under Who may call it.
`consult_agent_principal_unavailable`	The agent's own account can't act: archived, locked, switched off, or not created yet.
`consult_read_only`	Every tool the agent has changes data.
`consult_tools_withheld`	The asker's tool policy withholds every tool the agent would use.
`consult_budget_exhausted`	Too little of the turn is left.
`consult_run_as_unsupported`	A draft could not be tried with your rights.
`consult_bound_reviewer`	A specialist asked its own reviewer. The platform asks the reviewer once the specialist has answered.

The router contract¶

When a router is live, the platform consults it on every turn before HERC runs. It skips the router when you picked an agent in the @ menu, and when your message answers a question a specialist asked you. The router gets:

a task with your message, and your previous message for context, so a short follow-up reads as what it follows up on. Each is cut at 2,000 characters.
evidence listing the candidates, one line each: identifier, name, and the first 300 characters of When to use. The candidates are exactly the live specialists you may ask.

It must reply with one JSON object and nothing else:

{"type": "margin question", "domain": "finance", "agent": "finance"}

Field	Rule
`type`	What kind of question it is, in a few words. Required, at most 60 characters.
`domain`	The business domain, or `null`. At most 80 characters.
`agent`	A candidate's identifier, or `null` when none covers the question.

A valid answer is passed to HERC, which consults the named specialist first. With null, HERC answers with its own tools, or goes back to the agent an earlier answer came from. If the router answers anything else, names an agent that is not a candidate, is refused or fails, HERC chooses for itself, and the router's step in the chat says why. While a router is live, naming an agent in your message does not reach it directly: the router reads the name.

The reviewer contract¶

A specialist's reviewer is the first live Reviewer, by identifier, on its May consult list. When a consult of that specialist answers, the platform consults the reviewer as the specialist, within the specialist's data scope and its own. The reviewer gets your question, the task, the specialist's answer, and its evidence. It must reply with one JSON object:

{"verdict": "rejected", "reasons": ["Q3 total does not match the sum of the regions"]}

Verdict	What HERC is told
`approved`	Answer from it, and say a reviewer checked it.
`rejected`	Do not present the answer or its figures as fact. Give the reasons, and say what an answer that holds would need.
Unreadable, refused or failed	Not checked: present the answer as unchecked. Never read as approved.

Up to 5 reasons are kept. If the specialist lists a reviewer that is not live (archived or not approved yet) and no live one, its answers are marked Not checked too.

API and MCP tools¶

The builder uses the REST API under /aimodule/agent-definitions. Your own AI client can use the MCP tools.

Route	Role	MCP tool
`GET /aimodule/agent-definitions`	`aimodule.agents.read`	`list_custom_agents`
`GET …/{agent_id}`	`aimodule.agents.read`	`get_custom_agent`
`GET …/{agent_id}/versions`, `…/versions/{version_id}`	`aimodule.agents.read`	`list_custom_agent_versions`, `get_custom_agent_version`
`GET …/options`, `…/options/pick-lists`	`.read`, `.manage`	`get_custom_agent_builder_options`, `get_custom_agent_pick_lists`
`GET /aimodule/settings/model-config/agents`	`aimodule.providerkeys.read`	`list_built_in_agents` (the built-in agents, by name)
`POST /aimodule/agent-definitions`	`aimodule.agents.manage`	`create_custom_agent`
`PUT …/{agent_id}/draft`	`aimodule.agents.manage`	`update_custom_agent_draft` (`clear_fields` sets a limit or the model back to the default)
`POST …/{agent_id}/submit`, `…/withdraw`	`aimodule.agents.manage`	`submit_custom_agent_for_review`, `withdraw_custom_agent_review`
`POST …/{agent_id}/archive`, `…/restore`	`aimodule.agents.manage`	`archive_custom_agent`, `restore_custom_agent`
`POST …/{agent_id}/draft/try`	`.manage` and `aimodule.agent.run`	none

Approval has no route or tool of its own. A reviewer decides in their task, and an AI client can't approve an agent.

The consult audit¶

Every consult, refused or run, writes one record to the AI audit log:

Who asked: always the person, by id and name, even when the agent ran with its own access.
Which agents: the calling agent, the consulted agent, and the exact version that answered.
How deep, and how it ended: the depth, the outcome, the refusal code or error, the tools called, and how long it took.
Why it did not answer: for a refusal or failure, a reason in plain words and the facts behind it in params, such as the seconds left, how deep consults may nest, or the tools the policy withheld.
Whose access ran: the person's or the agent's own, and the agent's account when it was its own.
Where it happened: the conversation, and, when one agent consulted another, the consult that led to it (parent_consult_id), so a chain can be followed back to the person who asked.
Ids: an id for the consult and one for the run. The chat's step names both, so you, or HERC later in the same conversation, can find the record behind a step.

The task text is never stored, only a SHA-256 fingerprint of it. A tool call made by an agent with its own access is also recorded in the MCP audit log, naming both the person and the agent's account.

Read it with	Who sees what
`GET /aimodule/agent-consults`, `GET /aimodule/agent-consults/{consult_id}`	With `aimodule.agent.run` or `aimodule.agentconsult.read`, your own records. With `aimodule.audit.admin`, everyone's.
MCP `list_agent_consults`, `get_agent_consult`	The same. A connector with read-only access, such as Claude, reads your own records. It never reads everyone's, even for an administrator.
Asking HERC "which agents did you consult, and why was one refused?"	Your own.

Filters: user_id, agent, consulted_version_id, outcome, code, run_id, date_from, date_to. There is no screen for these records yet.

Worked example: classify, answer, check¶

A finance team wants three agents:

A classifier that reads each question and sends finance questions to the finance agent.
A finance agent that answers from one Genie space, with room for 500 rows and a 180-second wait.
A check agent that checks every finance answer before anyone reads it.

	`classifier`	`finance`	`finance-check`
Kind	Router	Specialist	Reviewer
When to use	Reads each question and picks the agent that should answer it.	Revenue, cost and margin per period, region and product, from the Finance Genie space.	Checks finance answers against their SQL and rows.
Purpose prompt	Classify the question. Choose `finance` for revenue, cost, margin or budget questions. Otherwise choose no agent.	You answer finance questions from the Finance Genie space. Always state the period and the currency. Say when a figure is an estimate.	Check that every figure in the answer follows from the rows and the SQL. Reject totals that don't add up, a missing period, or a mixed currency.
Tools	none	`list_genie_spaces`, `ask_databricks_genie_new`, `ask_databricks_genie_followup`	none
May consult	none	`finance-check`	none
Data scope	none	Genie spaces: Finance	Genie spaces: Finance
Limits	defaults	Rows per query 500, Wait per query 180, Tool rounds 2	defaults, Tool rounds 1
Runs as	The person asking	The person asking	The person asking

Build them in this order, because an agent can only consult agents that exist:

finance-check. Choose New agent, set the kind to Reviewer, and fill in the fields above. Create agent. Then Try it with a sample answer to see that it replies with a verdict.
finance. Set the kind to Specialist. Under Tools, pick the three Genie tools. Under May consult, pick finance-check (custom). Under Data scope, pick the Finance space. Under Limits, set 500, 180 and 2. Create agent, then Try it with "What was the gross margin per region in Q3?" The test run shows the Genie question it asked and the number of rows it got back.
classifier. Set the kind to Router. No tools and no consults: the platform hands it the candidates.
Submit for review, each with a What changed line. An agent approver approves each one in Tasks. Approve finance-check no later than finance: until the reviewer is live, the finance agent's answers come back Not checked.

sequenceDiagram
    autonumber
    participant U as You
    participant H as HERC
    participant C as classifier
    participant F as finance
    participant K as finance-check
    U->>H: Gross margin per region in Q3?
    H->>C: Message + previous message + candidates
    C-->>H: type, domain finance, agent finance
    H->>F: Task
    F->>F: Genie, up to 500 rows, waits up to 180 s
    F-->>H: Answer + SQL + rows
    H->>K: Question, task, answer, evidence
    K-->>H: approved, or rejected with reasons
    H-->>U: One answer, marked as checked

Figure 4 — One chat turn through the three agents. The classifier, the finance agent and the check agent each count as one of the turn's 6 consults.

The turn holds three consults, all one level below HERC. HERC asks the router, the router names finance, and HERC consults it. When finance answers, the platform consults finance-check before HERC reads the answer. In the chat you see three steps, marked Router, the specialist, and Reviewer, and the specialist's step says who checked its answer.

Why the finance agent gets 2 tool rounds

Each Genie question may wait up to 180 seconds. Two rounds can take 6 minutes, which leaves time for the check agent and HERC's reply within the 10-minute turn. With 4 rounds the specialist could use the whole turn. The check agent would then be refused for lack of time, and the answer would come back Not checked.

Variant: finance answers for people without ledger access

Set finance to Runs as: The agent itself, and under Who may call it name the group of people who should get these answers, for example a sales managers group. Save it. Ask someone who manages role groups to grant the group Agent: finance the roles that read the Finance space's connection. That connection must sign in to Databricks as a service principal. Submit. An agent approver approves, then a data owner. From then on, only members of the named group are offered finance, and they see figures from the Finance space they could not open themselves. The check agent still reads only what both scopes allow, and every consult record names both the person and the agent's account.

Limitations¶

Limitation	What to do
The chat turn is at most 10 minutes, shared by every agent in it.	Keep waits and Tool rounds to what a question needs.
Consulted agents only look things up.	Changes go through Flows or a governed workflow.
One live router per organisation. A second is refused at go-live and at restore. With two live from before that rule, only the first by identifier is asked.	Archive the extra routers.
A built-in agent can't consult a custom agent by handing the conversation over. HERC consults custom agents.	Ask HERC, or pick the agent in the `@` menu.
Roles on an agent's own role group are not part of its review. A change takes effect at once.	Reviewers check the roles the version view lists. Role-group admins treat the group as part of the agent.
Who may call it offers a business role only once it has its own role group, which it gets the first time it is given a domain.	Give the business role a domain, or name an ordinary role group whose members hold that business role.
Data scope does not narrow catalog or metric lookups.	Narrow those through the access the agent runs with.
A Wait per query longer than the organisation's Databricks SQL wait does not yet lengthen Databricks SQL: the query stops at about the organisation's wait. Genie waits, and shorter waits, work as set.	Use Genie for long questions, or raise the organisation's Databricks SQL wait.
Archive and restore are not available as MCP tools.	Use the builder.
External MCP clients can't call a custom agent yet.	Ask in the app's chat, where HERC consults it.
There is no screen for consult records.	Read them through the API, the MCP tools or HERC.

Audit & compliance¶

Question	Answer
Can an agent go live without review?	No. Approval is the only way, and the submitter never approves their own version.
Can an agent change data when HERC consults it?	No. Tools that change data are withheld in every consult and every test run.
Who is recorded when an agent runs with its own access?	Both: the person who asked as the actor, and the agent's account as the principal.
Is the question text stored in the consult audit?	No. Only a SHA-256 fingerprint of the task.
Can a person reach an agent with its own access when they are not in Who may call it?	No. They are not offered it, and a direct request is refused and recorded.
Can an agent read outside its data scope?	No. The read is refused before it reaches any warehouse, and the agent says which list refused it.
Who approves an agent that exposes data to people without access?	An agent approver, then a data owner, and they are two different people unless only one person may approve integrations.
What happens to an archived agent's account?	It is archived with the agent and its role group is switched off. Restore brings both back.
Who changed an agent's roles, and to what?	Every save on its role group that changes them is recorded in the audit log against the agent (`agent_principal`, `roles_changed`), with who saved it, what was added and removed, and every role the agent holds afterwards. To know what the agent could do on a given day, read its last `roles_changed` row before that day together with its last `switched_on`, `switched_off`, `archived` or `restored` row: while the group is switched off, its roles reach nobody.

Troubleshooting¶

Symptom	Cause	Fix
Try is greyed out, with a note about the right to run agents.	You hold `aimodule.agents.manage` but not `aimodule.agent.run`.	Ask an administrator to add you to a group that holds it, such as `CustomAgents.Editor` or `AI.Editor`.
Submit for review says "This makes a consult loop".	Two agents consult each other, directly or through others.	Remove one link from May consult.
Submit for review says the draft changes nothing against the live version.	The draft is the same as the live version.	Change the draft first, or leave the live version running as it is.
A version is refused at approval or at Restore: another agent is the organisation's live router.	A second router would be live.	Archive the live router named in the refusal, then try again.
The agent answers, but HERC says it was not checked.	Its reviewer is not live, ran out of time, or gave an unreadable verdict.	Get the reviewer approved. Lower the specialist's wait or Tool rounds. Tighten the reviewer's purpose prompt so it replies with JSON only.
HERC says the agent was not consulted: too little time was left.	Earlier steps used up the 10-minute turn.	Lower waits and Tool rounds, or ask a narrower question.
HERC says "The agent you picked … can't be consulted for you".	The agent is not live (archived, or not approved yet), you are not in Who may call it, or your role's tool policy leaves it no tool to answer with. HERC does not say which.	Get its version approved or Restore it, ask to be added to a role group or business role under Who may call it, or ask an administrator to check your role's tool policy. Meanwhile HERC answers without it.
A person can't find the agent in the `@` menu.	It runs as itself and they are not in Who may call it, or it has no live version.	Add their role group and submit, or get the version approved.
An agent with its own access reads nothing.	Its role group Agent: followed by its identifier has no roles yet.	Ask someone who manages role groups to grant the roles it needs.
Its Databricks reads are refused with a note about a service principal.	The connection uses each person's own Databricks sign-in.	Point the agent at a connection that signs in as a service principal.
A table read is refused as outside the scope.	Tables is set and the SQL names a table outside it, or not in full `catalog.schema.table`.	Widen Tables, or tell the agent in its purpose prompt to name tables in full.
Archive is refused for a reviewer.	A live specialist relies on it.	Archive the specialist first, or approve a version of it that no longer lists the reviewer.