Crie um agente AI e implemente-o no Databricks Apps

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.

Pré-visualização da interface do usuário do chat do agente

Requisitos

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

o passo 1. Clone o aplicativo do 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
Clone from GitHub

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.

No seu workspace Databricks , clique em + Novo > Aplicativo .
Clique em Agentes > Agente - SDK de Agentes da OpenAI .
Crie um novo experimento MLflow com o nome openai-agents-template e conclua o restante da configuração para instalar o padrão.
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:

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

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

o passo 2. Compreenda o aplicativo do agente

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

Agente no aplicativo - diagrama simples

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

Servidor de agentes MLflow

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.

interfaceResponsesAgent

A Databricks recomenda o MLflow ResponsesAgent para construir agentes. ResponsesAgent permite que você crie agentes com qualquer estrutura de terceiros e, em seguida, os integre ao recurso AI Databricks para recursos robustos de registro, rastreamento, avaliação, implantação e monitoramento.

O ResponsesAgent integra facilmente os agentes existentes para compatibilidade com o Databricks.

Para aprender como criar um ResponsesAgent, veja os exemplos na documentaçãoMLflow - ResponsesAgent para servir modelo.

ResponsesAgent oferece os seguintes benefícios:

Capacidades avançadas de agente
- Suporte multiagente
- transmissão saída : transmissão a saída em partes menores.
- Histórico abrangente de mensagens de tool-calling : Retorna várias mensagens, inclusive mensagens intermediárias de chamadas de ferramentas, para melhorar a qualidade e o gerenciamento de conversas.
- Suporte para confirmação de chamadas de ferramentas
- Suporte de ferramentas de longa duração
Desenvolvimento, implantação e monitoramento simplificados
- Agentes autores utilizando qualquer estrutura : integre qualquer agente existente utilizando a interface ResponsesAgent para obter compatibilidade imediata com AI Playground, Avaliação de Agentes e Monitoramento de Agentes.
- Interfaces de criação digitadas : Escreva o código do agente usando classes Python digitadas, beneficiando-se do preenchimento automático do IDE e do Notebook.
- Rastreamento automático : MLflow agrega automaticamente as respostas de transmissão em rastreamentos para facilitar a avaliação e a visualização.
- Compatível com o esquema OpenAI Responses : Consulte OpenAI: Respostas vs. ChatCompletion.

SDK de Agentes OpenAI

O padrão utiliza o SDKde AgentesOpenAI como estrutura 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 .

Servidores MCP (Model Context Protocol)

O padrão se conecta aos servidores Databricks MCP para dar aos agentes acesso a ferramentas e fonte de dados. Consulte o Protocolo de Contexto do Modelo (MCP) no Databricks.

Autores agentes usando assistentes de codificação AI

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

Tópicos avançados de autoria

respostas

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

Emitir eventos delta : enviar vários eventos com o mesmo delta para transmitir trechos de texto em tempo real. output_text.delta eventos com o mesmo item_id para transmitir trechos de texto em tempo real.
Concluir com o evento concluído : envie um evento response.output_item.done final com o mesmo item_id dos eventos delta contendo o texto final completo da saída.

Cada evento delta transmite um fragmento de texto para o cliente. O evento final concluído contém o texto completo da resposta e sinaliza ao Databricks para realizar as seguintes ações:

Rastreie a saída do seu agente com o rastreamento do MLflow
Agregar respostas de transmissão em tabelas de inferência de gateway d AI
Mostrar a saída completa na interface do usuário do AI Playground

propagação de erro de transmissão

Mosaic AI propaga quaisquer erros encontrados durante a transmissão com os últimos tokens em databricks_output.error. Cabe ao cliente chamador tratar e revelar adequadamente esse erro.

