Agent Bricks CLI (agentbricks)

Agent Bricks CLI is an experimental command-line interface for building and deploying custom agents on Databricks. It manages memory, sessions, tracing, and deployments from one authenticated command.

The underlying APIs are in preview and may need workspace enablement.

Overview

A managed path from your custom agent code to a production-ready, scalable, durable agent hosted on Databricks in minutes - with no server framework to build, no infrastructure to provision, and no invocation protocol to design yourself. Bring your own agent, or start from a template.

• Deployment - a guided lifecycle (scaffold, run locally, deploy) that turns an agent project into a hosted endpoint. Databricks provisions the compute, the stores your agent binds (session, memory), and the access grants, so you ship application code and get a running endpoint.
• Runtime - a managed HTTP invocation contract (synchronous, streaming, background) plus optional durable execution (persistence, heartbeats, crash recovery) backed by Databricks Lakebase, with no database or job queue to operate. Use the opinionated DurableAgentServer to get it out of the box, or bring your own server for full control. AgentApp remains available as a deprecated compatibility alias; new code should use DurableAgentServer.

Deployment

• Agent project - agentbricks init scaffolds a deployable project from a framework template (LangGraph or OpenAI Agents) with the runtime, tests, and an optional chat UI wired up; you edit the application code (model, tools, prompts).
• agent.toml - the declarative source of truth for the Databricks-managed infrastructure your agent depends on: tool bindings (data sandbox, managed MCP services, Unity Catalog functions) and memory, session, and durability resources. agentbricks deploy reads it to provision and wire everything up (detailed under Agent tools).
• agentbricks deploy - provisions the bound stores, grants the app's service principal access to them, provisions the durable-runtime database when durability is on, configures tracing, and rolls out the app. agentbricks deployments covers the lifecycle (list, get, logs, start, stop, delete).
• agentbricks dev - runs your agent from the same manifest the deployment uses, so local behavior matches what ships.

Runtime

The two ways to run an agent:

• DurableAgentServer - opinionated, batteries included. Register one handler and get the managed invocation contract (synchronous, streaming, background). Enable the durable runtime so long-running and background work survives restarts, redeploys, and crashes. The framework templates are thin layers over DurableAgentServer (HTTP contract detailed under Runtime).
• Custom server - generic, full control. agentbricks init --server custom scaffolds a minimal FastAPI server with no DurableAgentServer: you define your own endpoints, request/response shapes, and protocol. agentbricks dev and agentbricks deploy run and ship it the same way.

Prerequisites

• Python ≥3.10 — the agentbricks CLI installs and runs on any Python 3.10+. The memory, sessions, tools, and agentbricks tracing bind/unbind commands need nothing else.
• uv — needed to scaffold, run, and deploy an agent (agentbricks init → agentbricks dev → agentbricks deploy): the scaffolded project builds its environment and launches with uv run, both locally and in the deployed Apps runtime. The store/session/tools commands and agentbricks tracing bind/unbind don't need it; agentbricks tracing list/get do, to read agentbricks dev's local trace store.
• Databricks CLI — needed for browser-based agentbricks login. If a profile is already authenticated, the CLI uses it directly and the Databricks CLI is optional.

Installation

The databricks-agentbricks Python distribution installs the agentbricks command and AgentKit.

pip install databricks-agentbricks

Install from PyPI rather than from this repository. Templates on main can depend on SDK changes that are not yet released, while generated projects install the released SDK from PyPI, so a CLI installed from source can scaffold projects that fail to start. To work on Agent Bricks itself, see CONTRIBUTING.md.

The base package includes the CLI, store SDK, and DurableAgentServer HTTP runtime. Generated projects declare their framework dependencies automatically.

Shell completion

Add this to ~/.zshrc:

eval "$(_AGENTBRICKS_COMPLETE=zsh_source agentbricks)"

Authentication

Agent Bricks CLI uses Databricks authentication. Ask the CLI to authenticate and remember a named profile:

agentbricks login --profile <profile>
agentbricks sessions stores list

agentbricks login validates existing credentials first. If credentials are missing or rejected in an interactive terminal, the CLI runs databricks auth login --profile <profile>, revalidates the profile, and stores the selection in the existing ~/.agentbricks/config.json state file. This browser-based setup requires the Databricks CLI. In non-interactive environments, authenticate the profile before running agentbricks. agentbricks logout forgets the saved selection without revoking the underlying credentials.

If Databricks SDK default authentication is already configured, you can skip agentbricks login. You can also pass the global --profile/-p option before an individual command, for example agentbricks --profile <profile> tools list. Use --output json for scripting.

Quickstart

The shortest path from a blank directory to a running and deployed agent:

agentbricks login --profile <profile>
agentbricks init my-agent       # Defaults to LangGraph; add --framework=openai for OpenAI Agents SDK
cd my-agent
agentbricks dev                 # run locally
agentbricks deploy my-agent     # deploy to Databricks

agentbricks dev runs the agent locally on http://localhost:8000, wrapping the Databricks Apps local runtime so local behavior matches a deployment.

agentbricks deploy my-agent deploys a Databricks App named agent-bricks-my-agent, provisions the stores declared in agent.toml, and grants the app's service principal access to the stores and direct App-auth tool resources declared there. Use agentbricks deployments list to find deployed apps, and agentbricks deployments get agent-bricks-my-agent to print an app's URL and status.

