Migrar um agente do Model Serving para o Databricks Apps

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

A Databricks recomenda a criação de agentes no Databricks Apps, pois oferece as seguintes vantagens em relação ao 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 total transparência nos logs e no comportamento do agente.
• Controle de versão baseado em Git e CI/CD : Empacote e versione o código de agente modular Python com Git e seja implantado com Pacotes de Automação Declarativa.
• Suporte para 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 stack, adicione rotas e middleware personalizados e configure a autenticação de usuário e agente para endpoints e ferramentas de 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 de conversação 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 Configure seu workspace e ambiente de desenvolvimento dos Databricks Apps.

Clonar o padrão de migração

O padrão de migração fornece a estrutura para desenvolver e ser implantado em Databricks Apps, juntamente com arquivos de habilidades de agente que ensinam os 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ão 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 o passo de migração, executados em sequência pelo assistente
• agent_server/A estrutura do agente 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 Declarative Automation Bundles com declarações de recurso de espaço reservado

Migração assistida por AI (recomendado)

A migração assistida por AI é a maneira 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. Solicite ao assistente que realize 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 o passo:

Migração manual

A Databricks recomenda o uso de assistentes de codificação de AI para realizar a migração. Caso prefira migrar sem um assistente de codificação de AI, os seguintes passos de alto nível descrevem o processo.

importante

Estes os passos são uma visão geral de alto nível e não abrangem 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 recurso.

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.

O passo 1. Baixar artefatos do agente

1. Obtenha o Nome e a Versão do Modelo do 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 e, depois, faça o download dos 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 baixada contém:

• MLmodel — declarações de recurso 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 testes

O passo 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 imports relativos e caminhos de arquivo codificados para refletir a nova estrutura de pastas. Então, reescreva agent_server/agent.py para usar o padrão mostrado no o passo 3.

O passo 3. Transformar o código do agente

No Model Serving, os agentes usam um ResponsesAgent baseado em classe com métodos predict() e predict_stream(). No Databricks Apps, o AgentServer do MLflow serve funções em 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 por uma resposta do LLM, o servidor processa outras solicitações.
• Sincronização : Mantém padrões Python síncronos do seu agente de Model Serving. Escolha esta opção para uma migração mínima ou se o seu código depende de bibliotecas apenas síncronas.

Model Serving (before)

A estrutura original do agente baseada em classe.

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 do agente primário reside 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 de nível de módulo decoradas com mínimas alterações estruturais.

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(...)

O passo 4. Configure o aplicativo

Instale as dependências e execute o script de início rápido para configurar a autenticação, criar o experimento MLflow e gerar o arquivo .env.

O passo 5. Testar localmente

Comece o servidor do aplicativo 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.

O passo 6. Configurar recurso

Os agentes do Model Serving declaram recursos em um arquivo MLmodel. Os 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 recursos para o formato equivalente dos 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

O passo 7. Implantar o agente usando Pacotes de Automação Declarativa

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

Antes de implantar, verifique se a estrutura de sua pasta se parece com o seguinte:

<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
    ├── requirements.txt
    └── ...

nota

Se seu aplicativo incluir pyproject.toml e uv.lock, o Databricks Apps usará uv para instalar dependências. Se requirements.txt também estiver presente, ele terá precedência e pip será usado em vez disso. Consulte Defina dependências Python com uv.

1. Validar a configuração do pacote:

   Bash

   databricks bundle validate

2. Implante o pacote no seu workspace (bundle deploy faz o upload dos arquivos, mas não deve começar o aplicativo):

   Bash

   databricks bundle deploy

3. Começar o aplicativo:

   Bash

   databricks bundle run <app-resource-name>

Recursos adicionais

Após migrar seu agente, consulte:

• Crie um agente de AI e tenha-o implantado no Databricks Apps
• Depurar um agente de código personalizado
• Autenticação para agentes de AI
• Habilidades de agente para assistentes de codificação de AI
• Configurar rede para Databricks Apps