Author an AI agent and deploy it on Databricks Apps

Build an AI agent and deploy it using Databricks Apps. Databricks Apps gives you full control over the agent code, server configuration, and deployment workflow. This approach is ideal when you need custom server behavior, git-based versioning, or local IDE development.

Requirements

Enable Databricks Apps in your workspace. See Set up your Databricks Apps workspace and development environment.

Step 1. Clone the agent app template

Get started by using a pre-built agent template from the Databricks app templates repository.

This tutorial uses the agent-openai-agents-sdk template, which includes:

• An agent created using OpenAI Agent SDK
• Starter code for an agent application with a conversational REST API and an interactive chat UI
• Code to evaluate the agent using MLflow

Choose one of the following paths to set up the template:

Workspace UI

Install the app template using the Workspace UI. This installs the app and deploys it to a compute resource in your workspace. You can then sync the application files to your local environment for further development.

1. In your Databricks workspace, click + New > App.

2. Click Agents > Agent - OpenAI Agents SDK.

3. Create a new MLflow experiment with the name openai-agents-template and complete the rest of the set up to install the template.

4. After you create the app, click the app URL to open the chat UI.

After you create the app, download the source code to your local machine to customize it:

1. Copy the first command under Sync the files

   

2. In a local terminal, run the copied command.

Clone from GitHub

To start from a local environment, clone the agent template repository and open the agent-openai-agents-sdk directory:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Step 2. Understand the agent application

The agent template demonstrates a production-ready architecture with these key components. Open the following sections for more details about each component:

Open the following sections for more details about each component:

Author agents using AI coding assistants

Databricks recommends using AI coding assistants such as Claude, Cursor, and Copilot to author agents. Use the provided agent skills, in /.claude/skills, and the AGENTS.md file to help AI assistants understand the project structure, available tools, and best practices. Agents can automatically read those files to develop and deploy the Databricks Apps.

Advanced authoring topics

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)

Step 3. Run the agent app locally

Set up your local environment:

1. Install uv (Python package manager), nvm (Node version manager), and the Databricks CLI:

   • uv installation
   • nvm installation
   • Run the following to use Node 20 LTS:

     nvm use 20
     

   • databricks CLI installation

2. Change directory to the agent-openai-agents-sdk folder.

3. Run the provided quickstart scripts to install dependencies, set up your environment, and start the app.

   uv run quickstart
   uv run start-app
   

In a browser, go to http://localhost:8000 to start chatting with the agent.

Step 4. Configure authentication

Your agent needs authentication to access Databricks resources. Databricks Apps provides two authentication methods:

App authorization (default)

App authorization uses a service principal that Azure Databricks automatically creates for your app. All users share the same permissions.

Grant permissions to the MLflow experiment:

1. Click Edit on your app home page.
2. Navigate to the Configure step.
3. In the App resources section, add the MLflow experiment resource with Can Edit permission.

For other resources (Vector Search, Genie spaces, serving endpoints), add them the same way in the App resources section.

See App authorization for more details.

User authorization

User authorization lets your agent act with each user's individual permissions. Use this when you need per-user access control or audit trails.

Add this code to your agent:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside predict or predict_stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important: Initialize get_user_workspace_client() inside your predict or predict_stream functions, not during app startup. User credentials only exist when handling a request.

Configure scopes: Add authorization scopes in the Databricks Apps UI to define which APIs your agent can access on behalf of users.

See User authorization for complete setup instructions.

Step 5. Evaluate the agent

The template includes agent evaluation code. See agent_server/evaluate_agent.py for more information. Evaluate the relevance and safety of your agent's responses by running the following in a terminal:

uv run agent-evaluate

Step 6. Deploy the agent to Databricks Apps

After configuring authentication, deploy your agent to Databricks. Ensure you have the Databricks CLI installed and configured.

1. If you cloned the repository locally, create the Databricks app before deploying it. If you created your app through the workspace UI, skip this step as the app and MLflow experiment are already configured.

   databricks apps create agent-openai-agents-sdk
   

2. Sync local files to your workspace. See Deploy the app.

   DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
   databricks sync . "/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk"
   

3. Deploy your Databricks App.

   databricks apps deploy agent-openai-agents-sdk --source-code-path /Workspace/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk
   

For future updates to the agent, sync and redeploy your agent.

Step 7. Query the deployed agent

Users query your deployed agent using OAuth tokens. Personal access tokens (PATs) are not supported for Databricks Apps.

Generate an OAuth token using the Databricks CLI:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Use the token to query the agent:

curl -X POST <app-url.databricksapps.com>/invocations \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Limitations

Only medium and large compute sizes are supported. See Configure the compute size for a Databricks app.