agentbricks init declares default memory and session stores in agent.toml, so the deployed agent has long-term memory and durable conversation history. It creates <name>-<6-letter-token>-memory and <name>-<6-letter-token>-sessions, and records both names in agent.toml. agentbricks deploy creates them if they don't exist yet. Point the agent at stores you already have with agentbricks memory bind <name> / agentbricks sessions bind <name>, or scaffold without stores using agentbricks init --server custom (see Initialize the chat app demo).

To exercise the agent (locally under agentbricks dev or once deployed), agentbricks endpoint invoke sends it an HTTP request. MLflow tracing is on by default (agentbricks init binds a default /Shared/agentbricks_traces/<project> experiment): agentbricks dev traces to a local MLflow server under .agentbricks/ and agentbricks deploy to the bound workspace experiment; agentbricks tracing list shows the available traces.

Inspect and clean up a project

Read agent.toml for the recorded agent name, declared memory/session stores, tracing, and tool bindings. A declaration does not confirm that the resource exists or that the deployed app can use it.

Inspect	Command	Details
Local onboarding checks	agentbricks doctor .	Offline; does not verify bindings or deployed resources.
Agent Bricks apps in a workspace	agentbricks -p <profile> deployments list	Lists apps with the agent-bricks- prefix in the selected workspace, including other projects.
App status and URL	agentbricks -p <profile> deployments get agent-bricks-<name>	Queries the selected workspace for the named app.
Memory store IDs and details	agentbricks -p <profile> memory stores list, then agentbricks -p <profile> memory stores get <resource-name>	Workspace-wide; can include other projects' stores. Use the ID or resource name, not the display name.
Session store names and details	agentbricks -p <profile> sessions stores list, then agentbricks -p <profile> sessions stores get <name>	Workspace-wide; can include other projects' stores. Use the store name.

Review each confirmation. Delete a store only after confirming that you own it and no other agent needs it, using the same profile and identifier used to inspect it.

Clean up	Command	Details
Deployment	agentbricks -p <profile> deployments delete agent-bricks-<name>	Managed Runtime Store cleanup checks the app identity and runs before app deletion; a cleanup failure retains the app for retry. Memory/session stores, tracing experiments, tools, and source files are retained.
Memory store	agentbricks -p <profile> memory stores delete <resource-name>	Soft-deletes the store after confirmation.
Session store	agentbricks -p <profile> sessions stores delete <name>	Deletes the store after confirmation.

Public names

Use agentbricks for the CLI and AgentKitClient from databricks_agentkit for the Python SDK. New projects store local state under .agentbricks/ and ~/.agentbricks/, use server = "agentbricks" in agent.toml, and deploy apps with the agent-bricks- prefix.

AgentKit SDK

AgentKitClient adds a small resource-oriented layer over AgentKit APIs. Pass it an authenticated Databricks WorkspaceClient, or omit the argument to use the Databricks SDK's default authentication resolution:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient(profile="my-workspace"))

session_store = agentkit.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")
session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

memory_store = agentkit.memory_stores.create("coding-agent-memory")
memory = memory_store.add(
    actor_id="alice",
    path="/preferences/style.md",
    content="The user prefers concise answers.",
)
results = memory_store.search(
    actor_id="alice",
    query="response preferences",
    limit=10,
)
memory = memory.update(content="The user prefers very concise answers.")
memory.delete()

The root collections manage stores: agentkit.memory_stores.create/get/list and agentkit.session_stores.create/get/list. A returned store owns operations on its contents, such as memory_store.add(), memory_store.get("memory-id"), memory_store.list(), and memory_store.search(), or session_store.add(), session_store.get("session-id"), and session_store.list(). Returned memories, sessions, and stores own their update() and delete() operations.

All list() methods return iterators that automatically consume server pages. List page_size and search limit values must be between 1 and 100. session.list_items() also auto-pages. session.fork(...) creates an independent copy, optionally through a specific item. Deleting a session with descendants requires session.delete(force=True) to cascade the deletion.

The resource layer intentionally does not mirror every API method. Its private transport will be replaced by the generated WorkspaceClient.mason service when that is released, without changing this public surface. Deployment, sandbox, tracing, and the existing CLI commands remain separate.

Runtime

DurableAgentServer runs your agent through one HTTP API for synchronous, streaming, and background invocations. Register an @app.invoke handler, publish progress with await context.emit(event), and return a JSON result. You can also add your own FastAPI endpoints.

Start from a template, edit the agent code in agent/, and run it locally before deploying:

agentbricks init my-agent --framework langgraph --server agentbricks --profile <profile>
cd my-agent
agentbricks dev
# Stop the local server when ready to deploy.
agentbricks --profile <profile> deploy my-agent

Use --framework openai for OpenAI Agents. Templates keep agent code separate from the runtime adapter and declare default Session and Memory Store bindings in agent.toml.

Each managed run is an invocation. Send a client-generated UUID id and your agent's input:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "support-case-123",
  "input": {"messages": [{"role": "user", "content": "Hello"}]},
  "background": true,
  "stream": true
}

The optional top-level session_id groups invocations into one application session. It is distinct from the invocation id and from the X-Routing-Key sticky-routing header.

Endpoint	Behavior
POST /api/invocations	Defaults to synchronous execution: 200 with the result under output. stream: true returns SSE events. background: true returns 202 with a status URL; adding stream: true also includes an events URL.
GET /api/invocations/{id}	Returns the invocation status and, when completed, its output.
GET /api/invocations/{id}/events?after={cursor}	Streams events after the last received event ID, allowing clients to reconnect.

