Migre um agente do Model Serving para o Databricks Apps

Migre um agente AI existente de um endpoint de Model Serving para o Databricks Apps.

A Databricks recomenda a criação de agentes no Databricks Apps, já que oferece as seguintes vantagens sobre o Model Serving:

• Iteração rápida : Itere no código do agente e na configuração de implantação em segundos, com depuração local e transparência total nos Logs e no comportamento do agente.
• Controle de versão baseado em Git e CI/CD: Empacote e controle a versão do código do agente Python modular com o Git, e implante com Pacotes de Automação Declarativa.
• Suporte a assistentes de codificação de AI: Use assistentes de codificação de AI para desenvolver e migrar seu agente localmente.
• Agentes assíncronos escaláveis : Crie agentes assíncronos com padrões assíncronos nativos do Python para alta simultaneidade.
• Personalização flexível do servidor : Use qualquer framework ou pilha, adicione rotas e middleware personalizados e configure a autenticação de usuários e agentes para endpoints e ferramentas LLM.
• Rastreamento do MLflow : Use modelos logged baseados em Git do MLflow e rastreamento em tempo real para monitorar o comportamento do agente.
• Interface de chat integrada : os padrões de agente conversacional incluem uma interface de chat pronta para uso com transmissão, autenticação e histórico persistente.

Requisitos

• Um agente existente implantado em um Endpoint de Model Serving.
• A CLI do Databricks instalada e autenticada. Consulte Instalar ou atualizar a CLI do Databricks.
• Python 3.11 ou posterior.
• O gerenciador de pacotes uv. Consulte instalação do uv.
• Databricks Apps habilitados em seu workspace. Consulte Configurar seu workspace e ambiente de desenvolvimento do Databricks Apps.

Clone o padrão de migração

O padrão de migração fornece o arcabouço para desenvolver e implantar um agente no Databricks Apps, juntamente com arquivos de habilidade do agente que ensinam assistentes de codificação de AI a executar cada o passo de migração.

Clone o padrão e vá para a pasta:

Bash

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-migration-from-model-serving

A pasta de padrões contém:

• AGENTS.md: Instruções para assistentes de codificação de AI que descrevem o fluxo de trabalho de migração
• skills/: Arquivos de habilidades para cada etapa de migração, executados em sequência pelo assistente
• agent_server/: A estrutura do agente do Databricks Apps de destino com código de espaço reservado para os manipuladores @invoke() e @stream()
• databricks.yml: Um padrão de configuração de Pacotes de Automação Declarativa com declarações de recursos de marcador de posição

Migração assistida por AI (recomendado)

A migração assistida por AI é a forma recomendada de usar este padrão. Um assistente de codificação de AI lê AGENTS.md e os arquivos de habilidade e lida automaticamente com as mudanças de código e configuração.

1. Abra a pasta de padrão em um assistente de codificação de AI, como Cursor, GitHub Copilot ou Claude.
2. Peça ao assistente para realizar a migração fornecendo o nome do seu Endpoint:

Prompt

"Migrate my Model Serving endpoint `my-agent-endpoint` to a Databricks App"

1. O assistente gera um plano de migração e executa cada passo:

Migração manual

A Databricks recomenda usar assistentes de codificação de IA para realizar a migração. Se preferir migrar sem um assistente de codificação de AI, as seguintes etapas de alto nível descrevem o processo.

importante

Esses passos são uma visão geral de alto nível e não cobrem todos os cenários de migração, como agentes com estado, compensações assíncronas vs. síncronas, acesso a artefatos do Unity Catalog ou configurações complexas de recursos.

Use um assistente de codificação de AI para ajudar na migração ou consulte a habilidademigrate-from-model-serving no padrão para obter informações mais detalhadas.

Etapa 1. Download dos artefatos do agente

1. Obtenha o nome e a versão do modelo de seu Endpoint:

Bash

databricks serving-endpoints get <endpoint-name> --output json

