Skip to main content
Last updated on

Build a custom agent using the Supervisor API (Beta)

Beta

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

You can build a 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 Databricks runs the agent loop for you. Your agent.py makes a single API call, and 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 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.

Next steps​

On this page