The UUID also acts as an idempotency key: repeating the same request reuses the existing invocation while its record is retained; using the ID for a different request returns 409.

agentbricks dev keeps execution state in process and loses it on restart. For projects with [agent].server = "agentbricks", agentbricks deploy provisions a persistent Runtime Store for requests, status, events, and results. Register @app.recover to restart interrupted app-auth work after worker failures. Recovery is at-least-once, so external side effects must be idempotent. Session and Memory Stores separately preserve the state used by your agent.

The managed path uses the internal Runtime Store API to create a dedicated database in the workspace's shared Lakebase project and give the app SP ownership. The managed runtime initializes its schema and tables; no manual Lakebase grant or Postgres app-resource attachment is needed. Backend selection is an internal rollout detail, not a user-facing setting; the current implementation retains the legacy per-app Lakebase project by default. Once enabled, redeploy reads the stored backend and verifies the app identity, and agentbricks deployments delete removes the managed store before deleting the app. The switch does not migrate existing deployments between backends. Managed cleanup errors retain the app for retry. Direct app deletion bypasses managed store cleanup.

For a tool using auth = "user", the Runtime Store still records token-free invocation state, events, and results. The forwarded user credential remains process-local for the active attempt and is never written to the Runtime Store. A replacement attempt after failure recovery stops with MCP_USER_AUTH_RECOVERY_UNSUPPORTED because the original request credential is no longer present.

Use server = "custom" to deploy your own HTTP server without provisioning a Runtime Store. Changing the server type of an existing deployment is not supported. To use a different server, scaffold a new project with the desired agentbricks init --server option and deploy it under a new name. See the runtime guide for agent hooks, full API examples, and recovery behavior.

Memory and sessions

To hold context, an agent needs two kinds of state: the state of the interaction it is handling right now, and the durable knowledge it carries from one conversation to the next. Databricks provides a fully managed store for each, both backed by Lakebase and usable from agents built on any framework:

• Managed agent sessions store an agent's session state: the state an agent or framework keeps for one interaction. Most commonly this is the conversation history (the ordered transcript of messages, tool calls, and results), but it can be any state a framework persists, such as a LangGraph graph. The agent reads it at the start of a turn and appends to it as the interaction runs.
• Managed agent memory stores durable facts, preferences, and decisions that an agent recalls in later, separate conversations, retrieved by semantic search.

The examples below use the AgentKitClient Python SDK; the same operations are available as agentbricks sessions / agentbricks memory CLI commands.

Sessions

A session store holds sessions, and each session holds an ordered list of session items. A session is one interaction — typically a conversation thread — grouped under an actor_id (who it belongs to; set this from trusted application context, never a model- or user-supplied value) and identified by a caller-chosen session_id (the service generates one if you omit it). Each item is an opaque, JSON-compatible data value — a message, tool call, result, or reasoning block — that Databricks stores and returns verbatim, in order, and never mutates once appended.

Create a store, start a session, append the conversation's turns, and read the history back on a later request:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient())

session_store = agentkit.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

# On a later turn, reload the session and read its full history in order.
session = session_store.get("case-456")
history = [item.data for item in session.list_items()]  # list_items auto-pages

A session can be forked into an independent branch: a new session seeded with the original's history, linked back to its origin by parent_session_id. Fork the full history, or only up to a specific item, to explore an alternate continuation without disturbing the original thread:

branch = session.fork(actor_id="customer-123")  # add up_to_item_id=... to branch up to one item

Deleting a session that has such descendants requires session.delete(force=True) to cascade.

In an agent configured with server = "agentbricks", you don't call these directly — the framework adapter reads and appends session state for you. With LangGraph, pass checkpointer() when you build the agent and scope each run with thread_config(session_id); the OpenAI Agents adapter exposes the same as session_store(session_id):

from databricks_agentkit.langgraph import checkpointer, thread_config

agent = create_agent(model=..., tools=[...], checkpointer=checkpointer())
result = await agent.ainvoke(inputs, config=thread_config(session_id))

Memory

A memory store holds memory entries. Each entry is a free-form content string plus a short description used for retrieval, keyed by three fields: actor_id (whose memory it is — set from trusted application context, never a model- or user-supplied value), path (a filesystem-like key within an actor, such as /preferences/response-style.md), and an optional session_id (the session an entry came from, for provenance). An entry is uniquely identified by its actor_id, path, and optional session_id.

Write an entry when the agent learns something durable, then recall it in a later, separate conversation with a natural-language search — results are ranked by full-text (BM25) relevance, up to 100 entries, with no pagination or vector similarity:

from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

agentkit = AgentKitClient(WorkspaceClient())

memory_store = agentkit.memory_stores.create("support-agent-memory")
memory_store.add(
    actor_id="user-123",
    path="/preferences/communication.md",
    content="Prefers email over phone. Timezone: PST.",
    description="User 123 communication preferences",
)

# In a later, separate conversation, recall what the agent knows about this user.
results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

To browse rather than search, memory_store.list(actor_id=..., path_prefix=...) returns entries directly.

In an agent configured with server = "agentbricks", add the memory tools so the model can read and write memory during a run. memory_tools(actor) exposes remember and recall bound to one actor's partition; it resolves the store from the [memory_store] binding, carried to the runtime by the AGENT_MEMORY_STORE env var that agentbricks deploy injects, and returns no tools when no store is set, so the agent runs unchanged. That "no store set" path is also how it runs under agentbricks dev, which runs locally: memory is off there (the store is provisioned and used only at deploy). The OpenAI Agents adapter exposes the same as memory_tools():

