Skip to main content

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 run uv tool install databricks-agentbricks.
  • After sign-in, the core path is three commands: agentbricks init scaffolds the project, agentbricks dev runs it locally, and agentbricks deploy provisions resources and rolls it out.
  • agent.toml is 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, or pip 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
  1. Sign in. databricks auth login runs the OAuth flow and saves a profile in ~/.databrickscfg. agentbricks login validates that profile and saves it as the CLI default, so later commands can omit --profile.
  2. Scaffold. --framework langgraph picks the LangGraph template, which includes a browser chat app. Use --framework openai for the OpenAI Agents SDK, or add --disable-chat-app for an API-only backend.
  3. Run locally. agentbricks dev starts 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 the MODEL value in agent/agent.py. Local runs don't connect to memory or session stores.
  4. Deploy. agentbricks deploy my-agent provisions the stores declared in agent.toml, grants the agent's service principal access to them and rolls out an app named agent-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.