Agent Bricks CLI

info

Beta

Esse recurso está em Beta. Nenhuma configuração de workspace é necessária para ativá-lo. Instale a CLI do Agent Bricks para começar.

A CLI do Agent Bricks (databricks-agentbricks) é uma ferramenta de linha de comando do Databricks para desenvolvedores que criam e implantam agentes personalizados em código.

A CLI do Agent Bricks é um caminho voltado para código para criar agentes personalizados a partir do terminal. A CLI do Agent Bricks cria a estrutura de um projeto usando um framework integrado baseado nas melhores práticas da Databricks. Em seguida, ele pode executar o projeto localmente para testes e implantá-lo no runtime de agentes da Databricks. A CLI permite ir de um diretório vazio a um agente implantado sem configurar manualmente runtime, ferramentas, memória e recursos gerenciados. Para outras formas de criar agentes personalizados, incluindo o fluxo de trabalho baseado em aplicativo, consulte Executar agentes no Databricks Apps usando o servidor de agentes herdado.

Pré-requisitos

• O Databricks CLI, instalado e disponível no seu path.

• Python 3.10 ou acima, com pip.

• Instale a CLI do Agent Bricks:

  Bash

  pip install databricks-agentbricks

O ciclo de vida da Agent Bricks CLI

A CLI do Agent Bricks cria a estrutura de um diretório local de código de agente implantável a partir de um modelo padrão, com o runtime, testes e uma UI de chat opcional já configurados. Você escreve a lógica do aplicativo (modelo, ferramentas e prompts), e a CLI gerencia a execução local e a implantação na infraestrutura do Databricks.

agent.toml é a fonte declarativa da verdade para todos os recursos gerenciados pelo Databricks dos quais seu agente depende: associações de ferramentas (sandbox de dados, serviços do Model Context Protocol (MCP) gerenciados, funções do Unity Catalog) e recursos de memória, sessão e rastreamento. agentbricks deploy o lê para provisionar e conectar tudo, portanto, o arquivo, e não o código de configuração escrito manualmente, é o que é implantado.

Os três comandos que levam um agente de um diretório em branco até a produção:

• agentbricks init estrutura o projeto a partir de um padrão empacotado, opcionalmente populando um arquivo .env com um perfil do Databricks para que o projeto seja executado imediatamente.
• agentbricks dev executa o agente localmente em relação ao servindo modelo do Databricks para que você possa testá-lo antes de implantá-lo.
• agentbricks deploy faz o provisionamento dos recursos declarados em agent.toml e implanta o agente no runtime do agente do Databricks.

nota

Você também pode adicionar ferramentas e associar armazenamentos de memória e de sessão a qualquer momento, e não apenas na inicialização. Use agentbricks tools add, agentbricks memory bind e agentbricks sessions bind para atualizar a configuração do seu agente entre qualquer uma dessas etapas.

Recursos da CLI do Agent Bricks

Capacidade	Descrição
Acesso ao modelo	A CLI do Agent Bricks provisiona automaticamente o acesso ao modelo para que seu agente possa chamar um modelo atendido pelo Databricks sem gerenciar credenciais ou endpoints. Consulte as APIs do Foundation Model do Databricks.
Memória gerenciada	Memórias de longo prazo que um agente pode gravar e pesquisar, particionadas por ator e apoiadas por armazenamentos gerenciados. Use a memória para persistir fatos e preferências em várias sessões e use agentbricks memory pipeline para extrair memórias de um armazenamento de sessão. Veja Memória do agente e Pipelines de memória do agente.
Sessões gerenciadas	Transcrições de conversas mantidas em armazenamentos de sessão gerenciados e particionadas por ator, com suporte para bifurcar sessões em cópias independentes. Veja Sessões de agente.
Ferramentas	Databricks-managed capabilities declared in agent.toml: a downscoped Unity Catalog sandbox, a Databricks-managed MCP serviço, or a Unity Catalog function. Custom Python tools are written directly in the project code. See MCPs.
Rastreamento	O rastreamento do MLflow ativado por default, roteando os rastreamentos de cada execução para um experimento do MLflow por projeto para depuração e monitoramento. Consulte Visão geral do rastreamento.
Implantação	Implanta um agente no runtime do agente do Databricks, concede ao service principal do agente acesso aos armazenamentos vinculados e gerencia o ciclo de vida da implantação.

