Databricks GenAI: Chain Components, Agent Tools and Agent Bricks

Pick chain components by tracing the data: start from what arrives (a question string, a JSON payload, a whole document, a conversation) and end at what the consumer needs (plain text, a list, a typed record). Each component exists to close one gap between the two, and they run in the order the data needs them.

A typical RAG chain therefore runs retriever → prompt template → chat model → output parser. A retriever after the model, or a template after the model, breaks the flow: the model would answer before seeing the passages. The parser at the end follows the consumer: a string parser for text shown to a person, a list parser when a downstream system loads separate entries, a JSON or structured parser when code reads named fields.

Leave out what the input does not need

Fewer components mean lower latency and fewer failure points. If the whole input — one meeting transcript, one contract — always fits in the model's context window, put it straight into the prompt template: a retriever over its chunks adds a search call and can drop relevant parts it does not return. Memory is for state across turns, not for holding a single document.

Retrieval keeps answers current; fine-tuning does not

When source documents change every few weeks, retrieval at query time reflects the latest indexed text immediately. Fine-tuning bakes in a snapshot of the documents and would have to be repeated on every change, so it is the wrong tool for freshness. Fine-tuning changes style or task behaviour; retrieval supplies facts.

Chat models take a list of role-tagged messages (system, user, assistant), so use a chat prompt template: fixed behaviour instructions go in the system message, the variable input in the user message. Foundation Model APIs chat endpoints use this chat-completions format. A string template, or a chat template that folds the instructions into the user message, still runs, but the standing instructions then reach the model as part of the user's turn rather than as system guidance.

Structured output when code reads the result

When a downstream job loads fields (category, priority, product) into a table, format failures — a sentence before the data, a misspelled key — are an output-side problem. Few-shot examples, a larger model or memory make the right format more likely; only structured output fixes it. On Foundation Model APIs, set response_format to a JSON schema (json_schema) so the reply must match named fields and types, then parse it into a typed object. json_object mode only guarantees valid JSON, not your schema.

• Optional values: a field declared as a required string must be filled with a string, so the model invents one when the value is absent. Declare a field that may be missing as a type list such as ["string", "null"] and tell the model to return null when the value is absent; it then loads as NULL.
• Unsupported keywords: Foundation Model APIs structured outputs do not support JSON Schema keywords such as pattern or anyOf; validate formats in code.

A schema guarantees shape, not truth

Structured output makes the reply parseable; it does not make the values correct. If an app must show the source URLs of documents actually used, do not ask the model to write them — it can invent plausible URLs that still pass the schema. The retriever already returns each chunk with its metadata, so carry the retrieved documents forward alongside generation and build the sources list in code from that metadata. Any fix that still has the model produce the sources, however strictly instructed, lowers the error rate without guaranteeing it.

The retriever only sees what the chain passes it, so two input situations need explicit handling: follow-up messages in a conversation, and structured fields that decide which documents are allowed.

Rewrite follow-ups into standalone queries

A follow-up such as 'how long does that take?' carries no topic on its own. The chat model may see the whole history, but if the retriever embeds only the latest message it searches for nothing useful. A history-aware query rewrite (condense) step takes the chat history plus the latest message and uses an LLM call to produce a standalone question, which replaces the raw message as the retrieval query.

Because the rewrite is an extra model call, run it only when earlier turns exist. The first message of a conversation has no history to resolve, so send it straight to retrieval; common history-aware retriever helpers behave this way when the history is empty. The rewrite step does not need the previous turn's documents or the answer model's system prompt.

Pass structured fields to the retriever as filters

When a request carries a field that decides which documents are allowed — tenant_id, plan tier, product_line — pass it to the Vector Search query as a metadata filter on the matching column. Filtering happens inside the search, so disallowed chunks never reach the prompt. Putting the field in the prompt, appending it to the query text, reranking, or scrubbing the answer afterwards all let the wrong content into the pipeline and then try to suppress it — they reduce leaks but do not eliminate them.