1. Encontre served_entities[0].entity_name (nome do modelo) e entity_version na resposta, então download os artefatos:

Bash

DATABRICKS_CONFIG_PROFILE=<profile> uv run --no-project \
  --with "mlflow[databricks]>=2.15.0" \
  python3 << 'EOF'
import mlflow
mlflow.set_tracking_uri("databricks")
mlflow.artifacts.download_artifacts(
    artifact_uri="models:/<model-name>/<version>",
    dst_path="./original_mlflow_model"
)
EOF

A pasta de download contém:

• MLmodel — declarações de recursos para o agente original
• code/ — os arquivos de origem Python do agente
• artifacts/ — arquivos de configuração e prompts opcionais
• input_example.json — uma solicitação de amostra para teste

Etapa 2. Migrar código do agente

Copie todos os arquivos Python de code/ para agent_server/ e quaisquer artefatos de artifacts/ para agent_server/artifacts/.

Após mover arquivos, atualize quaisquer importações relativas e caminhos de arquivo codificados para refletir a nova estrutura de pastas. Em seguida, reescreva agent_server/agent.py para usar o padrão mostrado n'O passo 3.

Etapa 3. Transforme o código do agente

No Model Serving, os agentes usam um ResponsesAgent baseado em classes com os métodos predict() e predict_stream(). No Databricks Apps, o AgentServer do MLflow serve funções de nível de módulo decoradas com @invoke() e @stream().

Ao migrar, escolha um dos seguintes padrões:

• Assíncrono (recomendado) : Usa Python async def e await para lidar com várias solicitações simultaneamente. Enquanto uma solicitação aguarda uma resposta do LLM, o servidor processa outras solicitações.
• Sincronização : Mantém os padrões síncronos do Python do seu agente de Model Serving. Escolha esta opção para uma migração mínima ou se o seu código depender de bibliotecas somente síncronas.

Model Serving (before)

A estrutura de agente baseada em classe original.

Python

from mlflow.pyfunc import ResponsesAgent, ResponsesAgentRequest, ResponsesAgentResponse

class MyAgent(ResponsesAgent):
  def predict(self, request: ResponsesAgentRequest, params=None) -> ResponsesAgentResponse:
    # Synchronous implementation
    ...
    return ResponsesAgentResponse(output=outputs)

  def predict_stream(self, request: ResponsesAgentRequest, params=None):
    # Synchronous generator
    for chunk in ...:
      yield ResponsesAgentStreamEvent(...)

Apps — async (recommended)

A lógica primária do agente está localizada em streaming(). A função non_streaming() coleta sua saída e a retorna como uma única resposta.

Python

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
async def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Async implementation - typically calls streaming() and collects results
  outputs = [
    event.item
    async for event in streaming(request)
    if event.type == "response.output_item.done"
  ]
  return ResponsesAgentResponse(output=outputs)

@stream()
async def streaming(request: ResponsesAgentRequest) -> AsyncGenerator[ResponsesAgentStreamEvent, None]:
  # Async generator
  async for event in ...:
    yield event

Apps — sync

Extraia os métodos de classe em funções decoradas de nível de módulo com alterações estruturais mínimas.

Python

from mlflow.genai.agent_server import invoke, stream
from mlflow.types.responses import (
  ResponsesAgentRequest,
  ResponsesAgentResponse,
  ResponsesAgentStreamEvent,
)

@invoke()
def non_streaming(request: ResponsesAgentRequest) -> ResponsesAgentResponse:
  # Same sync logic from original predict(), extracted from the class
  ...
  return ResponsesAgentResponse(output=outputs)

@stream()
def streaming(request: ResponsesAgentRequest):
  # Same sync generator from original predict_stream(), extracted from the class
  for chunk in ...:
    yield ResponsesAgentStreamEvent(...)

Etapa 4: Configurar o aplicativo

1. Instalar dependências. Isso resolve as dependências em pyproject.toml e cria o arquivo uv.lock que as pins para instalações reproduzíveis:

   Bash

   uv sync

