Como implementar agentes de IA com Databricks

Informatec Digital » Recursos » Implementando agentes de IA com Databricks: um guia prático completo

Agent Bricks, AI Playground e MLflow abrangem tudo, desde a prototipagem até a implantação, com governança no Unity Catalog.
O ResponsesAgent oferece streaming, multiagente e rastreamento avançado integrados ao MLflow e ao AI Gateway.
A implantação com deploy() cria endpoints seguros, com rastreamento e revisão em tempo real.

Criar agentes de IA no Databricks não é mais domínio exclusivo de perfis ultra-técnicos: entre ambientes visuais como o AI Playground , automação com Agent Bricks e frameworks MLflow, agora você pode ir da ideia ao protótipo e do protótipo à produção sem se perder no processo. Neste guia, condensamos tudo o que você precisa para criar, avaliar e implantar agentes que chamam ferramentas, consultam dados e se integram à governança do Unity Catalog.

Além de explorar a abordagem sem código e o desenvolvimento em Python, você aprenderá como empacotar agentes com MLflow (ChatAgent e ResponsesAgent) , registrar recursos no catálogo, habilitar o monitoramento em tempo real e escalar usando o Model Serving. Também incluímos um aplicativo de exemplo desenvolvido com React e FastAPI para integrar seu agente perfeitamente a uma interface web corporativa.

Opções para criar agentes no Databricks

Se você prioriza velocidade e simplicidade, o Agent Bricks oferece um fluxo de trabalho automatizado para a criação de sistemas de agentes de alta qualidade e alinhados ao domínio. Você especifica seu caso de uso e conecta seus dados do Unity Catalog ; a plataforma gera variantes de agentes, otimiza com avaliação e permite que você refine, tudo com governança e segurança integradas.

Quando você precisa de controle preciso e deseja reutilizar bibliotecas conhecidas, a abordagem baseada em código combina o Mosaic AI Agent Framework e o MLflow . Com Python, você pode definir a lógica do agente, habilitar chamadas de ferramentas, realizar rastreamento detalhado e, por fim, empacotar e implantar em produção com o ecossistema Databricks.

Se você já utiliza frameworks de terceiros, há suporte nativo para LangGraph/ LangChain , LlamaIndex ou implementações personalizadas em Python. Graças às assinaturas de modelo e interfaces de agente do MLflow, você pode integrá-los aos recursos de avaliação e monitoramento sem precisar reescrever tudo do zero.

Quer criar protótipos em tempo recorde? Com o AI Playground, você escolhe o modelo e a máquina virtual, adiciona ferramentas ao LLM por meio de uma interface de baixo código e usa o chat para validar. Em seguida, você exporta o agente para um código pronto para produção e continua com o ciclo de desenvolvimento padrão.

Assinaturas de modelo e compatibilidade com recursos da plataforma

O Azure Databricks usa assinaturas de modelo MLflow para descrever o esquema de entrada e saída dos agentes. Recursos do produto — como o AI Playground ou a avaliação — exigem que o agente esteja em conformidade com uma das assinaturas compatíveis para garantir a interoperabilidade.

Se você seguir a abordagem recomendada ao criar o agente, o MLflow inferirá automaticamente a assinatura compatível sem etapas adicionais. Caso contrário, verifique se sua implementação está em conformidade com uma das assinaturas no esquema legado para entrada e saída do agente, evitando surpresas ao integrar com as ferramentas do Databricks.

Tutorial rápido: Primeiro agente com o framework Mosaic AI Agent.

O objetivo é criar um agente que raciocine com um Mestrado em Direito (LLM) oferecido pela Databricks e ser capaz de executar ferramentas, por exemplo, a função integrada. system.ai.python_exec do Catálogo Unity para executar código Python. Além disso, habilitaremos o rastreamento com MLflow para inspeção de vestígios e diagnósticos.