from databricks_agentkit.langgraph import memory_tools

agent = create_agent(model=..., tools=[*your_tools, *memory_tools(actor)])

actor_id partitions data; it is not access control. Both stores are workspace-scoped and authorized at the store level, so any principal that can reach a store can read and write every actor's entries. For strict isolation between tenants or users, use a separate store per boundary. Grant another principal — such as your app's service principal — access with session_store.grant_permission(principal_id) or memory_store.grant_permission(principal_id); agentbricks deploy does this for the deployed app automatically.

Declaring and provisioning stores

For a deployed agent, agent.toml declares which stores it uses and agentbricks deploy provisions them — you don't create stores by hand. agentbricks init declares a default memory and session store named from the project; override those names, point at stores you already have, or let deploy create them:

# Scaffold a project with default memory and session stores declared in agent.toml.
agentbricks init my-agent

# Override the declared store names at init time.
agentbricks init my-agent --memory-store support-agent-memory --session-store support-agent-sessions

# Or point an existing project at specific stores (edits agent.toml only; creates nothing).
agentbricks sessions bind support-agent-sessions
agentbricks memory bind support-agent-memory

# deploy creates any declared-but-missing store and grants the app's service principal access.
agentbricks deploy my-agent

Memory and session stores are independent resources: deleting one never affects the other. For projects with agent.toml, unbinding either store removes its declaration; the next deploy removes the corresponding AGENT_MEMORY_STORE or AGENT_SESSION_STORE entry from app.yaml. Unbinding does not delete the store or revoke an existing grant to the App's service principal. If access must be revoked, coordinate that separately with the store owner or workspace admin.

Commands

For the full command reference - every command, subcommand, argument, and option, in table form - see cli.md. The tree below is a quick overview.

agentbricks [-p <profile>] [-o text|json]
  login        [--profile P]
  logout
  init         [--framework openai|langgraph] [--server agentbricks|custom]
               [--disable-chat-app]
               [--memory-store NAME] [--session-store NAME]
               [--existing] [--profile P] [directory]
  doctor       [directory]
  dev          [--source PATH] [--prepare-environment] [--app-port PORT]
  memory
    bind         STORE [--source PATH]
    unbind       [--source PATH]
    stores     create | list | get | update | delete
    entries    create | get | list | search | update | delete
  sessions     create | list | get | update | delete | fork
    bind         STORE [--source PATH]
    unbind       [--source PATH]
    stores     create | list | get | update | delete
    items      list | append | pop | clear
  tracing
    bind       (--experiment-name NAME | --experiment-id ID) [--source PATH]
    unbind     [--source PATH]
    list | get [--experiment-name NAME | --experiment-id ID] [--source PATH]
  tools
    add sandbox      --scope SCOPE [--scope SCOPE ...]
                     [--no-databricks-access-token-included] [--source PATH]
    add mcp          SERVICE [--name NAME] [--source PATH]
    add uc-function  FUNCTION [--name NAME] [--source PATH]
    add genie-one    [--name NAME] [--auth user|app] [--source PATH]
    add genie-agent  SPACE_ID [--name NAME] [--auth user|app] [--source PATH]
    list             [--kind sandbox|mcp|uc-function|genie-one|genie-agent]
                     [--schema CATALOG.SCHEMA]
    remove           TOOL_ID [MCP_SERVICE] [--source PATH]
  deploy       [<name>] [--source PATH] [--instances N]
  deployments  list | get | logs | start | stop | delete
  endpoint
    invoke      [APP] --path PATH [--url URL] [--json JSON] [--sse]

Bring an existing agent

From the existing project, prepare a migration for your coding agent:

agentbricks init --framework langgraph --existing .
agentbricks init --framework openai --existing .

Before or after the conversion, inspect its progress without changing the repository or contacting Databricks:

agentbricks doctor .
agentbricks -o json doctor .

Doctor exits 0 only when the project has a valid Agent Bricks manifest and matching project metadata, uses the Agent Bricks server, declares the framework-appropriate databricks-agentbricks extra and a non-empty app.yaml command, constructs DurableAgentServer with an invoke hook, and calls a recognized adapter for the selected framework in production Python source. Test, example, and old/stale directories do not count as source evidence. A failed report is the normal result for a project that still needs migration; run agentbricks init --framework <framework_name> --existing <directory> with the appropriate framework to prepare the migration instructions. Doctor never imports or executes the target's source, and a bounded source scan that exceeds a limit is reported while the evidence it already found still counts. Its findings are static repository evidence, not proof that the configured startup command executes the files it finds.

This writes agent-bricks-migrate/ containing a skill, a prompt to paste into your coding agent, references/migration.json, and a reference project generated from the templates bundled with the installed CLI. The bundle sits outside any single agent's configuration directory; .claude/skills/ and .agent/skills/ each receive a small skill that points at it, so Claude Code, Codex, and similar tools discover the same instructions without duplicating the reference. Agent Bricks CLI prepares the instructions; the coding agent performs and verifies the conversion. Init leaves application source, dependencies, .env, and existing .agentbricks/project.toml configuration intact and refuses to overwrite existing migration files.

The bundle is scaffolding for the migration, not part of the application: delete agent-bricks-migrate/ and the two pointer skills once the conversion is done, and keep them out of commits meanwhile.