Capacidade	Descrição
Acesso ao modelo	A CLI do Agent Bricks provisiona automaticamente o acesso ao modelo para que seu agente possa chamar um modelo atendido pelo Databricks sem gerenciar credenciais ou endpoints. Consulte as APIs do Foundation Model do Databricks.
Memória gerenciada	Memórias de longo prazo que um agente pode gravar e pesquisar, particionadas por ator e apoiadas por armazenamentos gerenciados. Use a memória para persistir fatos e preferências em várias sessões e use agentbricks memory pipeline para extrair memórias de um armazenamento de sessão. Veja Memória do agente e Pipelines de memória do agente.
Sessões gerenciadas	Transcrições de conversas mantidas em armazenamentos de sessão gerenciados e particionadas por ator, com suporte para bifurcar sessões em cópias independentes. Veja Sessões de agente.
Ferramentas	Databricks-managed capabilities declared in agent.toml: a downscoped Unity Catalog sandbox, a Databricks-managed MCP serviço, or a Unity Catalog function. Custom Python tools are written directly in the project code. See MCPs.
Rastreamento	O rastreamento do MLflow ativado por default, roteando os rastreamentos de cada execução para um experimento do MLflow por projeto para depuração e monitoramento. Consulte Visão geral do rastreamento.
Implantação	Implanta um agente no runtime do agente do Databricks, concede ao service principal do agente acesso aos armazenamentos vinculados e gerencia o ciclo de vida da implantação.

Criar um novo agente

Passo 1: Autenticar com o OAuth e salvar um perfil

A CLI do Agent Bricks usa a autenticação da CLI do Databricks. Autentique-se no seu workspace com o OAuth (user-to-machine) e salve as credenciais como um perfil nomeado.

Para começar o fluxo de OAuth, execute o seguinte comando, substituindo o host pela URL do seu workspace. O comando abre um navegador para concluir o login e, em seguida, grava o perfil em ~/.databrickscfg:

Bash

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

Para definir esse perfil como o default da CLI para que comandos posteriores possam omitir --profile, execute o seguinte comando:

Bash

agentbricks login --profile <profile>

agentbricks login valida as credenciais do perfil. Se estiverem faltando ou forem rejeitadas, a CLI executa novamente databricks auth login e faz uma nova tentativa.

Passo 2: Estruturar o projeto do agente

Estruture um novo projeto de agente e passe --framework para escolher o padrão. Este exemplo usa o padrão LangGraph, que inclui um aplicativo de chat no navegador:

Bash

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

A CLI fornece um padrão empacotado por framework, e --framework seleciona qual padrão usar na criação: langgraph para o LangGraph ou openai para o SDK de agentes da OpenAI. A CLI grava os recursos gerenciados e as vinculações de ferramentas do projeto em agent.toml e a procedência do modelo em .agentbricks/project.toml. Para criar a estrutura do backend apenas com API sem o aplicativo de chat, adicione --disable-chat-app.

o passo 3: Anexar sessões gerenciadas e armazenamentos de memória

Vincule armazenamentos gerenciados para que seu agente possa persistir o histórico de conversas e a memória de longo prazo. Cada comando registra o nome do armazenamento em agent.toml e cria o armazenamento se ele não existir.

Para vincular um armazenamento de sessões e um armazenamento de memória, execute o seguinte:

Bash

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

Etapa 4: view tracing

O rastreamento está ativado por default. agentbricks init associa um experimento MLflow /Shared/agentbricks_traces/<project> default, e agentbricks dev e agentbricks deploy enviam os rastreamentos de cada execução para ele.

Para listar os rastreamentos após o seu agente ter produzido alguns, execute o seguinte comando:

Bash

agentbricks tracing list

