Criar um agente de IA e implantá-lo em Aplicativos do Databricks

Crie um agente de IA e implante-o usando o Databricks Apps. O Databricks Apps fornece controle total sobre o código do agente, a configuração do servidor e o fluxo de trabalho de implantação. Essa abordagem é ideal quando você precisa de comportamento de servidor personalizado, controle de versão baseado em git ou desenvolvimento de IDE local.

Dica

Se o agente usar apenas ferramentas hospedadas Azure Databricks e não precisar de lógica personalizada entre chamadas de ferramenta, você poderá usar a Supervisor API (Beta) para permitir que Azure Databricks gerencie o loop do agente para você.

Visualização da UI do chat do agente

Cada modelo de agente de conversa inclui uma interface do usuário de chat interna (mostrada acima) sem necessidade de configuração adicional. A interface do usuário de chat dá suporte a respostas de streaming, renderização de markdown, autenticação do Databricks e histórico opcional de chat persistente.

Requisitos

Habilite os Aplicativos do Databricks em seu workspace. Consulte Configurar seu ambiente de desenvolvimento e workspace do Databricks Apps.

Etapa 1. Clonar o modelo de aplicativo do agente

Comece usando um modelo de agente predefinido do repositório de modelos de aplicativo do Databricks.

Este tutorial usa o agent-openai-agents-sdk modelo, que inclui:

Um agente criado usando o SDK do OpenAI Agent
Código inicial para um aplicativo de agente com uma API REST conversacional e uma interface do usuário de chat interativa
Código para avaliar o agente usando o MLflow

Escolha um dos seguintes caminhos para configurar o modelo:

Interface do usuário do workspace

Instale o modelo de aplicativo usando a interface do usuário do workspace. Isso instala o aplicativo e o implanta em um recurso de computação em seu workspace. Em seguida, você pode sincronizar os arquivos do aplicativo com seu ambiente local para desenvolvimento adicional.

No workspace do Databricks, clique em + Novo>Aplicativo.
Clique em Agentes>Agente Personalizado (SDK do OpenAI).
Crie um novo experimento do MLflow com o nome openai-agents-template e conclua o restante da configuração para instalar o modelo.
Depois de criar o aplicativo, clique na URL do aplicativo para abrir a interface do usuário do chat.

Depois de criar o aplicativo, baixe o código-fonte no computador local para personalizá-lo:

Copiar o primeiro comando em Sincronizar os arquivos
Em um terminal local, execute o comando copiado.

Clonar de GitHub

Para começar a partir de um ambiente local, clone o repositório de modelos do agente e abra o agent-openai-agents-sdk diretório:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Etapa 2. Entender o aplicativo do agente

O modelo de agente demonstra uma arquitetura pronta para produção com esses componentes principais. Abra as seções a seguir para obter mais detalhes sobre cada componente:

Diagrama simples do Agente no Aplicativo

Abra as seções a seguir para obter mais detalhes sobre cada componente:

Interface de chat integrada

O modelo de agente busca e executa automaticamente o modelo de aplicativo de chat como seu front-end. Essa interface do usuário de chat é agrupada na mesma implantação do Databricks Apps e fornecida junto com seu agente, portanto, não há nenhuma configuração adicional necessária.

Você pode personalizar a interface do usuário do chat diretamente em seu projeto. Para obter mais detalhes sobre os recursos do aplicativo de chat, incluindo como habilitar o histórico de chat persistente e a coleta de comentários do usuário, consulte Compilar e compartilhar uma interface do usuário de chat com os Aplicativos do Databricks.

MLflow AgentServer

Um servidor FastAPI assíncrono que lida com solicitações de agentes, oferecendo rastreamento e observabilidade embutidos. O AgentServer fornece o /responses endpoint para consultar seu agente e gerencia automaticamente o roteamento de solicitações, o log e o tratamento de erros.

ResponsesAgent Interface

O Databricks recomenda o MLflow ResponsesAgent para criar agentes. ResponsesAgent permite criar agentes com qualquer framework de terceiros e integrá-los aos recursos de IA do Databricks para capacidades robustas de registro em log, rastreamento, avaliação, implantação e monitoramento.

ResponsesAgent encapsula facilmente agentes existentes para compatibilidade do Databricks.

Para saber como criar um ResponsesAgent, confira os exemplos na documentação do MLflow – ResponsesAgent for Model Serving.

ResponsesAgent fornece os seguintes benefícios:

Funcionalidades avançadas do agente
- Suporte a vários agentes
- Saída de streaming: transmita a saída em partes menores.
- Histórico abrangente de chamada de mensagens de ferramentas: Retorne várias mensagens, incluindo as intermediárias de chamada de ferramentas, para melhorar a qualidade e o gerenciamento da conversa.
- Suporte à confirmação de chamada de ferramenta
- Suporte para ferramentas de execução prolongada
Desenvolvimento, implantação e monitoramento simplificados
- Agentes de autoria usando qualquer estrutura: Envolver qualquer agente existente usando a ResponsesAgent interface para obter compatibilidade imediata com o Playground de IA, a Avaliação do Agente e o Monitoramento do Agente.
- Interfaces de autoria tipadas: escreva o código do agente usando classes de Python tipadas, beneficiando-se do preenchimento automático do IDE e do notebook.
- Rastreamento automático: o MLflow agrega automaticamente respostas transmitidas em rastreamentos para facilitar a avaliação e a exibição.
- Compatível com o esquema OpenAIResponses: consulte OpenAI: Responses vs. ChatCompletion.

SDK de Agentes do OpenAI

O modelo usa o SDK do OpenAI Agents como a estrutura do agente para gerenciamento de conversa e orquestração de ferramentas. Você pode criar agentes usando qualquer estrutura. A chave é encapsular o seu agente com a interface MLflow ResponsesAgent.

Servidores MCP (Model Context Protocol)

O modelo se conecta aos servidores MCP do Databricks para dar aos agentes acesso a ferramentas e fontes de dados. Consulte Model Context Protocol (MCP) no Databricks.

Criar agentes usando assistentes de codificação de IA

O Databricks recomenda usar assistentes de codificação de IA, como Claude, Cursor e Copilot para criar agentes. Use as habilidades de agente fornecidas, em /.claude/skills, e o arquivo AGENTS.md para ajudar os assistentes de IA a entender a estrutura do projeto, as ferramentas disponíveis e as práticas recomendadas. Os agentes podem ler automaticamente esses arquivos para desenvolver e implantar os Aplicativos do Databricks.

Etapa 3. Adicionar ferramentas ao seu agente

Forneça os recursos do agente, como consultar bancos de dados, pesquisar documentos ou chamar APIs externas conectando-o a servidores MCP. O modelo de agente inclui uma conexão de servidor MCP padrão. Para adicionar mais ferramentas, configure servidores MCP adicionais no código do agente e conceda as permissões necessárias.databricks.yml

Consulte as ferramentas do agente de IA para obter exemplos de código e tipos de ferramenta com suporte.

Defina ferramentas de função Python local

Para operações que não exigem fontes de dados externas ou APIs, defina ferramentas diretamente no código do agente. Essas ferramentas são executadas no mesmo processo que seu agente e são úteis para transformações de dados, cálculos ou operações de utilitário.

SDK de Agentes do OpenAI

Use o @function_tool decorador do SDK do OpenAI Agents:

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

Use o @tool decorador do LangChain:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

As ferramentas de função local não exigem concessões de recursos em databricks.yml porque são executadas no processo do agente.

Etapa 4. Gerenciar o uso de LLM de seus agentes nos aplicativos Databricks com o Unity AI Gateway

Rote as chamadas LLM do agente por meio do Gateway de IA (Beta) para que cada solicitação seja regida pelos mesmos controles, independentemente de qual provedor responda. Com o gateway no caminho da solicitação, você pode centralizar permissões, atribuir custo por aplicativo, alternar entre modelos e inspecionar ou retransmitir o tráfego sem modificar o código do agente ou rotacionar as credenciais do provedor.

Important

Esse recurso está em Beta. Os administradores do workspace podem controlar o acesso a esse recurso na página Visualizações . Consulte Gerenciar visualizações do Azure Databricks.

Habilite o Gateway de IA em seu workspace. Durante o Beta, o Gateway de IA é optativo. Um administrador de conta deve ativar essa função na página Pré-visualizações do console da conta antes que você possa criar ou consultar pontos de extremidade do gateway. Consulte Gerenciar visualizações do Azure Databricks.
Aponte seu agente para um endereço do gateway de inteligência artificial. No código do agente, passe o nome do ponto de extremidade do Gateway de IA como argumento model e configure use_ai_gateway=True no cliente LLM do Azure Databricks. O cliente roteia o tráfego pelo gateway e manipula a autenticação automaticamente.

