CLI do Agente Bricks

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

A CLI do Agent Bricks é uma abordagem centrada no código para criar agentes personalizados no terminal. A CLI Agent Bricks estrutura um projeto utilizando uma framework incorporada baseada nas melhores práticas do Databricks. Depois, pode executar o projeto localmente para testes e implementá-lo no runtime do agente Azure Databricks. A CLI permite-lhe passar de um diretório vazio para um agente implementado sem ter de ligar manualmente o tempo de execução, ferramentas, memória e recursos geridos. Para outras formas de construir agentes personalizados, incluindo o fluxo de trabalho baseado em aplicações, veja Executar agentes nas Databricks Apps usando o servidor de agentes legado.

Pré-requisitos

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

• Python 3.10 ou superior, com pip.

• Instale a CLI do Agent Bricks:

  pip install databricks-agentbricks
  

O ciclo de vida da CLI dos Agent Bricks

A CLI Agent Bricks estrutura um diretório local de código de agente deployável a partir de um modelo de framework, com o runtime, testes e uma interface de chat opcional já ligados. Escreves a lógica da aplicação (modelo, ferramentas e prompts), e a CLI trata da execução local e da implementação na infraestrutura do Azure Databricks.

agent.toml é a fonte declarativa de referência para todos os recursos geridos pelo Azure Databricks de que o seu agente depende: associações de ferramentas (sandbox de dados, serviços geridos do Model Context Protocol (MCP), funções do Unity Catalog) e recursos de memória, sessão e rastreio. agentbricks deploy lê-o para provisionar e interligar tudo, pelo que é o ficheiro, e não o código de configuração escrito manualmente, que faz a implementação.

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

• agentbricks init Estrutura o projeto a partir de um modelo agrupado, opcionalmente semeando um .env ficheiro com um perfil Databricks para que o projeto corra imediatamente.
• agentbricks devExecuta o agente localmente contra o Azure Databricks model serve para que possas testá-lo antes de implementar.
• agentbricks deploy aprovisiona os recursos declarados em agent.toml e implementa o agente no runtime do agente do Azure Databricks.

Capacidades da CLI do Agent Bricks

Crie um novo agente

Passo 1: Autenticar com OAuth e guardar um perfil

A CLI Agent Bricks utiliza autenticação da CLI Databricks. Autentica-te no teu espaço de trabalho com OAuth (utilizador-para-máquina) e guarda as credenciais como um perfil nomeado.

Para iniciar o fluxo OAuth, execute o seguinte, substituindo o host pelo URL do seu espaço de trabalho. O comando abre um navegador para completar o login, depois escreve o perfil em ~/.databrickscfg:

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

Para definir esse perfil como o 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 em falta ou forem rejeitados, a CLI executa novamente databricks auth login e tenta novamente.

Passo 2: Estruturar o projeto do agente

Cria um novo projeto de agente e utiliza --framework para escolher o modelo. Este exemplo utiliza o modelo LangGraph, que inclui uma aplicação de chat no navegador:

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

A CLI inclui um modelo integrado por framework, e --framework seleciona qual deles usar para gerar a estrutura base: langgraph para LangGraph ou openai para o SDK de OpenAI Agents. A CLI escreve os recursos geridos do projeto e as ligações de ferramentas para agent.toml e a proveniência do template para .agentbricks/project.toml. Para estruturar o backend apenas com API sem a aplicação de chat, adicione --disable-chat-app.

Passo 3: Anexar armazenamentos geridos de sessões e memória

Vincule os armazenamentos geridos para que o seu agente possa manter o histórico de conversas e a memória de longo prazo. Cada comando regista o nome da loja em agent.toml e cria a loja caso não exista.

Para associar 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: Rastreio de visualizações

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

Para listar vestígios depois de o seu agente ter produzido alguns, execute o seguinte:

agentbricks tracing list

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

Passo 5: Executar o agente localmente

Executa o agente na tua máquina para o testar antes de implementares.

agentbricks dev

Isto inicia um servidor local na porta 8000 usando o mesmo comando e ambiente do runtime do agente Azure Databricks. A CLI do Agent Bricks liga o agente ao serviço de model serving do Azure Databricks para que este possa chamar o modelo localmente. O modelo define um modelo predefinido 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: Instalar o agente