Bash
{
  "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 origem de recuperação que não devem ser incluídos no histórico do chat para interações futuras.

Para esses cenários, MLflow ResponsesAgent suporta nativamente os campos custom_inputs e custom_outputs. Você pode acessar as entradas personalizadas por meio de request.custom_inputs nos exemplos de estrutura acima.

O aplicativo de análise de avaliação de agentes não oferece suporte à renderização de rastreamentos para agentes com campos de entrada adicionais.

Forneça custom_inputs no AI Playground e revise o aplicativo.

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

No AI Playground ou no aplicativo Agent Review, selecione o ícone de engrenagem .
Habilite custom_inputs .
Forneça um objeto JSON que corresponda ao esquema de entrada definido pelo seu agente.

Esquemas de recuperação personalizados

Agentes AI geralmente usam mecanismos de recuperação para encontrar e consultar dados não estruturados em índices de busca vetorial. Para exemplos de ferramentas de recuperação, consulte Conectar agentes a dados não estruturados.

Rastreie esses recuperadores dentro de seu agente com MLflow RETRIEVER spans para permitir Databricks produto recurso, incluindo:

Exibição automática de links para documentos de origem recuperados na interface do usuário do AI Playground
Executando automaticamente juízes de fundamentação e relevância de recuperação na Avaliação de Agentes

nota

Databricks recommends using retriever tools provided by Databricks AI Bridge packages like databricks_langchain.VectorSearchRetrieverTool and databricks_openai.VectorSearchRetrieverTool because they already conform to the MLflow retriever schema. See Locally develop Vector Search retriever tools with AI Bridge.

Se seu agente incluir extensões de retriever com um esquema personalizado, chame mlflow.models.set_retriever_schema ao definir seu agente no código. Isso mapeia as colunas de saída do seu recuperador para os campos esperados do MLflow (primary_key, text_column, doc_uri).

Python
import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)

nota

The doc_uri column is especially important when evaluating the retriever's performance. doc_uri is the main identifier for documents returned by the retriever, allowing you to compare them against ground truth evaluation sets. See Evaluation sets (MLflow 2).

o passo 3. executar o aplicativo do agente localmente

Configure seu ambiente local:

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

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

o passo 4. Configurar autenticação

Seu agente precisa de autenticação para acessar o recurso Databricks . O Databricks Apps oferece dois métodos de autenticação:

App authorization (default)
User authorization

A autorização do aplicativo utiliza uma entidade de serviço que o Databricks cria automaticamente para o seu aplicativo. Todos os usuários compartilham as mesmas permissões.

Conceda permissões ao experimento MLflow:

Clique em Editar na página inicial do seu aplicativo.
Acesse a opção Configurar o passo.
Na seção de recursos do aplicativo , adicione o recurso de experimento MLflow com permissão Can Edit .

Para outros recursos (Busca Vetorial, Genie spaces, endpoint de serviço), adicione-os da mesma forma na seção de recursos do aplicativo .

Consulte a seção Autorização do aplicativo para obter mais detalhes.

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

Adicione este código ao seu agente:

Python
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)

Importante: Inicialize get_user_workspace_client() dentro de suas funções @invoke ou @stream , não durante startup do aplicativo. As credenciais do usuário só existem durante o processamento de uma solicitação.

Configure os escopos: adicione escopos de autorização na interface do usuário do Databricks Apps para definir quais APIs seu agente pode acessar em nome dos usuários.

Consulte a seção Autorização do usuário para obter instruções completas de configuração.

o passo 5. 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

o passo 6. implantou o agente para Databricks Apps

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

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
```

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"

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.

o passo 7. Consulte 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.
A interface de chat do aplicativoMLflow Review não oferece suporte, no momento, a agentes implantados em Databricks Apps. Para avaliar rastreamentos existentes, use sessões de rótulo, que funcionam independentemente do método de implantação. Databricks está integrando suporte para avaliações e feedback diretamente no chatbot Padrão.

Requisitos​

o passo 1. Clone o aplicativo do agente padrão​

o passo 2. Compreenda o aplicativo do agente​

Autores agentes usando assistentes de codificação AI​

Tópicos avançados de autoria​

respostas​

Entradas e saídas personalizadas​

Esquemas de recuperação personalizados​

o passo 3. executar o aplicativo do agente localmente​

o passo 4. Configurar autenticação​

o passo 5. Avalie o agente​

o passo 6. implantou o agente para Databricks Apps​

o passo 7. Consulte o agente implantado​

Limitações​