CLI do Agente Bricks

Importante

Esse recurso está em Beta. Não é necessária nenhuma configuração de espaço de trabalho para habilitá-la. Instale a CLI Agent Bricks para começar.

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

A CLI do Agent Bricks é uma abordagem que prioriza código para criar agentes personalizados diretamente do terminal. A CLI Agent Bricks estrutura um projeto usando uma estrutura embutida baseada nas melhores práticas do Databricks. Ele pode então rodar o projeto localmente para testes e implantá-lo no runtime do agente Azure Databricks. A CLI permite que você vá de um diretório vazio para um agente implantado sem precisar ligar runtime, ferramentas, memória e recursos gerenciados manualmente. Para outras formas de construir agentes personalizados, incluindo o fluxo de trabalho baseado em aplicativos, veja Executar agentes em aplicativos Databricks usando o servidor de agentes legado.

Pré-requisitos

  • A CLI do Databricks, instalado e disponível no seu PATH.

  • Python 3.10 ou superior, com pip.

  • Instale o Agent Bricks CLI:

    pip install databricks-agentbricks

O ciclo de vida da CLI do Agent Bricks

A CLI Agent Bricks estrutura um diretório local de código de agente implantável a partir de um modelo de framework, com runtime, testes e uma interface de chat opcional já conectados. Você escreve a lógica da aplicação (modelo, ferramentas e prompts), e a CLI cuida da execução localmente e da implantação na infraestrutura do Azure Databricks.

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

Os três comandos que levam um agente de um diretório vazio para produção:

  • agentbricks init Estrutura o projeto a partir de um template agrupado, opcionalmente semeando um .env arquivo com um perfil Databricks para que o projeto rode imediatamente.
  • agentbricks devRoda o agente localmente contra o modelo de serviço do Azure Databricks para que você possa testá-lo antes de implantar.
  • agentbricks deploy provisiona os recursos declarados em agent.toml e implanta o agente no runtime de agente do Azure Databricks.

Ciclo de vida da CLI do Agent Bricks: fases de iniciação, desenvolvimento e implantação com suas ações principais

Note

Você também pode adicionar ferramentas e vincular memória e armazenamento de sessões a qualquer momento, não só no init. Use agentbricks tools add, agentbricks memory bind, e agentbricks sessions bind para atualizar a configuração do seu agente entre qualquer uma dessas etapas.

Capacidades da CLI do Agent Bricks

Capability Description
Acesso a modelos A CLI Agent Bricks provisiona automaticamente acesso ao modelo para que seu agente possa chamar um modelo servido pelo Azure Databricks sem gerenciar credenciais ou endpoints. Confira APIs do Modelo Base do Databricks.
Memória gerenciada Memórias de longo prazo que um agente pode escrever e pesquisar, particionadas por ator e suportadas por armazenamentos gerenciados. Use memória para manter informações e preferências em diferentes sessões. Consulte a memória do agente gerenciado.
Sessões gerenciadas Transcrições de conversas armazenadas em armazenamentos de sessão gerenciados e particionadas por ator, com suporte à bifurcação de sessões em cópias independentes. Veja Sessões de agentes gerenciados.
Tools Capacidades gerenciadas pelo Azure Databricks declaradas emagent.toml: um sandbox do Unity Catalog com escopo reduzido, um serviço MCP gerenciado pelo Azure Databricks ou uma função do Unity Catalog. Ferramentas personalizadas em Python são escritas diretamente no código do projeto. Veja MCPs.
Rastreamento Rastreamento do MLflow ativado por padrão, encaminhando os rastros de cada execução para um experimento do MLflow por projeto para depuração e monitoramento. Veja visão geral do rastreamento.
Implantação Implanta um agente no runtime do agente Azure Databricks, concede ao principal de serviço do agente acesso aos armazenamentos vinculados e gerencia o ciclo de vida da implantação.

Crie um novo agente

Passo 1: Autentice com o OAuth e salve um perfil

A CLI do Agent Bricks usa a autenticação da CLI do Databricks. Autentique seu espaço de trabalho com OAuth (usuário-para-máquina) e salve as credenciais como um perfil nomeado.

Para iniciar o fluxo OAuth, execute o seguinte, substituindo o host pela URL do seu workspace. O comando abre um navegador para completar o login, então escreve o perfil em ~/.databrickscfg:

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

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

agentbricks login --profile <profile>

agentbricks login Valida as credenciais do perfil. Se estiverem ausentes ou forem rejeitados, a CLI executará novamente databricks auth login e tentará outra vez.

Passo 2: Criar a estrutura do projeto do agente

Crie a estrutura de um novo projeto de agente e passe --framework para escolher o modelo. Este exemplo usa o modelo LangGraph, que inclui um aplicativo de chat no navegador:

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

A CLI inclui um template integrado para cada framework, e --framework seleciona a partir de qual deles gerar a estrutura: langgraph para LangGraph ou openai para o OpenAI Agents SDK. A CLI grava os recursos gerenciados do projeto e as associações de ferramentas em agent.toml e a procedência do modelo em .agentbricks/project.toml. Para gerar a estrutura do backend somente de API sem o aplicativo de chat, adicione --disable-chat-app.

Passo 3: Anexar os armazenamentos gerenciados de sessões e 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 da loja em agent.toml e cria a loja se ela não existir.

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

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