Implemente o agente para o runtime do Azure Databricks agent. A CLI aprovisiona os armazenamentos associados, concede ao principal de serviço do agente acesso a esses armazenamentos e efetua a implementação. O agente destacado chama-se agent-bricks-<name>.

agentbricks deploy my-agent

Quando a implementação termina, a CLI devolve a URL da implementação. Abra esse URL para interagir com o seu agente ao vivo, que está automaticamente ligado ao Azure Databricks model serving. Para gerir a implementação posterior, utilize os agentbricks deployments comandos, como agentbricks deployments logs e agentbricks deployments stop.

Traga um agente já existente

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

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 utiliza: langgraph para LangGraph ou openai para o SDK OpenAI Agents.

agentbricks init --framework langgraph --existing .

A CLI escreve um diretório agent-bricks-migrate/ que contém as instruções de migração, um prompt para o seu agente de código e um projeto de referência gerado a partir dos templates da CLI. Também adiciona competências em .claude/skills/ e em .agent/skills/ que orientam 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 ficheiro .env, e não cria recursos no seu espaço de trabalho.

Passo 2: Converte o projeto com o teu agente de programação

Cola o prompt do agent-bricks-migrate/ no teu agente de programaçã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

Executa agentbricks doctor no diretório do projeto:

agentbricks doctor .

agentbricks doctorinspeciona os ficheiros do projeto sem executar o seu código ou contactar o Azure Databricks. Tem sucesso quando o projeto tem um agent.toml, começa DurableAgentServer com um handler de invocação e chama o adaptador para o seu framework. Um relatório falhado significa que a conversão não está concluída.

Passo 4: Limpar, executar e fazer a implantação

Apaga agent-bricks-migrate/ e as duas competências que apontam para isso, e mantém-nas fora dos teus commits. Depois executa o agente com agentbricks dev e implanta-o com agentbricks deploy.

Considerations

• --existing suporta o LangGraph e o SDK dos Agentes OpenAI com DurableAgentServer. Não suporta --server custom.
• Mudar o agente para um armazenamento de sessões gerido não move o histórico de conversas existente. As instruções de migração pedem-lhe para 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 construir o seu agente com a CLI Agent Bricks, adicione um Serviço MCP incorporado 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 regista a ferramenta em agent.toml. O agente liga-se à ferramenta em tempo de execução, por isso não é necessário escrever qualquer código de ligação.

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

agentbricks tools list --kind mcp

Os seguintes exemplos adicionam serviços incorporados 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 defeito, uma ferramenta corre com as permissões do utilizador que enviou o pedido ao seu agente. Para o executar como entidade de serviço da aplicação, adicione --auth app. No Google Drive, Gmail, Google Calendar e Microsoft 365, cada utilizador realiza um login OAuth único antes da primeira chamada. Ver Aplicações conectadas.

Para rever 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 fazem: MCPs fornecidos por Databricks.
• Os teus próprios servidores MCP externos: Servidores MCP externos.
• As funções do Unity Catalog funcionam como ferramentas: Criar ferramentas de agente usando funções do Unity Catalog.
• Um único Genie Agent selecionado: servidor MCP do Genie Agent (legado).

agent.toml Referência

agent.tomlé a fonte declarativa de verdade para os recursos geridos pelo Azure Databricks que o seu agente utiliza. agentbricks init cria-o, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, e agentbricks tracing bind atualizam-no, e agentbricks deploy lê-o para provisionar recursos e conceder acesso. Também podes editar diretamente.

O exemplo seguinte é o ficheiro 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 seguinte mostra bindings de ferramentas que agentbricks tools add escreve: um serviço MCP incorporado, um Agente Genie e um sandbox com âmbito numa única 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 utilizam source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" } e suportam apenas auth = "app".

Referência de comando

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

Recursos adicionais

• Ferramentas para agentes e serviços MCP: MCPs.
• Conceitos de memória de agente gerido e API: Memória de agente gerida.
• Conceitos de sessões de agentes geridos e API: Sessões de agentes geridos.
• MLflow Tracing para agentes: Visão geral do rastreamento.