The skill follows the shared managed-runtime contract for the selected framework, included in new projects and migration references: LangGraph or OpenAI Agents SDK. It explicitly handles existing history, custom state and output, recovery, and client/session contracts. For LangGraph, switching checkpointers does not migrate old conversations (likewise, the OpenAI Agents SDK keeps prior Session transcripts and RunState behind); unresolved transitions require a user decision.

The reference honors --disable-chat-app, --memory-store, --session-store, and the selected profile. These are migration intent; init does not provision resources or change the existing application. Migration supports LangGraph and the OpenAI Agents SDK with the managed server (server = "agentbricks"); --server custom is not supported for --existing.

Invoke HTTP endpoints

agentbricks endpoint invoke is a low-level HTTP command. It resolves and authenticates a deployed Databricks App, or targets localhost and arbitrary servers through --url. It does not assume an agent protocol: provide the method, path, query parameters, and complete JSON body required by the server.

agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'

agentbricks endpoint invoke --url http://localhost:8000 \
  --path /api/invocations \
  --json '{"id":"00000000-0000-4000-8000-000000000001","session_id":"support-case-123","input":[{"role":"user","content":"Hello"}]}'

The JSON body remains explicit even for generated agents. For example, managed runtime agents require a client-generated invocation ID, and streaming servers require their own streaming field plus --sse so the CLI consumes the response as Server-Sent Events.

SESSION_ID=$(uuidgen)
INVOCATION_ID=$(uuidgen)
agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --routing-key "$SESSION_ID" \
  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Run the report\"}]}"

INVOCATION_ID=$(uuidgen)
agentbricks --profile <profile> endpoint invoke agent-bricks-my-agent \
  --path /api/invocations \
  --routing-key "$SESSION_ID" \
  --sse \
  --json "{\"id\":\"$INVOCATION_ID\",\"session_id\":\"$SESSION_ID\",\"input\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":true}"

--routing-key keeps a session on one app replica (sticky routing): set it to your stable session id and it is sent verbatim in the X-Routing-Key request header. It is routing only and is never used as the session id - put the session id at the top level of the --json body for session continuity. This also works with a direct App URL and with the generated runtime on localhost. OAuth and session headers are managed by the runtime; arbitrary custom request headers are intentionally not exposed by this command.

Command help

Use the conventional help flag at any command level. Every command's help includes runnable examples:

agentbricks --help
agentbricks deploy --help
agentbricks sessions items append --help

Agent tools

For projects with [agent].server = "agentbricks" (the default from agentbricks init), agent.toml is the declarative source of truth for Databricks-managed infrastructure: the Runtime Store, sandbox, managed MCP, Genie and Unity Catalog function bindings, plus memory and session resources. agentbricks tools add updates only this file; direct TOML edits have the same behavior. Both managed-server framework adapters read the managed bindings at runtime without generating or patching agent source:

agentbricks tools add sandbox --scope volume:main.data.files
agentbricks tools add mcp system.ai.web_search
agentbricks tools add uc-function catalog.schema.lookup_ticket
agentbricks tools add genie-one
agentbricks tools add genie-agent SPACE_ID
agentbricks tools remove mcp system.ai.web_search
agentbricks tools list

Managed tool identity and migration

agentbricks tools add mcp, agentbricks tools add sandbox, agentbricks tools add genie-one, and agentbricks tools add genie-agent write explicit auth = "user" by default. Use --auth app for the App service principal instead. This field is on the tool entry, not inside source or policy:

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

Direct UC-function bindings remain app/default identity and do not accept --auth user. Managed-tool add commands write the selected identity to agent.toml; inspect that manifest to review configured bindings. Missing legacy auth continues to mean App identity at runtime; it is never silently upgraded to user identity.

Automatic App-identity access on deploy

agentbricks deploy reconciles least-privilege access for resources explicitly declared by App/default identity tool bindings. It skips every auth = "user" binding because those calls use the request user's permissions instead of the App service principal.

Explicit agent.toml resource	Automatic App service-principal access
UC function	Apps uc_securable: FUNCTION / EXECUTE
Genie Agent space	Apps genie_space: CAN_RUN
Sandbox volume scope	Apps uc_securable: VOLUME / READ_VOLUME or WRITE_VOLUME
External MCP service	Unity Catalog: effective EXECUTE plus USE_SCHEMA and USE_CATALOG on its named parents
Built-in system.ai MCP service, including Sandbox and Genie One	Platform-managed access defaults; Agent Bricks does not mutate system securables

Native Genie One has no resource identifier in its binding, so it does not add a resource-specific grant. Use a Genie Agent binding when the App identity should be scoped to one explicit Genie Space.

Apps-backed tool resources are named deterministically and reconciled to the manifest on each deploy: removing a binding removes that Agent Bricks-owned Apps resource while preserving Runtime Store, tracing, and user-owned resources. MCP grants are additive in this release because their permission APIs do not expose trustworthy Agent Bricks ownership metadata; removing those bindings does not revoke an independently valid grant.

Only direct resources are automatic. Agent Bricks never discovers or grants tables and warehouses used by a Genie Space, objects called by a UC function, or resources wrapped by an MCP service. Grant those transitive dependencies manually when the called service uses the App identity. If any required direct grant cannot be read, applied, or verified, deploy stops before source upload and leaves the currently deployed version untouched.