Requisitos básicos do espaço de trabalho: habilitar os recursos do agente e ter Acesso ao Modelo ServingNo ambiente de execução, instale pacotes como: mlflow, databricks-openai e o agente embalador (databricks-agent o databricks-agents(Dependendo do guia que você seguir e da versão), e reinicie o Python para carregar as dependências.

Defina a conexão com o serviço de modelo usando o cliente OpenAI que ele disponibiliza. Cliente do Espaço de Trabalho, ativo mlflow.openai.autolog() para instrumentação automática e registra as ferramentas disponíveis. Entre elas, system.ai.python_exec Ele funciona como um interpretador Python sem estado e permite que o LLM resolva cálculos ou manipule dados durante o diálogo.

Com uma função como run_agent(), você envia a solicitação do usuário para o endpoint de bate-papo (Por exemplo, um modelo como «databricks-claude-3-7-sonnet«e gerenciar o possível chamadas a ferramentas Retornar as mensagens do assistente e as respostas da ferramenta em uma lista coerente.

Como usar Inteligência Artificial sem cadastro ou conta

Para testar, execute uma consulta que exija código (por exemplo, calcular o 100º número de Fibonacci ) e revise tanto a saída do assistente quanto os rastreamentos do MLflow registrados no notebook ou experimento associado. Isso permitirá que você refine a orquestração antes de empacotar.

Empacotado com MLflow e implantado no Model Serving.

Uma forma recomendada de preparar o agente para produção é implementando a interface. Agente de bate-papo MLflowVocê precisa de um método predict() que aceita mensagens, chama a lógica do seu agente e retorna um Resposta do agente de bate-papo com a lista de mensagens (incluindo mensagens intermediárias associadas a ferramentas, se aplicável).

Para facilitar a integração, consolide todo o código em um único arquivo Python (por exemplo, usando...). %%writefile quickstart_agent.py (se você estiver trabalhando em um laptop). Na parte final, ligue mlflow.models.set_model() passando a instância da sua classe (por exemplo, QuickstartAgent) para estabelecer o ponto de entrada inferência.

Registre o agente em Catálogo Unity com mlflow.pyfunc.log_model, incluindo recursos que você precisará em produção: o endpoint do modelo LLM (por exemplo, DatabricksServingEndpoint) e as funções de catálogo que o agente invocará (por exemplo, DatabricksFunction com system.ai.python_execAssim, o Databricks pode Configurar autenticação para esses recursos durante a implantação.

Por fim, utilize a API do Agente para espalhar do modelo para um ponto de extremidade de serviço: from databricks import agents y agents.deploy(model_name, model_version)Quando o endpoint iniciar, você poderá Bate-papo do AI PlaygroundCompartilhe com as partes interessadas e comece a coletar feedback.

Se você deseja continuar aprimorando, o Databricks oferece guias para medir a qualidade do agente , construir agentes com recuperação (RAG) em dados não estruturados e controlar conversas de múltiplas etapas, além de alternativas com LangGraph, Python puro ou OpenAI.

Agente de Respostas: A interface moderna para agentes de produção

Embora Agente de bate-papo Funciona bem, a MLflow recomenda hoje mesmo. Agente de Respostas Para agentes sérios. Esta interface é compatível com o esquema. Responses da OpenAI e permite a integração de agentes de qualquer estrutura Com as funcionalidades do Databricks (registro, rastreamento, avaliação, implantação e observabilidade) sem qualquer dificuldade.

Principais vantagens: suporte nativo para Sistemas multiagente, modo de saída streaming, histórico completo de mensagens e chamadas de ferramentas, confirmação de chamadas de ferramentas e ferramentas duradouras. Além disso, oferece interfaces tipadas Em Python, inferência automática de assinaturas, rastreamento automático de predict y predict_stream e tabelas de inferência aprimoradas por meio de Gateway de IA.

Requisitos de instalação para esta abordagem: databricks-agents 1.2.0+, mlflow 3.1.3+ y Python 3.10 + (usando Serverless ou Databricks Runtime 13.3 LTS ou superior). A Databricks também recomenda os seguintes pacotes: Ponte de IA para integrações comuns.

Integrações úteis: databricks-openai (AI aberto), databricks-langchain (LangChain/LangGraph), databricks-dspy (DSPy) e databricks-ai-bridge (Agentes em Python puro). Com esses componentes, você pode construir desde agentes simples até... tubulações complexas com chamada de recuperação e ferramenta.

Se você já possui um agente integrado, encapsule-o em uma classe que herde de mlflow.pyfunc.ResponsesAgent. Implement predict para converter as entradas e saídas em Esquema do Agente de RespostasPara streaming, conte com predict_stream, emitindo deltas e um evento final response.output_item.done Por favor, adicione a resposta completa.

Em relação a erros de streaming, o Mosaic AI propaga a falha juntamente com o último token dentro do arquivo. databricks_output.errorSeu cliente deve capturar e exibir isso corretamente, melhorando a experiência de depuração.

Sistemas de recuperação, entradas personalizadas e rastreabilidade.

Muitos agentes usam recuperadores para RAGs sobre índices vetoriais. Se seus intervalos de recuperação expõem um esquema diferente, você pode mapeá-lo com mlflow.models.set_retriever_schemadeclarando primary_key, text_column, doc_uri e outras colunas. Assim, o AI Playground mostrará Links para as fontes recuperado e a avaliação será aplicada avaliadores de relevância automaticamente

Nos casos em que o seu agente necessitar de informações adicionais (por exemplo, tipo_cliente o session_id), usa custom_inputs e retorna metadados em custom_outputs Isso não deve contaminar o histórico do chat. Tanto o AI Playground quanto o aplicativo de avaliação permitem que você insira entradas_personalizadas a partir da interface do usuário.

Dados sintéticos: o que são, como são gerados e para que servem

Implantação com deploy(), requisitos e ações automatizadas

Para publicar seu agente no Mosaic AI Model Serving, use a função deploy() da API Python. No MLflow 3, instale mlflow >= 3.1.3 y databricks-agents >= 1.1.0 (se você implantar fora dos notebooks). No MLflow 2.x, os mínimos mudam (por exemplo, mlflow >= 2.13.1 y databricks-agents >= 0.12.0). Tenha certeza de Registre o agente no Catálogo da Unity. antes da implantação.

Chamar a deploy() Crie um endpoint escalável com balanceamento automático, configure o autenticação segura para recursos do Databricks (índices vetoriais, funções de catálogo) — verificando as permissões do proprietário — e ativa o análise de candidatura para colaboração com as partes interessadas.

Ele também permite o monitoramento em tempo real no MLflow (com rastreamentos no experimento ativo e nas tabelas de inferência). No MLflow 3, é possível configurar o monitoramento de produção com avaliação automática de qualidade; as solicitações REST e os comentários são registrados nas tabelas de inferência (usando APIs de feedback modernas).

Para personalizar, passe argumentos para deploy() como scale_to_zero_enabled=TrueReduzir custos após períodos de inatividade, à custa de maior latência na primeira solicitação. Além disso, você tem utilitários para listar, obter e excluir implantações via API do Agente.

Boas práticas para padrões de estado, configuração e execução

O serviço de modelos é distribuído: evite caches locais e pressupõe que diferentes respostas podem lidar com diferentes turnos em uma conversa. Ela reconstrói o estado a partir do dicionário de ResponsesAgentRequest cada predict e projetar o estado para ser thread-safe.

Inicializa o estado dentro de predict e não no construtor do agente, já que uma única réplica poderia lidar com conversas de diferentes usuários. Isso impede vazamentos de informação e conflitos de concorrência em ambientes de alto desempenho.

Parametrize o comportamento do agente com ModelConfig (dicionário ou YAML). Defina, por exemplo, model_serving_endpointParâmetros LLM e modelos de prompts; carregue essa configuração em desenvolvimento e promova-a para produção. sem mexer no código.

Evite introduzir loops de eventos ou frames assíncronos no servidor do agente: o Databricks lida com a concorrência internamente . Use código síncrono ou callbacks; caso contrário, você poderá encontrar erros como "Este loop de eventos já está em execução" e comportamento errático.

Agent Bricks: automação "sem código" para acelerar a geração de valor.

O Agent Bricks, lançado em 2025, oferece um fluxo de trabalho de criação de agentes simplificado que não requer programação . Você insere a tarefa em linguagem natural, conecta seus dados e a plataforma seleciona modelos, gera dados sintéticos , avalia e refina o processo até entregar um agente pronto para produção com governança do Unity Catalog.

Entre suas vantagens estão a automação de ponta a ponta , a escalabilidade no Databricks — com endpoints que podem ser reduzidos a zero após 3 dias de inatividade —, análises de uso e custo no Lakehouse e tipos de agentes prontos (extração de informações, LLM personalizado , assistente de conhecimento e supervisor multiagente para orquestração complexa).

Entre as limitações, está o fato de o código gerado não estar disponível para download no momento , o que restringe a personalização aprofundada, e o catálogo de modelos ser voltado para organizações já integradas ao Lakehouse e ao Unity Catalog. Alguns usuários também consideram que as métricas de custo carecem de granularidade .

Exemplos: agentes multiagentes e agentes com estado.

Na documentação oficial, você encontrará notebooks com OpenAI (bate-papo simples e chamadas de ferramentas, tanto para modelos hospedados no Databricks quanto no OpenAI), LangGraph (invocação de ferramentas) e DSPy (chamadas de ferramentas em uma única interação). Essas são excelentes bases para estender a funcionalidade com ferramentas personalizadas e avaliações de qualidade.

Para coordenar vários especialistas, você pode configurar sistemas cooperativos usando ferramentas como o Genie. E se você estiver interessado em memória de conversas, há suporte para agentes com estado que permitem pontos de verificação e persistência do histórico de conversas.

AlphaGeometry 2 da DeepMind revoluciona a resolução de problemas matemáticos

Aplicativos no Databricks: interface do usuário com React e backend em FastAPI.

Os aplicativos Databricks oferecem uma plataforma robusta para fornecer interfaces ricas sem a necessidade de configurar infraestrutura externa. Eles se integram nativamente ao Databricks SQL, Unity Catalog , Model Serving e Jobs, e herdam os controles de segurança e conformidade da plataforma.

Um padrão muito prático é criar um frontend com React (com suporte a streaming, renderização de mensagens e UX em Markdown) e um backend com FastAPI que atua como uma ponte para o endpoint do agente. O backend encaminha a solicitação do usuário para o serviço de modelo e retorna a resposta estruturada para o cliente.

Na FastAPI, a ordem de montagem das subaplicações é importante: app.mount("/api", api_app) direciona rotas de API (por exemplo, /api/chat) E app.mount("/", ui_app) Ele serve os arquivos estáticos da compilação do React no diretório raiz. Esse esquema mantém clareza das rotas e separa a interface do usuário dos pontos de extremidade.

Configure as variáveis de ambiente (por exemplo, SERVING_ENDPOINT_NAME ou o FQN do modelo do agente no Catálogo Unity) da definição do aplicativo no Databricks. Compile o frontend (npm run build), sincroniza arquivos, declara dependências (requirements.txt) e começa com Gunicórnio + Uvicórnio trabalhadores para a ASGI.

Caso real: chatbot para operações de manufatura

Em cenários de Gestão de Operações de Manufatura (MOM), um chatbot do Databricks pode auxiliar os gerentes de produção com análise de gargalos , rastreamento de estoque e geração de relatórios. As funções são expostas como ferramentas no Catálogo Unity (via SQL ou Python), e o agente as invoca com base no contexto.

Exemplos: uma função identify_bottleneck_station Ele executa consultas no Databricks SQL para detectar a etapa que causa mais atrasos; outra, check_inventory_levelsEle retorna o estoque em tempo real. O agente também pode enviar e-mails, gerar relatórios e realizar análises de sentimento, tudo orquestrado com chamadas de ferramentas.

A implantação do endpoint Model Serving funciona como o backend padrão . O aplicativo React consome esse endpoint, exibindo respostas em tempo real com uma experiência de usuário refinada e oferecendo suporte ao streaming de tokens quando habilitado no ResponsesAgent.

Migração do ChatCompletions e compatibilidade

Se o seu agente legado utiliza a API ChatCompletions da OpenAI , você pode migrar para o ResponsesAgent com um contêiner que traduz mensagens de entrada/saída e, opcionalmente, mapeia deltas de streaming para o ResponsesAgentStreamEvent . Isso moderniza a telemetria e a observabilidade sem reescrever a lógica principal.

Para listar e gerenciar implantações, a API do Agente permite listar as implantações existentes, recuperar uma implantação específica (por nome e versão) e remover endpoints que você não precisa mais. Lembre-se de gerenciar as credenciais de recursos externos usando variáveis de ambiente e segredos.

O Databricks oferece um caminho completo: desde a ideação com o AI Playground ou a automação com o Agent Bricks, passando pelo desenvolvimento de código (Mosaic AI, MLflow, LangGraph, DSPy), até o empacotamento, o registro no Unity Catalog , a implantação com o deploy() e o monitoramento em produção. Com as melhores práticas, como assinaturas de modelo adequadas , estado seguro em ambientes distribuídos e configuração parametrizada, você pode fornecer agentes confiáveis e governados, prontos para integração em aplicações web na plataforma.