Agent Bricks CLI
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.11 ou acima. O pacote CLI do Agent Bricks é instalado no Python 3.10, mas os projetos que ele cria requerem Python 3.11 ou acima. O Databricks recomenda Python 3.12.
-
uv, que faz a execução do projeto scaffolded paraagentbricks init,agentbricks deveagentbricks deploy. -
Instale a CLI do Agent Bricks. Para instalá-la como uma ferramenta
uv, execução o seguinte:Bashuv tool install databricks-agentbricksPara instalá-lo com
pipem vez disso, execuçãopip install databricks-agentbricks. Se a instalação falhar, consulte Solução de problemas.
Visão geral: do login a um agente implantado
A sequência a seguir resume os passos em Criar um novo agente:
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
Todos os comandos e grupos de comandos suportam --help. Por exemplo, execução agentbricks memory --help para listar os comandos de memória e suas flags.
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 initestrutura o projeto a partir de um padrão empacotado, opcionalmente populando um arquivo.envcom um perfil do Databricks para que o projeto seja executado imediatamente.agentbricks devexecuta o agente localmente em relação ao servindo modelo do Databricks para que você possa testá-lo antes de implantá-lo.agentbricks deployfaz o provisionamento dos recursos declarados emagent.tomle implanta o agente no runtime do agente do Databricks.
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 |
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 |
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 autenticação da CLI do Databricks. Autentique-se em seu workspace com OAuth (usuário para máquina) e salve as credenciais como um perfil nomeado. Execução ambos os comandos a seguir.
Um profile é um conjunto nomeado de configurações de conexão (uma URL de workspace e suas credenciais) salvas em ~/.databrickscfg. Os exemplos nesta página usam um perfil chamado my-workspace. Escolha qualquer nome e passe-o com --profile.
-
Para começar o fluxo de OAuth, faça a execução do seguinte, substituindo o host pela URL do seu Workspace. O comando abre um navegador para concluir o login, então escreve o perfil de
my-workspacepara~/.databrickscfg:Bashdatabricks auth login --host "https://<your-workspace-url>" --profile my-workspace -
Para validar o perfil e salvá-lo como o default da CLI do Agent Bricks para que os comandos posteriores possam omitir
--profile, execute a seguinte execução:Bashagentbricks login --profile my-workspaceSe as credenciais do perfil estiverem ausentes ou forem rejeitadas, o
agentbricks loginexecuta novamente odatabricks auth logine tenta novamente.
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:
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
As lojas gerenciadas permitem que seu agente preserve a história de conversas e a memória de longo prazo. agentbricks init declara um armazenamento de sessão e um armazenamento de memória em agent.toml, com o nome do projeto e um sufixo aleatório, como my-agent-cuzvas-memory. agentbricks deploy cria qualquer armazenamento declarado que ainda não exista e concede acesso ao agente implantado, portanto, a maioria dos agentes pode pular o passo.
Para usar um armazenamento diferente, vincule-o pelo nome. Cada comando substitui o nome do armazenamento em agent.toml. Ele não cria o armazenamento. Para vincular um armazenamento de sessão chamado my-agent-sessions e um armazenamento de memória chamado my-agent-memory, realize a execução do seguinte:
agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory
Para começar o agente com memórias já no armazenamento, crie o armazenamento e adicione entradas antes de implantar. Consulte a tab Agent Bricks CLI em Comece a usar a memória do agente.
Etapa 4: view tracing
O rastreamento está ativado por default. agentbricks init associa um experimento MLflow /Shared/agentbricks_traces/<project>-<suffix> 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:
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.
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.
agentbricks dev não se conecta à memória ou a armazenamentos de sessão. A memória de longo prazo está desativada e a história da conversa dura apenas enquanto o servidor local está em execução. O aplicativo de chat mostra Não conectado para a memória localmente, mesmo quando um armazenamento está vinculado. A memória se conecta após agentbricks deploy.
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>.
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.
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:
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
--existingdá suporte ao LangGraph e ao OpenAI Agents SDK comDurableAgentServer. 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-storee--session-storemoldam 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:
agentbricks tools list --kind mcp
Os exemplos a seguir adicionam serviços integrados comuns:
# 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 |
|---|---|
| A versão do formato |
| O padrão de framework: |
| O servidor do agente: |
| O armazenamento de memória gerenciado que o agente usa. |
| O armazenamento de sessões gerenciado que o agente usa. |
| O experimento do MLflow para rastreamentos. Remove the section to turn tracing off. |
| Uma vinculação de ferramenta. Each tool has an |
| Request-user authorization for tools that you write in code: |
The following example is the file that agentbricks init generates for a LangGraph agent named my-agent:
schema_version = 1
[agent]
framework = "langgraph"
server = "agentbricks"
[memory_store]
name = "my-agent-cuzvas-memory"
[session_store]
name = "my-agent-cuzvas-sessions"
[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent-cuzvas"
O sufixo aleatório (cuzvas neste exemplo) é diferente para cada projeto, portanto, projetos com o mesmo nome não compartilham armazenamentos ou experimentos.
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:
[[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
A tabela a seguir lista os comandos da CLI do Agent Bricks.
Comando | Descrição |
|---|---|
| Autenticar um perfil e salvá-lo como default. |
| Esqueça o perfil default salvo sem excluir suas credenciais. |
| Monte um novo projeto de agente ou prepare um agente existente para migração com |
| Verifique se um agente existente está configurado para a Agent Bricks CLI. |
| execução o agente localmente com uma UI de chat. |
| Gerenciar memória de longo prazo: vincular ou desvincular um armazenamento e gerenciar armazenamentos, entradas e pipelines de memória. |
| Gerenciar sessões de conversa: vincular ou desvincular um armazenamento e gerenciar armazenamentos de sessão. |
| Listar, adicionar e remover as ferramentas do agente. |
| Descubra serviços MCP gerenciados. |
| Vincular, desvincular e inspecionar rastreamento. |
| Implante o agente no runtime do agente do Databricks. |
| Gerencie agentes implantados: |
| Invocar um endpoint HTTP. |
| Comandos experimentais que podem mudar sem aviso prévio: |
Para todas as flags e opções, consulte a referência de comando da CLI do Agent Bricks no GitHub.
Solução de problemas
A instalação falha em um Mac Intel durante a compilação cryptography
Se a instalação falhar em um Mac Intel ao criar o pacote cryptography a partir da fonte, instale pacotes pré-compilados. Para instalar com pip, execução o seguinte:
pip install --only-binary :all: databricks-agentbricks
Instalar ou agentbricks dev falha por causa da versão do Python
Se a instalação ou agentbricks dev falhar ao criar dependências, verifique sua versão do Python com python3 --version. Projetos com scaffold exigem Python 3.11 ou acima, e o Databricks recomenda Python 3.12. Em versões mais recentes do Python, algumas dependências podem não ter pacotes pré-compilados. Para instalar a CLI com Python 3.12, execute o seguinte:
uv tool install --python 3.12 databricks-agentbricks
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.