DurableAgentServer derives its request-auth policy directly from the managed tool bindings in agent.toml. Projects do not maintain a separate request-auth contract marker: a managed tool with auth = "user" requires a transient request-user credential. Code-first tools can declare any additional API scopes that Agent Bricks cannot infer from Python:

[auth.user]
required = true
additional_api_scopes = ["sql"]

additional_api_scopes is additive: deploy unions it with scopes inferred from managed bindings, deduplicates the result, and preserves unrelated scopes already configured on the App. Scope names are not restricted to a client-side allowlist; Databricks Apps validates whether a requested scope is supported. Entries must be non-empty strings without surrounding whitespace or control characters, and a non-empty list requires required = true. This request-auth contract is supported only with [agent].server = "agentbricks".

Generated framework adapters pass the request-bound resolver to agent construction. A code-first tool should obtain its user client from that resolver inside the active invocation rather than creating or persisting a user credential:

from langchain_core.tools import tool


def sql_tools(workspace_client_for):
    @tool
    def run_statement(statement: str) -> str:
        client = workspace_client_for("user")
        response = client.statement_execution.execute_statement(
            warehouse_id="...",
            statement=statement,
        )
        return str(response.result)

    return [run_statement]

The resolver is request-bound and closes after the attempt. Agent Bricks does not inject it into arbitrary auto-discovered decorated tools; build those tools from the resolver passed to the generated request-aware agent function.

Request-user invocations use the same synchronous, streaming, background, status, event-replay, and idempotency APIs as app-auth invocations. The Runtime Store records only token-free request state, events, and results. The forwarded credential stays process-local for the active first attempt and closes when that attempt completes, fails, or is cancelled. A replacement attempt after failure recovery stops with MCP_USER_AUTH_RECOVERY_UNSUPPORTED because no user credential is available; neither the invoke nor recovery handler runs for that attempt.

Before deploying user-auth tools from an older project, migrate its request handler and framework adapter to the current request-auth-aware DurableAgentServer template, then explicitly choose user or app on every managed MCP, sandbox, or Genie entry. Changing agent.toml alone does not upgrade copied Python adapter code. Outdated adapters fail closed rather than silently using App identity. App-only legacy projects and generic bring-your-own source directories keep the existing path.

Deploy derives Apps user scopes from explicit auth = "user" bindings and unions them with [auth.user].additional_api_scopes:

Binding	Requested Apps scopes
Managed MCP (governed ingress)	ai-gateway
system.ai.dbsql	ai-gateway, sql
system.ai.genie_one_mcp	ai-gateway, genie
Sandbox with a Volume downscope	ai-gateway, files
First-class Genie One or Genie Agent	genie
Sandbox with token injection	ai-gateway, workspace.workspace
Sandbox with token injection disabled	ai-gateway

For example, bind Genie tools in a current project with server = "agentbricks":

agentbricks tools add mcp system.ai.genie_one_mcp --auth user
agentbricks tools add genie-agent SPACE_ID --auth user

Mixed bindings and explicit additions request the union. App-auth and legacy bindings add no user scopes. These are explicit service-consent scopes, not a claim that gateway access alone authorizes the downstream resource. OAuth consent does not grant Unity Catalog privileges: the user still needs access to the configured Genie Space and its underlying data.

For a new App, deploy explicitly enables user-token forwarding and includes these scopes in the initial typed SDK create request before uploading source. An existing App that is missing a required scope needs one-time explicit permission:

agentbricks --profile my-workspace deploy my-agent --allow-user-scope-update

The system.ai.dbsql managed MCP additionally requests the Apps sql user scope. This is full SQL API consent, not sql:restricted-query; read-only enforcement remains the service policy plus the requesting user's Unity Catalog grants. DBSQL does not use Databricks Connect.

When a user-auth sandbox has databricks_access_token_included = true, it requests the Apps workspace.workspace user scope so the injected credential can call workspace APIs. A sandbox binding with a Volume downscope additionally requests the Apps files user scope. OAuth consent does not grant Volume access: the requesting user still needs the corresponding Unity Catalog privileges, and the sandbox downscope remains authoritative. A sandbox binding with token injection disabled does not request workspace.workspace; its other resource-derived scopes still apply. Databricks Apps rejects the legacy bare workspace scope, so Agent Bricks requests workspace.workspace. These scopes are requested only for auth = "user"; auth = "app" uses the App service principal's permissions instead.

Review the target App's scopes and coordinate with its other owners before allowing the update. Once those scopes are present, later deploys do not need the flag. The CLI preserves unrelated scopes, updates only user scopes and any explicitly requested instance counts, and checks requested and effective scopes before source rollout. It checks for scope changes since preflight, but Apps read/write is not atomic; this is not a lock or a compare-and-swap guarantee. Polling is bounded and a mismatch stops source deployment. Users may need to sign out and re-consent after changing scopes; effective-scope verification does not refresh an existing user's consent.

Apps may report iam.access-control:read and iam.current-user:read as implicit effective scopes. The CLI permits these platform defaults during verification but does not request them as configurable scopes. Explicitly disabled user-token forwarding stops deployment; enable forwarding and restart the App compute before retrying.

Removing a tool or switching back to app-only auth does not remove Apps scopes. Remove unneeded scopes explicitly in Databricks Apps, and verify both configured and effective scopes before declaring removal complete. The CLI does not send empty-list scope updates: the SDK's App.as_dict() omits empty lists, so that would not prove removal succeeded. No scopes are managed for generic bring-your-own apps without this managed user contract.

