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 que prioriza o código para criar agentes personalizados a partir do terminal. A CLI do Agent Bricks cria a estrutura de um projeto usando uma estrutura integrada baseada nas melhores práticas do Databricks. Em seguida, ela pode executar o projeto localmente para testes e implantá-lo no runtime de agente do Databricks. A CLI permite que você vá de um diretório vazio a um agente implantado sem configurar manualmente o runtime, as ferramentas, a memória e os recursos gerenciados. Para outras maneiras de criar agentes personalizados, incluindo o fluxo de trabalho baseado em aplicativos, consulte Criar um agente e implantá-lo no Databricks Apps.
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:
Bashpip 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 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 sustentadas por armazenamentos gerenciados. Use a memória para persistir fatos e preferências entre as sessões. Consulte Memória do agente gerenciado. |
Sessões gerenciadas | Transcrições de conversas mantidas em armazenamentos de sessões gerenciadas e particionadas por ator, com suporte para ramificação de sessões em cópias independentes. Consulte Sessões de agente gerenciadas. |
Ferramentas | Recursos gerenciados pelo Databricks declarados em |
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. |
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:
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:
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:
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:
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:
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.
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.
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 e ferramentas de agente.
- Conceitos de memória de agente gerenciada e API: Memória de agente gerenciada.
- Conceitos de sessões de agentes gerenciadas e API: Sessões de agentes gerenciadas.
- MLflow Tracing para agentes: Visão geral do rastreamento.