OpenAI
```
from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)
```
LangGraph
```
from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)
```
Para obter mais interfaces de API (API de Respostas OpenAI, API de Mensagens Anthropic, Google Gemini) e exemplos REST, consulte Pontos de Extremidade do Gateway de IA do Unity.

Tópicos de criação avançados

Respostas de streaming

O streaming permite que os agentes enviem respostas em partes em tempo real em vez de aguardar a resposta completa. Para implementar o streaming com ResponsesAgent, emita uma série de eventos delta seguidos por um evento de conclusão final:

Emitir eventos delta: enviar vários output_text.delta eventos com o mesmo item_id para transmitir partes de texto em tempo real.
Concluir com o evento concluído: enviar um evento final response.output_item.done com o mesmo item_id que os eventos delta que contêm o texto de saída final completo.

Cada evento delta transmite uma parte do texto para o cliente. O evento final concluído contém o texto de resposta completo e sinaliza o Databricks para fazer o seguinte:

Rastrear a saída do agente com o rastreamento do MLflow
Agregar respostas transmitidas em tabelas de inferência do Gateway de IA
Mostrar a saída completa na interface do usuário do AI Playground

Propagação de erro de streaming

Mosaic AI propaga todos os erros encontrados durante a transmissão com o último token em databricks_output.error. Cabe ao cliente de chamada tratar e exibir corretamente esse erro.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Entradas e saídas personalizadas

Alguns cenários podem exigir entradas adicionais do agente, como client_type e session_id, ou saídas, como links de fontes de recuperação que não devem ser incluídos no histórico de chat para futuras interações.

Para esses cenários, o MLflow ResponsesAgent dá suporte nativo aos campos custom_inputs e custom_outputs. Você pode acessar as entradas personalizadas por meio request.custom_inputs dos exemplos de estrutura acima.

O aplicativo de revisão de Avaliação do Agente não dá suporte à renderização de rastreamentos para agentes com campos de entrada adicionais.

Fornecer custom_inputs no Playground de IA e examinar o aplicativo

Se o agente aceitar entradas adicionais usando o custom_inputs campo, você poderá fornecer manualmente essas entradas no AI Playground e no aplicativo de revisão.

No Playground de IA ou no Aplicativo de Revisão do Agente, selecione o ícone de engrenagem .
Habilitar custom_inputs.
Forneça um objeto JSON que corresponda ao esquema de entrada definido do agente.

Etapa 5. Executar o aplicativo do agente localmente

Configure seu ambiente local:

Instale uv (gerenciador de pacotes Python), nvm (gerenciador de versões do Node) e o Databricks CLI:
- uv Instalação
- nvm Instalação
- Execute o seguinte para usar o Node 20 LTS:
```
nvm use 20
```
- databricks CLI Instalação
Altere o diretório para a agent-openai-agents-sdk pasta.
Execute os scripts de início rápido fornecidos para instalar dependências, configurar seu ambiente e iniciar o aplicativo.
```
uv run quickstart
uv run start-app
```

Em um navegador, vá para http://localhost:8000 para abrir a interface de chat integrada e inicie a conversa com o agente.

Etapa 6. Configurar autenticação

Seu agente precisa de autenticação para acessar Azure Databricks recursos. Os Aplicativos do Databricks fornecem dois métodos de autenticação: autorização do aplicativo (principal de serviço) e autorização do usuário (em nome do usuário final). Você pode configurar qualquer um por meio da interface do usuário do ambiente de trabalho ou declarativamente em databricks.yml com Pacotes de Automação Declarativa. Os modelos de agente são fornecidos com um databricks.yml, tornando esse caminho o padrão quando você inicia a partir de um modelo.

Para obter a referência completa, incluindo todos os tipos de recursos com suporte, valores de permissão e um passo a passo de ponta a ponta databricks.yml , consulte Autenticação para agentes de IA.

Autorização de aplicativo (padrão)

A autorização do aplicativo usa um princípio de serviço que o Azure Databricks cria automaticamente para seu aplicativo. Todos os usuários compartilham as mesmas permissões.

Declare todos os recursos que o agente usa sob resources.apps.<app>.resources em databricks.yml. Implante o pacote para conceder à entidade de serviço as permissões declaradas:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para obter a lista completa de tipos de recursos, consulte a autorização do aplicativo.

Autorização do usuário