App-auth tools execute with workload privileges. Restrict App CAN USE to callers trusted for all App-auth tools, or deploy those tools separately. Models, custom MCP servers, Memory/Session Stores, and tracing keep their existing credentials.

For MCP services, the remove command accepts the same service name as the add command. You can also remove any binding by its id in agent.toml, for example agentbricks tools remove web_search. Every successful add (including an already-configured no-op) points you to the target project's agent.toml to review configured managed tools and MCP bindings. With --source, the message points to that project's file. JSON add output includes its path in manifest.

agentbricks tools list discovers available integrations to add, not configured bindings. By default it shows built-in add recipes and caller-visible MCP Services in system.ai. A recipe may still need your resources: sandbox scopes, a concrete UC function name, or a Genie Space ID. Genie One needs no additional argument. system.ai.sandbox is represented by its scoped recipe rather than a second unscoped add command. The list does not enumerate every workspace schema, individual operations inside MCP services, or custom Python tools.

agentbricks tools add mcp looks up the service in the selected workspace before writing agent.toml. Use agentbricks --profile <profile> tools add mcp <service> to select a workspace. A missing service or failed lookup (including authentication or permission errors) leaves the project unchanged. This checks service metadata access, not whether every tool can be executed at runtime. Removing local bindings does not require workspace access.

agentbricks tools list
agentbricks tools list --kind mcp
agentbricks tools list --kind mcp --schema main.tools
agentbricks tools list --kind sandbox
agentbricks tools list --kind genie-one
agentbricks tools list --kind genie-agent
agentbricks --output json tools list

No agent project is required for discovery. MCP discovery uses your Databricks profile; the sandbox, uc-function, genie-one, and genie-agent kind filters show local recipes without authentication. --schema requires --kind mcp and replaces the default system.ai scope. An API/authentication failure returns nonzero and marks discovery incomplete, while retaining local recipes; it is not reported as an empty successful discovery. Listing metadata does not verify runtime execution permissions.

Migration: the former configured tools list view and its --source option are removed. Read agent.toml (its [[tools]] entries) to inspect configured bindings. Discovery JSON uses schema_version: 2, with available_tools (name, kind, add_command), mcp_schema (null for local-only recipes), complete, and errors. Replace old scripts that read configured-list JSON with TOML inspection. Replace agentbricks mcp list [--schema catalog.schema] with agentbricks tools list --kind mcp [--schema catalog.schema]; the former command is removed. Use agentbricks tools list --help for the new discovery contract.

Read-only live discovery can be checked against the installed wheel without creating a project or deploying an agent:

AGENTBRICKS_E2E_PROFILE=<profile> .venv-functional/bin/pytest tests/e2e/tool_discovery_test.py -v

The live checks compare default and MCP-filtered discovery with the compatibility service list. Set AGENTBRICKS_E2E_SCHEMA=catalog.schema to exercise an additional schema. The installed CLI's local add/review/remove flows and all updated help pages are covered by tests/functional/cli_smoke_test.py.

In managed-server templates, custom Python tools are code-first. Write them with the framework's native decorator in agent/tools/: LangGraph uses @tool, while OpenAI Agents uses @function_tool. The templates auto-discover decorated tools from that package and add them to the agent; there is no CLI command or agent.toml entry to keep in sync. Customer-managed MCP servers are likewise ordinary code in agent/mcps.py and are joined with the managed bindings by mcp_tools(...) or mcp_servers(...).

Projects created with --server custom do not auto-discover agent/tools/ or load managed tool bindings from agent.toml, so agentbricks tools add rejects those projects. Wire framework-native Python tools and MCP servers directly in agent/agent.py instead.

If a manifest with server = "agentbricks" contains source = { kind = "python", ... }, remove that [[tools]] entry; the decorated tool in agent/tools/ remains active. agentbricks dev and agentbricks deploy do not generate or patch Python tool code, and do not alter the manifest's [[tools]] bindings.

Sandbox scopes support volumes only and default to read-only access. Repeat --scope to allow more than one volume, use volume:catalog.schema.volume, and use --permission read_write only when the agent needs writes. Every sandbox call carries this fixed downscope in MCP _meta, outside the tool arguments controlled by the model. New sandbox bindings also expose the selected Databricks credential to sandbox code by default:

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "volume:main.data.files", permission = "read_only" }], databricks_access_token_included = true }

Table sandbox scopes are not supported yet because Databricks Connect does not support table downscoping. Workspace sandbox scopes are also not supported yet; they have not been validated against a live workspace. Use a volume instead. Existing table: and workspace: entries must be removed from agent.toml before using agentbricks dev or agentbricks deploy.

The table implementation is retained behind a disabled code-level gate so it can be enabled when Databricks Connect supports table downscoping. There is no CLI option to bypass that gate.

With databricks_access_token_included = true, the sandbox receives DATABRICKS_HOST, a short-lived DATABRICKS_TOKEN, and DATABRICKS_AUTH_TYPE, so code such as WorkspaceClient().current_user.me() can call workspace APIs. This policy does not choose the identity: auth = "user" uses the request user's OBO credential, while auth = "app" uses the Databricks App service principal. Use --no-databricks-access-token-included when adding a sandbox that does not need workspace API access. Existing manifests that omit databricks_access_token_included remain disabled until explicitly updated.

Genie tools

