Agent Bricks Supervisor Agent and When to Build a Custom Agent

1.Supervisor Agent: one endpoint over many specialists

A single-purpose brick runs out of reach once a request crosses domains. An example is a question that needs both research reports and usage data. Supervisor Agent is the Agent Bricks answer. It builds a supervisor that delegates tasks to specialised subagents and tools, then combines their results into one response. The documented use cases are market analysis across research reports and usage data, answering questions about internal processes while automating a ticket backlog, and customer service across policy, FAQ and account questions. You must provide at least one subagent and can use at most 50 agents in one supervisor system. A Knowledge Assistant endpoint is one of the supported subagent types, so the bricks compose.

This is the key design consequence. Granting access to the supervisor is not enough, because each subagent type needs its own end-user permission.

Two capabilities come built in. Every supervisor has a code execution tool that runs model-generated Python (the default), SQL or shell commands in a sandboxed serverless session, and you don't configure it. Web search always runs on the databricks-gpt-5 Foundation Model API, whatever model powers the supervisor. It needs databricks-gpt-5 in the workspace's system.ai allowlist and is unavailable in workspaces with the Enhanced Security and Compliance add-on.

Sources1

2.Building, tuning and sharing a supervisor

You can build a supervisor in the Agents UI. You can also build one with the Databricks SDK for Python, which is in Beta. With the SDK, the supervisor is an object with a display name, a description and instructions. Each subagent is attached as a Tool.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import SupervisorAgent

w = WorkspaceClient()

supervisor_agent = SupervisorAgent(
    display_name="<display-name>",
    description="<description>",
    instructions="<instructions>",
)
created = w.supervisor_agents.create_supervisor_agent(supervisor_agent=supervisor_agent)
print(created)

tool = Tool(
    tool_type="knowledge_assistant",
    description="<tool-description>",
    knowledge_assistant=KnowledgeAssistant(
        knowledge_assistant_id="<knowledge-assistant-id>",
    ),
)

created_tool = w.supervisor_agents. ? (
    parent="supervisor-agents/<supervisor-agent-id>",
    tool=tool,
    tool_id="<tool-id>",
)

To improve quality, you give feedback instead of writing code. In the Examples tab, add questions and task scenarios. Share the configuration page with experts, who need Can Manage on the supervisor plus access to each subagent, and have them attach Guidelines to questions. The supervisor is then retrained and optimised from the labeled data. People who only consume the endpoint get Can Query, which lets them call it from AI Playground or the API but not view or edit the agent.

Sources1

3.Agent Bricks, a simpler pattern, or a custom agent?

Agent Bricks isn't the only option, and a multi-agent supervisor isn't the default. Databricks' design-pattern guidance says to start simple and add agentic behaviour only when you need it, because flexibility costs complexity and latency.

A supervisor earns its complexity when the work really is multi-domain. Signs of this are distinct skill areas, too many tools to fit in one agent's schema, or a need for agents to critique one another. The general risks don't go away: agents can bounce tasks between themselves without resolving them, so constraints and tracing still matter. When no brick fits, for example because you need a specific authoring library or control flow, build a custom agent in Python with LangGraph, LangChain, OpenAI, LlamaIndex or another library. This isn't an either/or choice. A custom agent deployed on Databricks Apps can itself be a supervisor subagent.

Sources23

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.A multi-agent supervisor is the best default design for any agent application.Why is that wrong?

   The guidance is to start simple and move to multi-agent only for large or cross-functional domains. Multi-agent systems are harder to orchestrate, trace and debug.

   Covered in Agent Bricks, a simpler pattern, or a custom agent?

2. 2.Any AI Search index can be added to a supervisor as a subagent.Why is that wrong?

   Supervisor Agent supports only Delta Sync indexes as AI Search index subagents.

   Covered in Supervisor Agent: one endpoint over many specialists

3. 3.Granting a user CAN QUERY on the supervisor endpoint gives them answers from every subagent.Why is that wrong?

   The supervisor enforces each end user's own access, so users need explicit permission on each subagent and its data.

   Covered in Supervisor Agent: one endpoint over many specialists