A autorização do usuário permite que seu agente aja com as permissões individuais de cada usuário. Use isso quando precisar de controle de acesso por usuário ou trilhas de auditoria.

Adicione este código ao seu agente:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

Inicialize get_user_workspace_client() dentro de suas funções @invoke ou @stream, e não durante a inicialização do aplicativo. As credenciais do usuário só existem ao lidar com uma solicitação.

Configure quais APIs de Azure Databricks o agente pode chamar em nome do usuário adicionando escopos em user_api_scopes no aplicativo em databricks.yml:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para obter a lista de escopos disponíveis e instruções de instalação completas, consulte a autorização do usuário.

Etapa 7. Avaliar o agente

O modelo inclui o código de avaliação do agente. Consulte agent_server/evaluate_agent.py para obter mais informações. Avalie a relevância e a segurança das respostas do agente executando o seguinte em um terminal:

uv run agent-evaluate

Passo 8. Implantar o agente nos Aplicativos do Databricks

Depois de configurar a autenticação, implante o agente para Azure Databricks. Os modelos de agente usam DABs (Pacotes de Ativos) do Databricks para implantação. O databricks.yml arquivo no modelo define a configuração do aplicativo e as permissões de recurso. Verifique se você tem a CLI do Databricks instalada e configurada.

Nota

Se você criou seu aplicativo por meio da interface do usuário do workspace na Etapa 1, execute databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve antes de implantar para associar o aplicativo existente ao seu pacote. Caso contrário, databricks bundle deploy falha com "Já existe um aplicativo com o mesmo nome".

Valide a configuração do pacote para capturar erros antes de implantar:
```
databricks bundle validate
```
Implante o pacote. Este processo carrega seu código e configura recursos (experimento do MLflow, pontos de extremidade do servidor e assim por diante) definidos em databricks.yml.
```
databricks bundle deploy
```
Inicie ou reinicie o aplicativo:
```
databricks bundle run agent_openai_agents_sdk
```
Nota

bundle deploy carrega apenas arquivos e configura recursos. bundle run é necessário iniciar ou reiniciar o aplicativo com o novo código.

Para atualizações futuras, execute databricks bundle deploy e, em seguida, databricks bundle run agent_openai_agents_sdk para reimplantar.

Etapa 9. Consultar o agente implantado

O exemplo a seguir usa uma solicitação rápida curl com um token OAuth. Não há suporte para PATs (tokens de acesso pessoal) para Aplicativos do Databricks.

Para obter a lista completa de métodos de consulta, incluindo o cliente do Databricks OpenAI e a API REST, consulte Consulte um agente implantado no Azure Databricks.

Gere um token OAuth usando a CLI do Databricks:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Use o token para consultar o agente:

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Limitações

Há suporte apenas para tamanhos de computação médios e grandes. Consulte Configurar recursos de computação para um aplicativo do Databricks.
Atualmente, a interface do usuário do Chat do Aplicativo de Revisão do MLflow não dá suporte a agentes implantados nos Aplicativos do Databricks. Para avaliar os rastreamentos existentes, use sessões de rotulagem, que funcionam independentemente do método de implementação. O Databricks está criando revisão e suporte a comentários diretamente no modelo de chatbot.

Próximas Etapas

Realize um teste de carga no agente dos Databricks Apps

Comentários

Esta página foi útil?

Last updated on 2026-05-03

Criar um agente de IA e implantá-lo em Aplicativos do Databricks

Requisitos

Etapa 1. Clonar o modelo de aplicativo do agente

Interface do usuário do workspace

Clonar de GitHub

Etapa 2. Entender o aplicativo do agente

Criar agentes usando assistentes de codificação de IA

Etapa 3. Adicionar ferramentas ao seu agente

Defina ferramentas de função Python local

SDK de Agentes do OpenAI

LangGraph

Etapa 4. Gerenciar o uso de LLM de seus agentes nos aplicativos Databricks com o Unity AI Gateway

OpenAI

LangGraph

Tópicos de criação avançados

Respostas de streaming

Entradas e saídas personalizadas

Etapa 5. Executar o aplicativo do agente localmente

Etapa 6. Configurar autenticação

Autorização de aplicativo (padrão)

Autorização do usuário

Etapa 7. Avaliar o agente

Passo 8. Implantar o agente nos Aplicativos do Databricks

Etapa 9. Consultar o agente implantado

Limitações

Próximas Etapas

Comentários

Recursos adicionais