Genie One and Genie Agent support ship with Agent Bricks CLI, but bindings are opt-in, like sandbox tools. Installing the current databricks-agentbricks distribution does not configure a Genie Space ID or enable a Genie binding. Add only the capabilities your agent needs:

agentbricks tools add genie-one --name genie_one --auth user
agentbricks tools add genie-agent SPACE_ID --name genie_agent --auth user
agentbricks tools list --kind genie-one
agentbricks tools list --kind genie-agent
agentbricks tools remove genie_one
agentbricks tools remove genie_agent

--name is optional and defaults to genie_one or genie_agent, respectively. --auth defaults to user; choose --auth app deliberately for App service-principal execution. Existing manifests without auth preserve App/default identity. Both add commands and remove accept --source PATH to select a project instead of the current directory. Discovery needs no project; read that project's agent.toml to inspect configured bindings. For scripted output, put the global -o json option before tools, as in agentbricks -o json tools add genie-one --source ./my-agent. Adding a binding is offline: it updates agent.toml without contacting Genie or checking permissions. The corresponding sources are:

[[tools]]
id = "genie_one"
auth = "user"
source = { kind = "genie_one" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<your-space-id>" }

Replace SPACE_ID or <your-space-id> with an existing space's 32-character lowercase hexadecimal ID. genie-one connects to the workspace-wide MCP endpoint https://<workspace-hostname>/api/2.0/mcp/genie, without a space suffix. genie-agent uses the native Genie Chat-mode conversation API through the Databricks SDK, not the streaming Agent-mode API or the per-space MCP endpoint.

Each native binding exposes {id}_ask, {id}_poll, and {id}_query_result, where {id} is its binding name. Ask accepts an optional conversation_id for follow-ups. Ask and poll share a 120-second budget per call, including client setup and submission. If the response is still running, they return timed_out with the conversation and message IDs so the caller can poll again. If submission times out before a message ID is received, ask returns INDETERMINATE_SUBMISSION: the request may still complete, so do not resubmit automatically. NOT_SUBMITTED means client setup timed out before sending the question. Query results include the first 100 rows, column schema, a truncation indicator, and a deep link to the conversation.

Both framework modules, databricks_agentkit.langgraph and databricks_agentkit.openai, export genie_tools(). New managed-server templates (server = "agentbricks") use it automatically for native Genie Agent bindings; Genie One uses the existing managed MCP helpers. In an existing project with server = "agentbricks", import genie_tools from your framework module and add *genie_tools() to the agent's existing tool list. The CLI does not patch existing Python code.

Both paths use Databricks authentication and the routed workspace. Genie One requires the Managed MCP Servers workspace preview; delegated access requires the genie OAuth scope. The effective caller needs access to the data, the SQL warehouse, and the selected Genie space where applicable. Agent Bricks CLI does not grant permissions or promise a service-principal fallback when caller credentials lack access. An offline add succeeding does not establish runtime access.

The opt-in live tests exercise both frameworks against the configured workspace and an existing Genie space. From integrations/agentbricks, with both framework extras installed:

DATABRICKS_CONFIG_PROFILE=my-workspace RUN_AGENTBRICKS_GENIE_TESTS=1 \
  AGENTBRICKS_GENIE_SPACE_ID=SPACE_ID \
  uv run pytest tests/integration_tests/genie_tools_test.py

By default they ask for the row count of samples.nyctaxi.trips. Set AGENTBRICKS_GENIE_QUESTION for another dataset and AGENTBRICKS_GENIE_EXPECTED_VALUE to assert a known result cell.

Initialize the chat app demo

The chat app is a LangGraph-specific init overlay, not a command that mutates an existing project. It is included by default for --framework langgraph; pass --disable-chat-app to scaffold the API-only backend instead.

agentbricks init --framework langgraph \
  --profile <profile> \
  ./my-agent
cd ./my-agent
agentbricks dev

The chat app includes synchronous, SSE streaming, background polling, Session Store, Memory Store, and HITL resume UI. The framework-specific overlay adds ui/, runtime/ui.py, the UI-enabled runtime/main.py, and UI tests.

For the full deployed demo, bind both managed stores, then deploy:

agentbricks sessions bind agent-bricks-demo-sessions
agentbricks memory bind agent-bricks-demo-memory
agentbricks --profile <profile> deploy agent-bricks-agent-demo --source .

(bind declares the store name in agent.toml; agentbricks deploy creates any declared-but-missing store and grants the app's service principal access to it. The memory store id flows to the runtime via the AGENT_MEMORY_STORE env var that deploy injects; agentbricks dev runs locally with memory off and does not inject it. The id is not persisted in agent.toml.)

The chat UI generates a stable application session UUID in browser local storage, sends it as the invocation's top-level session_id, and creates a fresh invocation UUID per turn. The chat app also sends this session UUID in the X-Routing-Key request header, which is used verbatim to pin the session to one app replica (it must be non-blank and no more than 128 UTF-8 bytes). The header is neither authentication nor the template's application session state; it is independent sticky-routing plumbing.

The generated README.md documents every request the client makes: config discovery, sync and SSE invocations, background submission and polling, session transcript loading, HITL resume, and memory entry operations. Capability colors are automatic from /api/demo/config; only the sync/streaming/background transport selector is manual.

Contributing

Developing Agent Bricks CLI (agentbricks), AgentKit, the runtime, and templates - plus the local dev loop and how to test unreleased changes on agentbricks dev and agentbricks deploy, is covered in CONTRIBUTING.md.