Crie um agente AI e implemente-o no Databricks Apps

info

Experimental

Este recurso é experimental e está sujeito a alterações.

Crie um agente AI e implante-o usando Databricks Apps. O Databricks Apps oferece 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 personalizado do servidor, controle de versão baseado em Git ou desenvolvimento em IDE local.

Este fluxo de trabalho de implantação de agente é uma alternativa para implantar um agente para instalar um modelo de endpoint onde Databricks gerencia a infraestrutura para você.

Pré-requisitos

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

Clonar o aplicativo agente padrão

Comece usando um agente pré-construído padrão do aplicativoDatabricks repositório padrão.

Este tutorial utiliza o padrão agent-openai-agents-sdk , que inclui:

• Um agente criado usando o SDK de Agentes da OpenAI
• Código inicial para um aplicativo de agente com uma API REST conversacional e uma interface de chat interativa.
• Código para avaliar o agente usando MLflow

Escolha um dos seguintes caminhos para configurar o padrão:

Workspace UI

Instale o aplicativo padrão usando a interface do usuário do espaço de trabalho. Isso instala o aplicativo e o implanta em um recurso compute em seu workspace. Em seguida, você pode sincronizar os arquivos do aplicativo com seu ambiente local para dar continuidade ao desenvolvimento.

1. No seu workspace Databricks , clique em + Novo > Aplicativo .

2. Selecione Agentes > Agente do SDK de Agentes OpenAI .

3. Crie um novo experimento MLflow com o nome openai-agents-template e conclua o restante da configuração para instalar o padrão.

4. Após criar o aplicativo, clique no URL do aplicativo para abrir a interface de bate-papo.

   

Após criar o aplicativo, download o código-fonte para o seu computador para personalizá-lo:

1. Copie o primeiro comando em Sincronizar os arquivos

   

2. No terminal local, execute o comando copiado.

Clone from GitHub

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

Bash

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

Compreenda a aplicação do agente

O agente padrão demonstra uma arquitetura pronta para produção usando três componentes key :

MLflow AgentServer : Um servidor FastAPI assíncrono que lida com solicitações de agentes com rastreamento e observabilidade integrados. O AgentServer fornece o endpoint /invocations para consultar seu agente e gerencia automaticamente o roteamento de solicitações, registro e tratamento de erros.

OpenAI Agents SDK : O padrão utiliza o OpenAI Agents SDK como framework de agentes para gerenciamento de conversas e orquestração de ferramentas. Você pode criar agentes usando qualquer framework. A key é envolver seu agente com a interface MLflow ResponsesAgent .

InterfaceResponsesAgent : Esta interface garante que seu agente funcione em diferentes estruturas e se integre com as ferramentas do Databricks. Crie seu agente usando SDK OpenAI , LangGraph, LangChain ou Python puro e, em seguida, envolva-o com ResponsesAgent para obter compatibilidade automática com AI Playground, a avaliação de agentes e a implantação Databricks Apps .

Servidores MCP (Model Context Protocol) : O padrão se conecta aos servidores MCP Databricks para acessar agentes, ferramentas e fonte de dados. Consulte o Protocolo de Contexto do Modelo (MCP) no Databricks.

executar o aplicativo do agente localmente

Configure seu ambiente local:

1. Instale uv (gerenciador de pacotes Python ), nvm (gerenciador de versões do Node) e a CLI Databricks :

   • uv instalação

   • nvm instalação

   • Execute o seguinte comando para usar o Node 20 LTS:

     Bash

     nvm use 20

   • databricks CLI instalação

2. Mude para o diretório da pasta agent-openai-agents-sdk .

3. Execute os scripts de início rápido fornecidos para instalar as dependências, configurar seu ambiente e iniciar o aplicativo.

   Bash

   ./scripts/quickstart.sh
   uv run start-app

Em um navegador, acesse http://localhost:8000 para iniciar o bate-papo com o agente.

Configurar autenticação

