Supervisor Agents

Skill: databricks-agent-bricks

What You Can Build

You can combine Knowledge Assistants, Genie Spaces, ML endpoints, Unity Catalog functions, and external MCP servers behind one conversational interface. A Supervisor Agent analyzes each query, routes it to the right specialist, and returns the response — so users never need to know which backend handles their question.

In Action

“Create a Supervisor Agent that routes questions to a Knowledge Assistant for policy questions, a Genie Space for data analysis, and an MCP server for invoice operations. Use Python with the AI Dev Kit tools.”

manage_mas(
    action="create_or_update",
    name="AP Invoice Supervisor",
    agents=[
        {
            "name": "policy_expert",
            "ka_tile_id": "f32c5f73-...",
            "description": "Answers questions about AP policies, approval workflows, and compliance requirements from policy documents"
        },
        {
            "name": "billing_analyst",
            "genie_space_id": "01abc123-...",
            "description": "SQL analytics on AP invoice data: spending trends, vendor analysis, aging reports"
        },
        {
            "name": "ap_operations",
            "connection_name": "ap_invoice_mcp",
            "description": "Execute AP operations: approve/reject/flag invoices, search invoice details, get vendor summaries, trigger batch workflows"
        }
    ],
    description="AP automation assistant with analytics, policy guidance, and operational actions",
    instructions="""
    Route queries as follows:
    - Policy questions (thresholds, SLAs, compliance rules) -> policy_expert
    - Data questions (invoice counts, spend analysis, vendor metrics) -> billing_analyst
    - Actions (approve, reject, flag, search, workflows) -> ap_operations

    When a user asks to approve, reject, or flag an invoice, ALWAYS use ap_operations.
    """
)

Key decisions:

• Five agent types supported — Knowledge Assistants (ka_tile_id), Genie Spaces (genie_space_id), model serving endpoints (endpoint_name), UC functions (uc_function_name), and MCP servers (connection_name)
• Descriptions drive routing — the Supervisor uses agent descriptions to decide where to send each query, so specificity matters
• Instructions add routing rules — use them to resolve ambiguity when descriptions alone aren’t enough
• Each agent entry needs exactly one of the five identifier fields plus a name and description

More Patterns

Add a UC Function as an Agent

“Add a Unity Catalog function that enriches customer records to my Supervisor Agent. Use Python.”

manage_mas(
    action="create_or_update",
    name="Support Supervisor",
    agents=[
        {
            "name": "data_enrichment",
            "uc_function_name": "sales_analytics.utils.enrich_customer_data",
            "description": "Enriches customer records with demographic and purchase history data"
        },
        # ... other agents
    ],
    instructions="Use data_enrichment when the user asks for customer context or history lookups."
)

The UC function must already exist, and the agent service principal needs EXECUTE privilege. Grant it with GRANT EXECUTE ON FUNCTION catalog.schema.function_name TO <agent_sp>.

Wire in an External MCP Server

“Connect my Supervisor Agent to an external ticket system via an MCP server over a UC HTTP Connection. Show the SQL for the connection and the Python for the agent config.”

CREATE CONNECTION ticket_system_mcp TYPE HTTP
OPTIONS (
  host 'https://my-app.databricksapps.com',
  port '443',
  base_path '/api/mcp',
  client_id '<service_principal_id>',
  client_secret '<service_principal_secret>',
  oauth_scope 'all-apis',
  token_endpoint 'https://<workspace>.azuredatabricks.net/oidc/v1/token',
  is_mcp_connection 'true'
);

GRANT USE CONNECTION ON ticket_system_mcp TO `<agent_sp>`;

{
    "name": "ticket_operations",
    "connection_name": "ticket_system_mcp",
    "description": "Creates and manages support tickets: open, close, escalate, search by customer or status"
}

The MCP server must implement JSON-RPC 2.0 methods (initialize, tools/list, tools/call). Test the connection before adding it to a Supervisor with SELECT http_request(conn => 'ticket_system_mcp', method => 'POST', ...).

Update Routing Without Recreating

“My Supervisor Agent is routing billing questions to the wrong agent. Update the descriptions to fix routing.”

manage_mas(
    action="create_or_update",
    name="Support Supervisor",
    agents=[
        {
            "name": "billing_agent",
            "ka_tile_id": "abc123-...",
            "description": "Handles billing questions including invoices, payments, refunds, subscription changes, and pricing inquiries"
        },
        {
            "name": "technical_agent",
            "endpoint_name": "tech-support-endpoint",
            "description": "Handles technical issues: API errors, integration problems, product bugs, and configuration help. Does NOT handle billing."
        }
    ],
    instructions="If the query mentions money, charges, or billing, always route to billing_agent."
)

Adding “Does NOT handle billing” to the technical agent’s description and explicit routing rules in the instructions resolves most misrouting. The Supervisor matches by name, so you don’t need to delete and recreate.

Watch Out For

• Vague descriptions cause misrouting — “Billing agent” is not enough. Write descriptions that list specific topics: “invoices, payments, refunds, subscription changes.” The Supervisor routes based on description similarity to the user query.
• Overlapping agent domains create unpredictable routing — if two agents both mention “customer data,” the Supervisor picks one semi-randomly. Give each agent a distinct, non-overlapping scope.
• Forgetting to grant permissions — UC functions need EXECUTE, MCP connections need USE CONNECTION. Missing permissions cause silent failures where the agent appears to work but returns empty results.
• No fallback agent — without a general-purpose agent, queries that don’t match any description get routed to the closest match, which is often wrong. Add a general_agent with a broad description to catch edge cases.