The filter column must exist in the index. For a Delta Sync index created with columns_to_sync limited to the ID and text, the column is missing, and the synced columns cannot be changed on an existing index: rebuild the index with the column included, then pass the filter. (Current Databricks documentation has started calling Vector Search 'AI Search'; the exam guide keeps the Vector Search name.)

Use a fixed chain when every request goes through the same steps in the same order, a tool-calling agent when requests need different sources or actions and the model must decide, and a router in front when most traffic is simple and only some needs the agent.

A fixed chain that calls every source on every request either pays for slow lookups it does not need or, if it skips a source, misses requests that need it. The reverse mistake is wrapping a fixed two-step workflow in an agent or a multi-agent supervisor, which adds latency and unpredictability for flexibility nobody uses.

For skewed workloads, the cost lives in the agent's planning loop: a large model decides what to do on every request. Instructions inside the agent ('answer FAQs with one retrieval') still run that loop, and shrinking the agent's model puts the complex cases at risk. Only a step in front of the agent keeps simple requests away from it.

An agent's model sees each tool only as a name, a description and a parameter schema, and it chooses tools by matching the request to those definitions. Write them for the model: what the tool returns, when to use it, and what each parameter expects.

• Unity Catalog function tools: the function name, the function COMMENT and each parameter's COMMENT become the tool definition. An opaque, abbreviated name with no comments gives the model no reason to connect it to a question, so it answers from its own knowledge. Only the function's own metadata becomes the tool definition; documentation kept anywhere else, such as on the underlying table, does not reach the model.
• Vector Search retriever tools: give each one a distinct tool_name and a tool_description of the content it covers. Two retrievers created with only an index name look nearly identical to the model, so it picks between them almost at random — even though each index returns good results when queried directly.
• Parameter formats: state the expected format in the parameter comment (for example an ISO date in YYYY-MM-DD form).
• Facts the model cannot know: a relative value such as 'last Tuesday' can only be resolved against today's date, so supply the current date in the system prompt.

When the wrong tool is chosen, fixes that act after the choice — reranking, more results, a larger context window, more max_tokens, retrying with the same argument — do not help. Pasting a function's code into the prompt does not either; the description is the interface.

Choose the tool type from the shape of the data and the question: exact lookups by key need a deterministic query, unstructured text needs semantic retrieval, open-ended analysis over tables needs generated SQL, and actions need a narrow tool that performs one operation.

One agent often needs several types at once — a function for the ticket status and a retriever for the runbooks. Swapping them gives near-miss tickets and missed runbooks. Turning documents into tables with extraction is a different job, not a retrieval tool.

Order tool calls by their data dependencies: a call that needs another call's output must wait for it; calls that share no inputs can run in parallel; and knowledge-gathering calls run before any irreversible action.

• Dependent chain: an email in the session yields a customer_id, the customer ID yields open orders and the latest order_id, and only then can an order-level tool run. Calling a tool before its input exists fails.
• Knowledge before action: when an action has a condition ('cancel if still within the window'), look up the policy before the side-effecting call. Checking afterwards cannot undo it.
• Parallel where independent: two store counts and a policy search share no inputs, so request them together; models that support parallel tool calls can request several in one step, and total latency becomes roughly the slowest call rather than the sum.
• Mixed plans: run the shared prerequisite first (get the customer ID), then fan out the calls that each need only that ID (tickets and invoices together), then generate.

Running everything in parallel breaks dependencies; running everything in sequence wastes time; splitting a request across turns adds a round trip for no gain.

Make the tool itself enforce the rules. An agent's tool choices come from the model, so prompt rules, tool descriptions and tool-list order influence behaviour but never guarantee it — a user who insists can still steer the model.

Preconditions inside the tool

If a refund must never be issued for an ineligible order, put the eligibility check inside issue_refund so it refuses whenever the check fails. A system prompt rule, a description saying 'use after the check' or listing the check first all raise the success rate; only enforcement in code makes it a guarantee.

Narrow tools, least privilege

