How do I get started with the Agent Bricks CLI?
Summary
- The Agent Bricks CLI (
databricks-agentbricks) is a Databricks command-line tool, in Beta, that scaffolds a custom agent project, runs it locally and deploys it to the Databricks agent runtime. - Before you start, install the Databricks CLI, Python 3.11 or above (Databricks recommends Python 3.12) and
uv, then runuv tool install databricks-agentbricks. - After sign-in, the core path is three commands:
agentbricks initscaffolds the project,agentbricks devruns it locally, andagentbricks deployprovisions resources and rolls it out. agent.tomlis the declarative source of truth for the agent's managed resources: tools, memory and session stores, and the tracing experiment.- Existing LangGraph or OpenAI Agents SDK agents can move over with
agentbricks init --existing, which prepares migration instructions for a coding agent.
How do I get started with the Agent Bricks CLI?
Install it, sign in with a Databricks CLI profile, and run three commands: agentbricks init, agentbricks dev and agentbricks deploy. That takes you from an empty directory to a deployed agent without wiring up runtime, tools, memory and managed resources by hand. The CLI is in Beta, and no workspace setting is required to enable it.
What is the Agent Bricks CLI?
The Agent Bricks CLI is the code-first path for building custom agents on Databricks, and Databricks recommends it for new agents written in code. It scaffolds a project from a framework template, LangGraph or the OpenAI Agents SDK, with the runtime, tests and an optional chat UI already wired up. You write the application logic: model, tools and prompts. The CLI runs the agent locally and deploys it to Agent Runtime, where DurableAgentServer serves it with persistent run state and crash recovery.
Before you start
- The Databricks CLI, installed and on your path.
- Python 3.11 or above for scaffolded projects. Databricks recommends Python 3.12.
uv, which runs the scaffolded project.- The CLI itself:
uv tool install databricks-agentbricks, orpip install databricks-agentbricks.
Create and deploy your first agent
databricks auth login --host "https://<your-workspace-url>" --profile my-workspace
agentbricks login --profile my-workspace
agentbricks init --framework langgraph my-agent
cd my-agent
agentbricks dev
agentbricks deploy my-agent
- Sign in.
databricks auth loginruns the OAuth flow and saves a profile in~/.databrickscfg.agentbricks loginvalidates that profile and saves it as the CLI default, so later commands can omit--profile. - Scaffold.
--framework langgraphpicks the LangGraph template, which includes a browser chat app. Use--framework openaifor the OpenAI Agents SDK, or add--disable-chat-appfor an API-only backend. - Run locally.
agentbricks devstarts a local server on port 8000 with the same command and environment as the agent runtime, connected to Databricks model serving. The default model is theMODELvalue inagent/agent.py. Local runs don't connect to memory or session stores. - Deploy.
agentbricks deploy my-agentprovisions the stores declared inagent.toml, grants the agent's service principal access to them and rolls out an app namedagent-bricks-<name>. It returns the deployment's URL.
The commands you'll use most
| Command | What it does |
|---|---|
agentbricks init |
Scaffold a project, or prepare an existing agent with --existing |
agentbricks dev |
Run the agent locally with a chat UI |
agentbricks deploy |
Deploy the agent to the Databricks agent runtime |
agentbricks tools |
List, add and remove the agent's tools |
agentbricks memory, agentbricks sessions |
Bind, unbind and manage memory and session stores |
agentbricks tracing |
Bind, unbind and inspect tracing |
agentbricks deployments |
list, get, wait, logs, start, stop and delete deployed agents |
agentbricks doctor |
Check that an existing agent is set up for the CLI |
Every command supports --help, and the full flag list is in the command reference on GitHub.
How agent.toml ties it together
agent.toml declares the Databricks-managed resources the agent depends on, and agentbricks deploy reads it to provision and wire them up. init declares a memory store, a session store and a tracing experiment under /Shared/agentbricks_traces/, each with a random suffix so projects don't share them. Add tools as you go: agentbricks tools add mcp system.ai.web_search adds web search, and agentbricks tools add mcp system.ai.dbsql runs SQL on a SQL warehouse. By default, a tool runs with the permissions of the user who sent the request. Add --auth app to run it as the app's service principal. Tracing is on by default, and agentbricks tracing list shows recent traces.
Bring an existing agent
For an agent already built with LangGraph or the OpenAI Agents SDK, run agentbricks init --framework langgraph --existing . in its directory (or --framework openai). The CLI doesn't rewrite your code. It writes an agent-bricks-migrate/ directory with instructions and a prompt for a coding agent, which converts the project to agent.toml and a DurableAgentServer entrypoint. Check the result with agentbricks doctor ., delete the migration directory and the two skills it added, then run agentbricks dev and agentbricks deploy.
FAQs
Is the Agent Bricks CLI generally available?
No. It's in Beta, and no workspace setting is required to enable it. Install it with uv tool install databricks-agentbricks to get started.
Which frameworks does it support?
The bundled templates cover LangGraph (--framework langgraph) and the OpenAI Agents SDK (--framework openai). For custom endpoints, request formats or protocols, agentbricks init --server custom keeps your own server.
How do I call a deployed agent?
Run agentbricks endpoint invoke from your terminal, or send a POST to the app's /api/invocations endpoint with a Databricks OAuth token. Personal access tokens don't work for Databricks Apps.
What if the install fails?
Check python3 --version first, since scaffolded projects need Python 3.11 or above. uv tool install --python 3.12 databricks-agentbricks installs with Python 3.12, and on an Intel Mac, pip install --only-binary :all: databricks-agentbricks avoids building cryptography from source.
The information provided herein is for general informational purposes only and may not reflect the most current product capabilities or configurations.