Build a custom agent using the Supervisor API (Beta)

Important

This feature is in Beta. Account admins can control access to this feature from the Previews page. See Manage Azure Databricks previews.

You can build a Azure Databricks Apps agent that uses the Supervisor API (Beta) for orchestration instead of managing the agent loop in your own code. The result is the same as authoring a custom agent: a deployed App with a chat UI, an /invocations endpoint, and authentication. The difference is that Azure Databricks runs the agent loop for you. Your agent.py makes a single API call, and Azure Databricks handles tool selection, execution, and response synthesis.

The Supervisor API works with any of the supported foundation models. Change the model field to switch providers without touching your tool definitions or handler logic.

When to use the Supervisor API

The Supervisor API works well when your agent uses only Azure Databricks-hosted tools and doesn't need custom logic between tool calls. Use a custom agent loop instead if your agent requires any of the following:

  • Client-side function tools (the Supervisor API cannot mix hosted and client-side tools in one request)
  • Agent endpoints other than Agent Bricks Knowledge Assistant endpoints
  • Custom retrievers, custom inputs/outputs, or fine-grained streaming control
  • Custom Python logic between tool calls, such as conditional branching or state management
  • Control over inference parameters like temperature

For the full API reference and supported parameters, see Supervisor API (Beta).

Requirements

Build a custom agent using the Supervisor API

The recommended starting point is to create a new app from the latest Databricks app template. The latest templates include a built-in use-supervisor-api skill for AI coding assistants, as well as an add-tools skill for adding hosted tools.

To create a new app from a template, see Author an AI agent and deploy it on Databricks Apps.

Once your app is set up from the latest template, open the project in your AI coding assistant and run:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

The skill updates your agent_server/agent.py to call DatabricksOpenAI().responses.create() with hosted tools, replacing the manual agent loop. It also adds the databricks-openai dependency and notes the beta limitations.

The result is the same deployed App, with a chat UI, authentication, and an /invocations endpoint, but with simpler agent code. For the full deployment workflow (deploy to Apps, add tools, evaluate), see Author an AI agent and deploy it on Databricks Apps.

Supported tools and parameters

For the full list of supported tool types, request parameters, and code examples, see Supervisor API (Beta).

For each tool you add, also grant the corresponding resource permission in databricks.yml. See the add-tools skill in .claude/skills/ for examples.

Authorization for hosted tools

When the Supervisor API runs the agent loop, it executes hosted tools using either the app's identity or the requesting user's identity. Choose based on whether all users of the app should share the same access to your tools, or each user should access only what their own permissions allow.

  • App authorization (default): Tools run as the app's service principal. Grant the service principal permission on each tool the agent uses. See App authorization.
  • User authorization: Tools run as the user who sent the request, so Unity Catalog permissions, row filters, and column masks apply per user. See the following section.

Run tools as the requesting user

Important

User authorization is in Public Preview. Your workspace admin must enable it before you can add scopes to your app. See Add scopes to an app.

To run hosted tools on behalf of the requesting user, forward the user's token to the DatabricksOpenAI client and add the user-authorization scopes your tools need.

  1. Add the user-authorization scopes your app needs. ai-gateway is required for all Supervisor API access. Add the per-tool scope for each tool type the agent uses:

    Tool type Required scope
    All tools ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    The app tool type is not supported with user authorization. To call an App endpoint as a tool, use app authorization instead. For how to add scopes through the workspace UI or Declarative Automation Bundles, see User authorization.

  2. In your agent.py handler, pass a user workspace client to DatabricksOpenAI. This is the only Supervisor-specific wiring: instead of calling a resource directly with the user client, you hand it to the client that runs the agent loop.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() reads the forwarded user token from the request headers, which are only populated at query time. Call it inside the invoke and stream handlers, never in __init__ or at app startup. If the forwarded token is missing, the resulting client isn't authenticated as the requesting user. For how to verify the agent runs as the caller rather than the app's service principal, see User authorization.

  3. Grant each user who runs the agent the required permission on each tool, such as CAN_RUN on a Genie Space or CAN_QUERY on a knowledge assistant endpoint.

Additional resources

  • Last updated on