Para vincular um experimento específico do MLflow, execute agentbricks tracing bind --experiment-id <experiment-id>. Para desativar o rastreamento, execute agentbricks tracing unbind.

Passo 5: Executar o agente localmente

Execute o agente em sua máquina para testá-lo antes de implantá-lo.

Bash

agentbricks dev

Isso inicia um servidor local na porta 8000 usando o mesmo comando e ambiente que o runtime do agente do Databricks. O Agent Bricks CLI conecta o agente ao servindo modelo do Databricks para que ele possa chamar o modelo localmente. O padrão define um modelo default como o valor MODEL em agent/agent.py. Para usar um modelo diferente, edite esse valor. Envie solicitações para http://localhost:8000 para interagir com o agente.

Etapa 6: Implantar o agente

Implante o agente no Databricks agent runtime. A CLI provisiona os armazenamentos vinculados, concede ao service principal do agente acesso a eles e realiza a implantação. O agente implantado chama-se agent-bricks-<name>.

Bash

agentbricks deploy my-agent

Quando a implantação for concluída, a CLI retornará a URL da implantação. Abra essa URL para interagir com seu agente ativo, que está conectado automaticamente ao servindo modelo do Databricks. Para gerenciar o implantação posteriormente, use os comandos agentbricks deployments, como agentbricks deployments logs e agentbricks deployments stop.

Traga um agente existente

Se você já criou um agente com o LangGraph ou o OpenAI Agents SDK, use o flag --existing para movê-lo para a CLI do Agent Bricks e DurableAgentServer. A CLI não reescreve seu código. Em vez disso, ela prepara instruções de migração que um agente de codificação, como o Claude Code ou o Codex, segue para converter o projeto.

O passo 1: Preparar a migração

A partir do diretório do projeto do agente, prepare a migração. Passe o framework que o agente usa: langgraph para LangGraph ou openai para o OpenAI Agents SDK.

Bash

agentbricks init --framework langgraph --existing .

The CLI writes an agent-bricks-migrate/ directory that contains the migration instructions, a prompt for your coding agent, and a reference project generated from the CLI's padrões. It also adds skills in .claude/skills/ and .agent/skills/ that point coding agents to the instructions. The comando doesn't change your application code, dependencies, or .env file, and doesn't create any recursos in your Workspace.

o passo 2: Converter o projeto com seu agente de codificação

Paste the prompt from agent-bricks-migrate/ into your coding agent. The coding agent converts the project to use agent.toml and a DurableAgentServer entrypoint, and verifies the conversion.

o passo 3: Check the conversion

Execute agentbricks doctor no diretório do projeto:

Bash

agentbricks doctor .

agentbricks doctor inspeciona os arquivos do projeto sem executar o código ou entrar em contato com o Databricks. Ele é bem-sucedido quando o projeto tem um agent.toml válido, começa o DurableAgentServer com um manipulador de invocação e chama o adaptador para sua estrutura. Um relatório com falha significa que a conversão não terminou.

O passo 4: Limpar, execução e implantar

Exclua agent-bricks-migrate/ e as duas habilidades que apontam para ele, mantendo-os fora dos seus commit. Em seguida, execute o agente com agentbricks dev e implante-o com agentbricks deploy.

Considerações

• --existing dá suporte ao LangGraph e ao OpenAI Agents SDK com DurableAgentServer. Ele não oferece suporte a --server custom.
• A alteração do agente para um armazenamento de sessão gerenciado não move sua história de conversas existente. As instruções de migração solicitam que você decida como lidar com conversas anteriores.
• As opções --disable-chat-app, --memory-store e --session-store moldam o projeto de referência. Eles não criam recursos.

Adicionar ferramentas MCP

Se você criar seu agente com a CLI do Agent Bricks, adicione um serviço MCP system.ai integrado ao seu projeto com agentbricks tools add mcp. O comando verifica se o serviço existe no seu workspace e registra a ferramenta em agent.toml. O agente se conecta à ferramenta em runtime, de modo que você não precisa escrever nenhum código de conexão.

