Migrar um agente do Serviting Modelo para Databricks Apps

Migrar um agente AI existente de um endpoint do Serving Modelo para Databricks Apps.

Databricks recomenda o uso de agentes de autoria em Databricks Apps , pois oferece as seguintes vantagens em relação ao modelo de serviço:

• 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.
• Versionamento baseado emGite CI/CD : empacote e versione código de agente Python modular com Git e implante com Declarative Automation Bundles.
• Suporte de assistentes de codificaçãoAI : Utilize assistentes de codificação AI para desenvolver e migrar seu agente localmente.
• Agentes assíncronos escaláveis : Crie agentes assíncronos com padrões assíncronos nativos Python para alta simultaneidade.
• Personalização flexível do servidor : Utilize qualquer framework ou pilha de tecnologias, adicione rotas e middleware personalizados e configure a autenticação de usuários e agentes para o endpoint e as ferramentas LLM .
• RastreamentoMLflow : Utilize os modelos baseados em Git MLflow , registrados em log, e o rastreamento em tempo real para monitorar o comportamento do agente.
• Interface de chat integrada : O agente de conversação padrão inclui uma interface de chat pronta para uso com transmissão, autenticação e história persistente.

Requisitos

• Um agente existente implantado em um modelo endpoint instalado.
• A CLI do Databricks foi instalada e autenticada. Consulte Instalar ou atualizar a CLI do Databricks.
• Python 3.11 ou posterior.
• O gerenciador de pacotes uv . Veja instalação de UV.
• Databricks Apps ativados em seu workspace. Consulte Configurar seu workspace e ambiente de desenvolvimento Databricks Apps.

Clonar o padrão de migração

O padrão de migração fornece a estrutura para desenvolver e implantar um agente no Databricks Apps, juntamente com arquivos de habilidades que ensinam os assistentes de codificação AI a executar cada etapa da migração.

Clone o padrão e acesse a pasta:

Bash

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

A pasta Thete contém:

• AGENTS.md: Instruções para assistentes de codificação AI que descrevem o fluxo de trabalho da migração
• skills/Arquivos de habilidades para cada migração ou passo, 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: Uma configuração padrão de pacotes de automação declarativa com declarações de recurso de espaço reservado

Migração assistidaAI(recomendada)

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

1. Abra a pasta padrão em um assistente de codificação AI , como Cursor, GitHub Copilot ou Claude.
2. Solicite ao assistente que execute 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 etapa:

Migração manual

Databricks recomenda o uso de assistentes de codificação AI para realizar a migração. Se preferir migrar sem um assistente de codificação AI , os seguintes passos gerais descrevem o processo.

importante

Esses 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 entre assíncrono e síncrono, acesso a artefatos Unity Catalog ou configurações complexas de recursos.

Use um assistente de codificação AI para ajudar na migração ou veja 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 a partir 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, em seguida, 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 downloads 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 — um exemplo de solicitação de teste

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 os arquivos, atualize todas as importações relativas e caminhos de arquivo fixos para refletir a nova estrutura de pastas. Em seguida, reescreva agent_server/agent.py para usar o padrão mostrado na etapa 3.

o passo 3. Transformar código do agente

No modelo de serviço, os agentes usam uma classe baseada em ResponsesAgent com métodos predict() e predict_stream() . No Databricks Apps, o MLflow AgentServer 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 Python síncronos do seu agente modelo de serviço. Escolha esta opção para uma migração mínima ou se o seu código depender de uma biblioteca que funcione apenas de forma síncrona.

Model Serving (before)

A estrutura original de agentes baseada em classes.

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 para funções decoradas em 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(...)

o passo 4. Configurar 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. Teste localmente

Inicie o servidor de aplicativos e verifique se o agente responde corretamente antes da implantação.

Teste com seu input_example.json original usando curl, depois implante após o agente responder conforme o esperado.

o passo 6. Configurar recurso

agentes de modelo específicos declaram recurso em um arquivo MLmodel . Os agentes Databricks Apps declaram recurso no arquivo de configuração databricks.yml usando pacotes de automação declarativa.

Consulte Autenticação para agentes AI.

Mapeie suas declarações de recursos para o formato equivalente do Declarative Automation Bundles:

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_protegível: TABLE)	SELECT
function	uc_securable (tipo_protegível: FUNCTION)	EXECUTE
table	uc_securable (tipo_protegível: TABLE)	SELECT ou MODIFY
uc_connection	uc_securable (tipo_protegível: CONNECTION)	USE_CONNECTION
sql_warehouse	sql_warehouse	CAN_USE
genie_space	genie_space	CAN_RUN

o passo 7. implantei o agente usando Bundles de Automação Declarativa

Implante seu agente em Databricks Apps usando pacotes de automação declarativa.

Antes de implantar, verifique se a estrutura de pastas está igual à 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

O arquivo requirements.txt na pasta do seu aplicativo deve conter uv para que o Databricks Apps possa instalar dependências de pyproject.toml.

1. Valide a configuração do pacote:

   Bash

   databricks bundle validate

2. Implante o pacote em seu workspace (bundle deploy carrega os arquivos, mas não inicia o aplicativo):

   Bash

   databricks bundle deploy

3. Iniciar o aplicativo:

   Bash

   databricks bundle run <app-resource-name>

Próximos passos

Após migrar seu agente, consulte:

• Crie um agente AI e implemente-o no Databricks Apps
• Depurar um agente AI implantado
• Autenticação para agentes AI