A tool that runs any SQL statement, or passes any model-written request to an API, makes the security boundary depend on the model. Replace it with purpose-built tools that encode the allowed operation: a function that reads one customer's orders, and a tool that calls only the service's address-update endpoint. Table-level MODIFY grants are broader than one permitted change, and a prompt rule is not enforcement.

Unity Catalog SQL and Python functions are suited to reads and computation, not to writing Delta tables, so state changes go through the owning service's API — for example a Unity Catalog function that calls the endpoint through a Unity Catalog HTTP connection — or through a tool defined in the agent's own code.

Idempotency for retries

A timeout does not mean the action failed: the payment may have gone through, so a blind retry pays twice. Retries are still needed for genuine failures, so removing them is not the answer. Make the tool idempotent: key it on an identifier unique to each requested action and return the already-recorded result instead of acting again. The key must identify the request, not just the object acted on, so a later, separate legitimate action on the same object is still possible.

Agent Bricks builds common agents from a configuration — sources, descriptions, instructions and examples — instead of code. The exam guide names three, and each fits one shape of problem:

Product status: Databricks documentation now labels Knowledge Assistant and Supervisor Agent as legacy offerings and points new low-code work to Genie Agents and coded multi-agent work to the Agent Bricks CLI; Information Extraction has a newer version. The March 2026 exam guide still names all three, and their use-case fit is what the exam tests.

Knowledge Assistant

Knowledge sources can be files in a Unity Catalog volume, a Unity Catalog table with a file content column, or a Vector Search index, and one assistant can hold several sources. If all users may read every collection, one assistant with several sources is simpler than several assistants under a supervisor. File-based sources do not update on their own: after files are added, run a Sync (incremental — for example, newly added files are processed without reprocessing the rest); index-based sources follow their index automatically. It is the wrong shape for exact, live lookups such as one account's orders.

Information Extraction

Define a schema of output fields; the field names, types and especially descriptions are what the agent relies on to know what to extract. When a vaguely named field picks up the wrong value — for example, one of several similar dates in a document — write a description that defines it precisely and says what it is not. Run it ad hoc over a volume or a table with a text column, or deploy it as a pipeline that processes new data on a schedule. PDFs are converted first (the documented workflow uses ai_parse_document to build a text table). A hand-written ai_query prompt can do the same job, but keeps the field definitions in code that engineers maintain.

Multiagent Supervisor

The supervisor coordinates subagents such as Genie spaces, Knowledge Assistant endpoints, model serving endpoints and Unity Catalog functions. It routes using the description of each subagent, so misrouting between subagents that each work well alone is fixed with detailed, distinct descriptions. It respects end-user access: it uses only the subagents the user can access, steers away from the others, and ends the conversation only when the user can access none. Nothing runs under the creator's identity. Folding one data type into another agent (tables into a Knowledge Assistant, manuals into Genie) loses what made each agent good; the supervisor adds routing instead.

Choose Agent Bricks when the use case is standard — retrieve and answer with citations, extract fields, route between agents — and has no custom logic; choose a custom agent written in Python with Mosaic AI Agent Framework, logged with MLflow and served on Databricks when every request must run custom code, apply filters computed by internal logic, or return a fixed output contract.

Adding feedback tooling to a hand-coded chain improves how expert input is collected, but leaves the team maintaining the same pipeline code. Agent Bricks agents are steered through sources, descriptions, instructions and examples; those shape behaviour but cannot inject arbitrary code into retrieval.

Improving quality with subject-matter experts

Agent Bricks is designed so the people who know what a good answer looks like improve the agent without engineering work. In Knowledge Assistant, experts add example questions (common or poorly answered ones) and attach guidelines describing what a good answer contains; saved guidelines take effect right away. In Information Extraction, they refine field descriptions in the UI. To edit these, experts need CAN MANAGE permission on the agent itself; permission to query the agent or to read its source data is not permission to change it.

When retrieval is fine and only company conventions are missing, the fix is examples and guidelines, not fine-tuning, a bigger embedding model, rewriting the source documents or adding more of them.