Passo 4: Rastreamento de visualização

O rastreamento está ativado por padrão. agentbricks init vincula um /Shared/agentbricks_traces/<project> experimento padrão de MLflow, e agentbricks devagentbricks deploy envia os traços de cada execução para ele.

Para listar rastreios após seu agente ter produzido alguns, execute o seguinte:

agentbricks tracing list

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

Passo 5: Gerencie o agente localmente

Execute o agente na sua máquina para testá-lo antes de implantar.

agentbricks dev

Isso inicia um servidor local na porta 8000 usando o mesmo comando e ambiente do runtime do agente do Azure Databricks. A CLI do Agent Bricks conecta o agente ao serviço de disponibilização de modelos do Azure Databricks para que ele possa invocar o modelo localmente. O template define um modelo padrão 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.

Passo 6: Implante o agente

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

agentbricks deploy my-agent

Quando a implantação termina, a CLI retorna a URL da implantação. Abra essa URL para interagir com seu agente ao vivo, que está automaticamente conectado ao modelo de serviço do Azure Databricks. Para gerenciar a implantação depois, use os agentbricks deployments comandos, como agentbricks deployments logs e agentbricks deployments stop.

Traga um agente existente

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

Passo 1: Prepare a migração

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 SDK de Agentes OpenAI.

agentbricks init --framework langgraph --existing .

A CLI grava um diretório agent-bricks-migrate/ que contém as instruções de migração, um prompt para seu agente de codificação e um projeto de referência gerado a partir dos templates da CLI. Também adiciona habilidades em .claude/skills/ e .agent/skills/ que direcionam os agentes de codificação para as instruções. O comando não altera o código da sua aplicação, as dependências ou o arquivo .env, e não cria recursos no seu espaço de trabalho.

Passo 2: Converta o projeto com seu agente de codificação

Cole o prompt de agent-bricks-migrate/ no seu agente de codificação. O agente de codificação converte o projeto para usar agent.toml e um ponto de entrada DurableAgentServer e verifica a conversão.

Passo 3: Verifique a conversão

Execute agentbricks doctor no diretório do projeto:

agentbricks doctor .

agentbricks doctorinspeciona os arquivos do projeto sem rodar seu código ou entrar em contato com o Azure Databricks. Funciona quando o projeto tem um agent.toml válido, inicia DurableAgentServer com um manipulador de invocação e chama o adaptador para seu framework. Um relatório com falha significa que a conversão não foi concluída.

Passo 4: Limpar, executar e implantar

Exclua agent-bricks-migrate/ e as duas competências que apontam para isso, e mantenha-as fora dos seus commits. Depois, execute o agente com agentbricks dev e o implante com agentbricks deploy.

Considerações

  • --existing suporta LangGraph e o SDK OpenAI Agents com DurableAgentServer. Ele não dá suporte a --server custom.
  • Trocar o agente para um armazenamento de sessão gerenciado não move o histórico de conversas existente dele. As instruções de migração pedem para você decidir 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ê construir seu agente com a CLI Agent Bricks, adicione um Serviço MCP embutido system.ai ao seu projeto com agentbricks tools add mcp. O comando verifica se o serviço existe no seu espaço de trabalho e registra a ferramenta em agent.toml. O agente se conecta à ferramenta em tempo de execução, então você não escreve nenhum código de conexão.

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

agentbricks tools list --kind mcp

Os exemplos a seguir adicionam serviços embutidos comuns:

# 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

Por padrão, uma ferramenta roda com as permissões do usuário que enviou a solicitação ao seu agente. Para rodá-lo como a entidade de serviço do aplicativo, adicione --auth app. Para Google Drive, Gmail, Google Calendar e Microsoft 365, cada usuário realiza um login OAuth único antes da primeira chamada. Veja Aplicativos conectados.

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

Para outras ferramentas, veja as páginas a seguir:

agent.toml Referência

agent.tomlé a fonte declarativa de verdade para os recursos gerenciados pelo Azure Databricks que seu agente utiliza. 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 editar diretamente.

Seção ou campo Description
schema_version A versão do formato agent.toml. Projetos gerados usam 1.
[agent] framework O modelo de estrutura: langgraph ou openai.
[agent] server O servidor agente: agentbricks para DurableAgentServer, ou custom para seu próprio servidor.
[memory_store] name O armazenamento de memória gerenciado que o agente usa.
[session_store] name O armazenamento de sessão gerenciado que o agente usa.
[tracing] experiment_name O experimento MLflow para rastreamentos. Remova a seleção para desligar o rastreamento.
[[tools]] Um vínculo de ferramenta. Cada ferramenta tem um id, um valor de auth de user ou app, e a source que identifica a ferramenta, mais um opcional policy.
[auth.user] Solicite autorização do usuário para ferramentas que você escreve em código: required e additional_api_scopes. Veja a autorização do usuário solicitante.

O exemplo a seguir é o arquivo que agentbricks init gera para um agente LangGraph chamado my-agent:

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 bindings de ferramentas que agentbricks tools add grava: um serviço MCP embutido, um Agente Genie e um sandbox escopado em 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 Catálogo Unity usam source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } e suportam apenas auth = "app".

Referência do comando

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

Recursos adicionais

  • Última atualização em