Para listar os MCP serviços que você pode adicionar, execute o seguinte comando:

Bash

agentbricks tools list --kind mcp

Os exemplos a seguir adicionam serviços integrados comuns:

Bash

# Search the public web.
agentbricks tools add mcp system.ai.web_search

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

By default, a tool execução with the permissions of the user who sent the request to your agent. To execução it as the app's Service Principal instead, add --auth app. For Google Drive, Gmail, Google Calendar, and Microsoft 365, each user completes a one-time OAuth login before the first call. See Connected applications.

Para revisar ou remover ferramentas, execute agentbricks tools list ou agentbricks tools remove mcp <service>.

Para outras ferramentas, consulte as seguintes páginas:

• Todos os serviços integrados e o que eles fazem: MCPs fornecidos pelo Databricks.
• Seus próprios servidores MCP externos: Servidores MCP externos.
• Funções do Unity Catalog como ferramentas: Criar ferramentas de agente usando funções do Unity Catalog.
• Um único Genie Agent com curadoria: Servidor MCP do Genie Agent.

Referência deagent.toml

agent.toml é a fonte de verdade declarativa para os recursos gerenciados pelo Databricks que seu agente usa. agentbricks init o cria, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind e agentbricks tracing bind o atualizam, e agentbricks deploy o lê para provisionar recursos e conceder acesso. Você também pode editá-lo diretamente.

Seção ou campo	Descrição
schema_version	A versão do formato agent.toml. Projetos gerados usam 1.
[agent] framework	O padrão de framework: langgraph ou openai.
[agent] server	O servidor do agente: agentbricks para DurableAgentServer, ou custom para o seu próprio servidor.
[memory_store] name	O armazenamento de memória gerenciado que o agente usa.
[session_store] name	O armazenamento de sessões gerenciado que o agente usa.
[tracing] experiment_name	O experimento do MLflow para rastreamentos. Remove the section to turn tracing off.
[[tools]]	Uma vinculação de ferramenta. Each tool has an id, an auth value of user or app, and a source that identifies the tool, plus an optional policy.
[auth.user]	Request-user authorization for tools that you write in code: required and additional_api_scopes. Consulte Autorização do usuário solicitante.

Seção ou campo	Descrição
schema_version	A versão do formato agent.toml. Projetos gerados usam 1.
[agent] framework	O padrão de framework: langgraph ou openai.
[agent] server	O servidor do agente: agentbricks para DurableAgentServer, ou custom para o seu próprio servidor.
[memory_store] name	O armazenamento de memória gerenciado que o agente usa.
[session_store] name	O armazenamento de sessões gerenciado que o agente usa.
[tracing] experiment_name	O experimento do MLflow para rastreamentos. Remove the section to turn tracing off.
[[tools]]	Uma vinculação de ferramenta. Each tool has an id, an auth value of user or app, and a source that identifies the tool, plus an optional policy.
[auth.user]	Request-user authorization for tools that you write in code: required and additional_api_scopes. Consulte Autorização do usuário solicitante.

The following example is the file that agentbricks init generates for a LangGraph agent named my-agent:

Toml

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-memory"

[session_store]
name = "my-agent-session"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent"

O exemplo a seguir mostra as associações de ferramentas que o agentbricks tools add grava: um serviço MCP integrado, um Genie Agent e um sandbox com escopo para uma tabela:

Toml

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

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

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

Ferramentas que chamam uma função do Unity Catalog usam source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } e oferecem suporte apenas a auth = "app".

Referência de comando

Para obter a referência completa e atualizada de comandos, incluindo todos os comandos e sinalizadores, consulte o README da CLI do Agent Bricks no GitHub.

Outros recurso

• Ferramentas de agente e serviços MCP: MCPs.
• Conceitos de memória do agente e API: Memória do agente.
• Conceitos de sessões de agente e API: Sessões de agente.
• Destile a história da sessão em memória de longo prazo: pipeline de memória de agentes.
• MLflow Tracing para agentes: Visão geral do rastreamento.