Seu agente precisa de autenticação para acessar recursos Databricks , como experimentos MLflow , índices de pesquisa vetorial, endpoints de serviço e funções Unity Catalog .

Escolha entre autenticação de entidade de serviço (recomendada para a maioria dos casos de uso) ou autenticação em nome de.

Service Principal authentication

Por default, Databricks Apps são autenticados usando uma entidade de serviço (SP). O SP é criado automaticamente quando você cria o aplicativo e funciona como a identidade do aplicativo.

Conceda ao SP a permissão Can Edit no experimento MLflow para log rastreamentos e resultados de avaliação. Clique em edit na página inicial do seu aplicativo para configurar isso. Consulte Adicionar um recurso de experimento do MLflow a um aplicativo Databricks.

Se o seu agente utiliza outros recursos Databricks , como índices de pesquisa vetorial, endpoints de serviço, funções UC, conexões UC, bancos de dados Lakebase, volumes UC ou Genie spaces você pode conceder permissões ao SP para acessá-los. Para obter uma lista completa de recursos e instruções sobre como configurar permissões, consulte Adicionar recurso a um aplicativo Databricks.

Consulte a tabela encontrada em Autenticação automática do agente para selecionar o nível de permissão correto.

On-Behalf-Of (OBO) authentication

Use a autenticação OBO quando seu agente precisar acessar o recurso usando a identidade do usuário solicitante em vez da entidade de serviço do aplicativo. A autenticação OBO permite permissões específicas do usuário e registros de auditoria.

Para implementar a autenticação OBO no código do seu agente:

1. Importe a autenticação russas. O utilitário usa o AgentServer para capturar o cabeçalho x-forwarded-access-token para lidar com a autenticação entre o usuário, o aplicativo e o servidor do agente:

   Python

   from agent_server.utils import get_user_workspace_client

2. Use get_user_workspace_client() para obter um WorkspaceClient autenticado como o usuário solicitante. Inicialize o WorkspaceClient no momento da consulta para acessar as credenciais do usuário. Se você inicializar durante startup do aplicativo, a operação falhará porque ainda não há credenciais de usuário disponíveis.

   Python

   # In your agent code
   w = get_user_workspace_client()
   
   # Now use w to access Databricks resources with user permissions
   response = w.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Conceda aos usuários acesso ao recurso que eles precisam usar por meio do agente. Por exemplo, se o seu agente consultar um endpoint de serviço, você deve conceder permissão Can Query aos usuários nesse endpoint.

Consulte Recuperar credenciais de autorização do usuário.

Avalie o agente

O padrão 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 seu agente executando o seguinte comando em um terminal:

Bash

uv run agent-evaluate

implantar o agente no Databricks Apps

Após configurar a autenticação, implante seu agente no Databricks. Certifique-se de ter o Databricks CLI instalado e configurado.

1. Se você clonou o repositório localmente, crie o aplicativo Databricks antes de implantá-lo. Se você criou seu aplicativo por meio da interface do usuário workspace , ignore esta etapa, pois o aplicativo e o experimento MLflow já estão configurados.

   Bash

   databricks apps create agent-openai-agents-sdk

2. Sincronize arquivos locais com seu workspace. Veja o aplicativo implantado.

   Bash

   DATABRICKS_USERNAME=$(databricks current-user me | jq -r .userName)
   databricks sync . "/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk"

3. Implante seu aplicativo Databricks .

   Bash

   databricks apps deploy agent-openai-agents-sdk --source-code-path /Workspace/Users/$DATABRICKS_USERNAME/agent-openai-agents-sdk

Para futuras atualizações do agente, sincronize e reimplemente o agente.

Consultar o agente implantado

Os usuários consultam seu agente implantado usando tokens OAuth. access tokens pessoal (PATs) não são suportados para Databricks Apps.

Gere tokens OAuth usando a CLI Databricks :

Bash

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

Utilize os tokens para consultar o agente:

Bash

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

Limitações

Apenas tamanhos compute médios e grandes são suportados. Consulte Configurar o tamanho compute para um aplicativo Databricks.