2. Execute o script de início rápido para configurar a autenticação, criar o experimento MLflow e gerar o arquivo .env:

   Bash

   uv run quickstart

Faça o commit do arquivo uv.lock gerado para que o Databricks Apps instale as mesmas dependências fixadas quando você implantar.

O passo 5. Teste localmente

Inicie o servidor de aplicativos e verifique se o agente responde corretamente antes de implementar.

Teste com seu input_example.json original usando curl e, em seguida, implante depois que o agente responder conforme o esperado.

Etapa 6. Configurar recursos

Agentes do Model Serving declaram recursos em um arquivo MLmodel. Agentes do Databricks Apps declaram recursos no arquivo de configuração databricks.yml usando Pacotes de Automação Declarativa.

Consulte Autenticação para agentes de AI.

Mapeie suas declarações de recurso para o formato equivalente de Pacotes de Automação Declarativa:

Tipo de recurso MLmodel	databricks.yml equivalente	Permissão
serving_endpoint	serving_endpoint	CAN_QUERY
lakebase	database	CAN_CONNECT_AND_CREATE
vector_search_index	uc_securable (tipo segurável: TABLE)	SELECT
function	uc_securable (tipo segurável: FUNCTION)	EXECUTE
table	uc_securable (tipo segurável: TABLE)	SELECT ou MODIFY
uc_connection	uc_securable (tipo segurável: CONNECTION)	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

Tipo de recurso MLmodel	databricks.yml equivalente	Permissão
serving_endpoint	serving_endpoint	CAN_QUERY
lakebase	database	CAN_CONNECT_AND_CREATE
vector_search_index	uc_securable (tipo segurável: TABLE)	SELECT
function	uc_securable (tipo segurável: FUNCTION)	EXECUTE
table	uc_securable (tipo segurável: TABLE)	SELECT ou MODIFY
uc_connection	uc_securable (tipo segurável: CONNECTION)	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

Passo 7. Implante o agente usando Pacotes de Automação Declarativa

Implante seu agente no Databricks Apps usando Pacotes de Automação Declarativa.

Antes de implantar, verifique se a estrutura de pastas está como a seguir:

<working-directory>/
├── original_mlflow_model/    # Downloaded artifacts from Model Serving
│   ├── MLmodel
│   ├── code/
│   │   └── agent.py
│   ├── input_example.json
│   └── requirements.txt
│
└── <app-name>/               # New Databricks App (ready to deploy)
    ├── agent_server/
    │   ├── agent.py          # Migrated agent code
    │   └── ...
    ├── app.yaml
    ├── databricks.yml        # Bundle config with resources
    ├── pyproject.toml        # Python dependencies (uv)
    ├── uv.lock               # Pinned dependencies for reproducible installs
    └── ...

nota

Databricks recomenda uv (pyproject.toml + uv.lock) para gerenciamento de dependências do Python, o que oferece instalações mais rápidas e builds reproduzíveis. Quando seu aplicativo incluir um pyproject.toml e uv.lock e nenhum requirements.txt, Databricks Apps usa uv para instalar as dependências. requirements.txt ainda é compatível: se um estiver presente, ele sempre tem precedência e Databricks Apps usa pip em vez disso. Consulte Melhores práticas para Databricks Apps e Defina as dependências do Python com uv.

1. Valide a configuração do bundle:

   Bash

   databricks bundle validate

2. Implante o pacote em seu Workspace (bundle deploy faz upload dos arquivos, mas não inicia o aplicativo):

   Bash

   databricks bundle deploy

3. Começar o aplicativo:

   Bash

   databricks bundle run <app-resource-name>

Outros recursos

Após migrar seu agente, consulte:

• Criar um agente de AI e implantá-lo no Databricks Apps.
• Depurar um agente de código personalizado
• Autenticação para Agentes de IA
• Habilidades de agente para assistentes de codificação de AI
• Configurar rede para Databricks Apps