Agent Bricks CLI

Beta

This feature is in Beta. No workspace setting is required to enable it. Install the Agent Bricks CLI to get started.

The Agent Bricks CLI (databricks-agentbricks) is a Databricks command-line tool for developers who build and deploy custom agents in code.

The Agent Bricks CLI is a code-first path for building custom agents from the terminal. The Agent Bricks CLI scaffolds a project using a built-in framework based on Databricks best practices. It can then run the project locally for testing and deploy it to the Databricks agent runtime. The CLI enables you to go from an empty directory to a deployed agent without wiring up runtime, tools, memory, and managed resources by hand. For other ways to build custom agents, including the app-based workflow, see Author an agent and deploy it on Databricks Apps.

Prerequisites

• The Databricks CLI, installed and available on your path.

• Python 3.10 or above, with pip.

• Install the Agent Bricks CLI:

  Bash

  pip install databricks-agentbricks

The Agent Bricks CLI lifecycle

The Agent Bricks CLI scaffolds a local directory of deployable agent code from a framework template, with the runtime, tests, and an optional chat UI already wired up. You write the application logic (model, tools, and prompts), and the CLI handles running it locally and deploying it to Databricks infrastructure.

agent.toml is the declarative source of truth for all Databricks-managed resources your agent depends on: tool bindings (data sandbox, managed Model Context Protocol (MCP) services, Unity Catalog functions), and memory, session, and tracing resources. agentbricks deploy reads it to provision and wire everything up, so the file, not hand-written setup code, is what deploys.

The three commands that take an agent from a blank directory to production:

• agentbricks init scaffolds the project from a bundled template, optionally seeding a .env file with a Databricks profile so the project runs right away.
• agentbricks dev runs the agent locally against Databricks model serving so you can test it before deploying.
• agentbricks deploy provisions the resources declared in agent.toml and rolls the agent out to the Databricks agent runtime.

note

You can also add tools and bind memory and session stores at any time, not only at init. Use agentbricks tools add, agentbricks memory bind, and agentbricks sessions bind to update your agent configuration between any of these steps.

Agent Bricks CLI capabilities

Capability	Description
Model access	The Agent Bricks CLI automatically provisions model access so your agent can call a Databricks-served model without managing credentials or endpoints. See Databricks Foundation Model APIs.
Managed memory	Long-term memories that an agent can write and search, partitioned by actor and backed by managed stores. Use memory to persist facts and preferences across sessions. See Managed agent memory.
Managed sessions	Conversation transcripts held in managed session stores and partitioned by actor, with support for forking sessions into independent copies. See Managed agent sessions.
Tools	Databricks-managed capabilities declared in agent.toml: a downscoped Unity Catalog sandbox, a Databricks-managed MCP service, or a Unity Catalog function. Custom Python tools are written directly in the project code. See MCPs and agent tools.
Tracing	MLflow tracing that is on by default, routing each run's traces to a per-project MLflow experiment for debugging and monitoring. See Tracing overview.
Deployment	Deploys an agent to the Databricks agent runtime, grants the agent's service principal access to bound stores, and manages the deployment lifecycle.

Capability	Description
Model access	The Agent Bricks CLI automatically provisions model access so your agent can call a Databricks-served model without managing credentials or endpoints. See Databricks Foundation Model APIs.
Managed memory	Long-term memories that an agent can write and search, partitioned by actor and backed by managed stores. Use memory to persist facts and preferences across sessions. See Managed agent memory.
Managed sessions	Conversation transcripts held in managed session stores and partitioned by actor, with support for forking sessions into independent copies. See Managed agent sessions.
Tools	Databricks-managed capabilities declared in agent.toml: a downscoped Unity Catalog sandbox, a Databricks-managed MCP service, or a Unity Catalog function. Custom Python tools are written directly in the project code. See MCPs and agent tools.
Tracing	MLflow tracing that is on by default, routing each run's traces to a per-project MLflow experiment for debugging and monitoring. See Tracing overview.
Deployment	Deploys an agent to the Databricks agent runtime, grants the agent's service principal access to bound stores, and manages the deployment lifecycle.

Step 1: Authenticate with OAuth and save a profile

The Agent Bricks CLI uses Databricks CLI authentication. Authenticate to your workspace with OAuth (user-to-machine) and save the credentials as a named profile.

To start the OAuth flow, run the following, replacing the host with your workspace URL. The command opens a browser to complete sign-in, then writes the profile to ~/.databrickscfg:

Bash

databricks auth login --host https://<your-workspace-url> --profile <profile>

To set that profile as the CLI's default so later commands can omit --profile, run the following:

Bash

agentbricks login --profile <profile>

agentbricks login validates the profile's credentials. If they are missing or rejected, the CLI reruns databricks auth login and retries.

Step 2: Scaffold the agent project

Scaffold a new agent project, and pass --framework to choose the template. This example uses the LangGraph template, which includes a browser chat app:

Bash

agentbricks init --framework langgraph my-agent
cd my-agent

The CLI ships one bundled template per framework and --framework selects which one to scaffold from: langgraph for LangGraph or openai for the OpenAI Agents SDK. The CLI writes the project's managed resources and tool bindings to agent.toml and template provenance to .agentbricks/project.toml. To scaffold the API-only backend without the chat app, add --disable-chat-app.

Step 3: Attach managed session and memory stores

Bind managed stores so your agent can persist conversation history and long-term memory. Each command records the store name in agent.toml and creates the store if it does not exist.

To bind a session store and a memory store, run the following:

Bash

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

Step 4: View tracing

Tracing is on by default. agentbricks init binds a default /Shared/agentbricks_traces/<project> MLflow experiment, and agentbricks dev and agentbricks deploy send each run's traces to it.

To list traces after your agent has produced some, run the following:

Bash

agentbricks tracing list

To bind a specific MLflow experiment, run agentbricks tracing bind --experiment-id <experiment-id>. To turn tracing off, run agentbricks tracing unbind.

Step 5: Run the agent locally

Run the agent on your machine to test it before you deploy.

Bash

agentbricks dev

This starts a local server on port 8000 using the same command and environment as the Databricks agent runtime. The Agent Bricks CLI connects the agent to Databricks model serving so it can call the model locally. The template sets a default model as the MODEL value in agent/agent.py. To use a different model, edit that value. Send requests to http://localhost:8000 to interact with the agent.

Step 6: Deploy the agent

Deploy the agent to the Databricks agent runtime. The CLI provisions the bound stores, grants the agent's service principal access to them, and rolls out the deployment. The deployed agent is named agent-bricks-<name>.

Bash

agentbricks deploy my-agent

When the deployment finishes, the CLI returns the deployment's URL. Open that URL to interact with your live agent, which is automatically connected to Databricks model serving. To manage the deployment afterward, use the agentbricks deployments commands, such as agentbricks deployments logs and agentbricks deployments stop.

Command reference

For the full, up-to-date command reference including all commands and flags, see the Agent Bricks CLI README on GitHub.

Additional resources

• Agent tools and MCP services: MCPs and agent tools.
• Managed agent memory concepts and API: Managed agent memory.
• Managed agent sessions concepts and API: Managed agent sessions.
• MLflow Tracing for agents: Tracing overview.