A chat application template for interacting with Databricks Agent Serving endpoints, built with Next.js, Vercel AI SDK, and Databricks authentication.

Features · Running Locally · Deployment

This template is based on the Vercel AI Chatbot template, with Databricks-specific enhancements for authenticating to agents and database instances on Databricks.

For additional documentation and details, see the original repository.

NOTE: this template provides a fully functional chat app for custom code agents and Agent Bricks deployed on Databricks, but has some known limitations for other use cases. Work is in progress on addressing these limitations.

• Databricks Agent and Foundation Model Integration: Direct connection to Databricks Agent serving endpoints and Agent Bricks
• Databricks Authentication: Uses Databricks authentication to identify end users of the chat app and securely manage their conversations.
• Persistent Chat History: Leverages Databricks Lakebase (Postgres) for storing conversations, with governance and tight lakehouse integration.

1. Databricks serving endpoint: you need access to a Databricks workspace containing the Agent Bricks or custom agent serving endpoint to chat with.
2. Set up Databricks authentication
   • Install the Databricks CLI
   • Run export DATABRICKS_CONFIG_PROFILE='your_profile_name', replacing your_profile_name with the name of a CLI profile for configuring authentication
   • Run databricks auth login --profile "$DATABRICKS_CONFIG_PROFILE" to configure authentication for your workspace under the named profile
3. Latest Databricks CLI: ensure you have the latest version of the Databricks CLI installed:
   • On macOS, you can run brew upgrade databricks && databricks -v. See docs for other platforms

This project includes a Databricks Asset Bundle (DAB) configuration that simplifies deployment by automatically creating and managing all required resources.

1. Clone the repo:

   git clone https://github.com/databricks/app-templates
   cd e2e-chatbot-app-next

2. Databricks authentication: Ensure auth is configured as described in Prerequisites.

3. Specify serving endpoint: In databricks.yml, set the default value of serving_endpoint_name to the name of the custom code agent or Agent Bricks endpoint to chat with.

   • NOTE: if using Agent Bricks Multi-Agent Supervisor, you need to additionally grant the app service principal the CAN_QUERY permission on the underlying agent(s) that the MAS orchestrates. You can do this by adding those agent serving endpoints as resources in databricks.yml (see the NOTE in databricks.yml on this)

4. Validate the bundle configuration:

   databricks bundle validate

5. Deploy the bundle (creates Lakebase instance, database catalog, and app). The first deployment may take several minutes for provisioning resources, but subsequent deployments are fast:

   databricks bundle deploy

   This creates:

   • Lakebase database instance for persisting chat history
   • App resource ready to start

6. Start the app:

   databricks bundle run databricks_chatbot

7. View deployment summary (useful for debugging deployment issues):

   databricks bundle summary

The bundle supports multiple environments:

• dev (default): Development environment
• staging: Staging environment for testing
• prod: Production environment

To deploy to a specific target:

databricks bundle deploy -t staging --var serving_endpoint_name="your-endpoint"

Before running the app locally, you should first deploy the app to Databricks following the steps in Deployment. This is the simplest way to get the required database instance set up with the correct permissions, so that both you and your app service principal can connect to the database, with database migrations already applied.

1. Clone and install:

   git clone https://github.com/databricks/app-templates
   cd e2e-chatbot-app-next
   npm install

2. Set up environment variables:

   cp .env.example .env.local

   Address the TODOs in .env.local, specifying your Databricks CLI profile and database connection details.

3. Run the application:

   npm run dev

   The app starts on localhost:3000

• This chat app only supports the following Databricks serving endpoint types (Foundation Model API endpoints are not supported):
  • Custom code agents deployed via Agent Framework, and which implement the ResponsesAgent interface and support streaming output via predict_stream. This covers any agent built following the recommended approach for authoring agents.
  • Agent Bricks endpoints
• No support for image or other multi-modal inputs
• The most common and officially recommended authentication methods for Databricks are supported: Databricks CLI auth for local development, and Databricks service principal auth for deployed apps. Other authentication mechanisms (PAT, Azure MSI, etc) are not currently supported.
• We create one database per app, because the app code targets a fixed ai_chatbot schema within the database instance. To host multiple apps out of the same instance, you can:
  • Update the database instance name in databricks.yml
  • Update references to ai_chatbot in the codebase to your new desired schema name within the existing database instance
  • Run npm run db:generate to regenerate database migrations
  • Deploy your app