Pular para o conteúdo principal
Última atualização em

Crie um agente de AI e implante-o nos Databricks Apps

Crie um agente de AI e implante-o usando o 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 de servidor personalizado, versionamento baseado em Git ou desenvolvimento IDE local.

dica

Se o seu agente usar apenas ferramentas hospedadas no Databricks e não precisar de lógica personalizada entre as chamadas de ferramenta, você poderá usar a Supervisor API (Beta) para permitir que o Databricks gerencie o ciclo do agente para você.

Pré-visualização da UI de chat do agente

Cada padrão de agente conversacional inclui uma interface de usuário de chat integrada (mostrada acima) sem necessidade de configuração adicional. A interface de usuário do chat oferece suporte a respostas de transmissão, renderização de markdown, autenticação Databricks e histórico de chat persistente opcional.

Requisitos​

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

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

Comece usando um padrão de agente pré-construído do repository de padrões de aplicativos Databricks.

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

  • Um agente criado usando o OpenAI Agent SDK
  • 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:

Instale o modelo de aplicativo usando a IU do Workspace. Isso instala o aplicativo e o implanta em um recurso de compute em seu workspace. Você pode então sincronizar os arquivos do aplicativo para seu ambiente local para desenvolvimento adicional.

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

  2. Clique em Agents > Custom Agent (OpenAI SDK) .

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

  4. Depois de criar o aplicativo, clique no URL do aplicativo para abrir a IU de chat.

Depois de criar o aplicativo, download o código-fonte para sua máquina local para personalizá-lo:

  1. Copie o primeiro comando em Sincronizar os arquivos

    Sincronizar arquivos do Databricks Apps

  2. Em um terminal local, execute o comando copiado.

Passo 2. Entenda o aplicativo do agente​

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

Agente em Aplicativo: Diagrama Simples

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

Ícone de bate-papo UI de chat integrada

O padrão de agente busca e executa automaticamente o padrão de aplicativo de chat como seu frontend. Esta interface de usuário de chat é empacotada no mesmo deployment do Databricks Apps e servida junto com seu agente, então não há configuração adicional necessária.

É possível personalizar a interface de chat diretamente no seu projeto. Para obter mais detalhes sobre os recursos do aplicativo de chat, incluindo como habilitar o histórico de chat persistente e a coleta de feedback do usuário, consulte Crie e compartilhe uma interface de chat com o Databricks Apps.

Ícone de chip MLflow AgentServer

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

Ícone de colchetes quadrados. interfaceResponsesAgent

A Databricks recomenda o MLflow ResponsesAgent para criar agentes. ResponsesAgent permite que você crie agentes com qualquer framework de terceiros e, em seguida, o integre com os recursos de Databricks AI para capacidades robustas de registro em log, rastreamento, avaliação, implantação e monitoramento.

ResponsesAgent facilmente envolve agentes existentes para compatibilidade com Databricks.

Para saber como criar um ResponsesAgent, consulte os exemplos na Documentação do MLflow - ResponsesAgent para Model Serving.

ResponsesAgent oferece os seguintes benefícios:

  • Capacidades avançadas do agente

    • Suporte multiagente
    • Saída de transmissão : transmita a saída em partes menores.
    • História abrangente de mensagens de chamada de ferramenta : retorna várias mensagens, incluindo mensagens intermediárias de chamada de ferramenta, para melhoria da qualidade e gerenciamento de conversas.
    • Suporte à confirmação de chamada de ferramenta
    • Suporte a ferramentas de longa duração

  • Desenvolvimento, implantação e monitoramento otimizados

    • Crie agentes usando qualquer estrutura : encapsule qualquer agente existente usando a interface ResponsesAgent para obter compatibilidade pronta para uso com o AI Playground, Agent Evaluation e Monitoramento de Agentes.
    • Interfaces de Autoria Tipadas : Escrever código de agente usando classes Python tipadas, beneficiando-se do preenchimento automático da IDE e de notebooks.
    • Rastreamento automático : O MLflow agrega automaticamente as respostas de transmissão em rastreamentos para facilitar a avaliação e exibição.
    • Compatível com o esquema Responses da OpenAI : Consulte OpenAI: Respostas x Conclusão de Chat.

Ícone de robô. SDK de Agentes OpenAI

O padrão usa o SDK de Agentes da OpenAI como o framework de agentes para gerenciamento de conversas e orquestração de ferramentas. É possível criar agentes usando qualquer framework. A key é envolver seu agente com a interface MLflow ResponsesAgent.

Ícone do MCP. Servidores MCP (Protocolo de Contexto de Modelo)

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

Crie agentes usando assistentes de codificação de AI​

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

Etapa 3. Adicionar ferramentas ao seu agente​

Conceda ao seu agente funcionalidades como consultar bancos de dados, pesquisar documentos ou chamar APIs externas conectando-o a servidores MCP. O padrão de agente inclui uma conexão de servidor MCP default. Para adicionar mais ferramentas, configure servidores MCP adicionais no código do seu agente e conceda as permissões necessárias em databricks.yml.

Consulte Conecte agentes a ferramentas para tipos de ferramentas compatíveis e exemplos de código.

Defina ferramentas de função Python locais​

Para operações que não exigem fontes de dados externas ou APIs, defina ferramentas diretamente no código do seu agente. Essas ferramentas são executadas no mesmo processo que seu agente e são úteis para transformações de dados, cálculos ou operações de utilidade.

Use o decorador @function_tool do SDK do OpenAI Agents:

Python
from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

Ferramentas de função locais não exigem concessão de recursos em databricks.yml, porque são executadas dentro do processo do agente.

O passo 4. Gerencie o uso do LLM de seus agentes nos Databricks Apps com o Unity AI Gateway​

Encaminhe as chamadas LLM de seu agente através do Unity AI Gateway (Beta) para que cada solicitação seja governada pelos mesmos controles, independentemente de qual provedor a responda. Com o gateway no caminho da solicitação, é possível centralizar permissões, atribuir custos por aplicativo, trocar modelos e inspecionar ou reproduzir o tráfego sem modificar o código do agente ou alternar as credenciais do provedor.

info

Beta

Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a este recurso na página Pré-visualizações . Consulte Gerenciar prévias do Databricks.

  1. Habilite o Unity AI Gateway em seu workspace. O Unity AI Gateway é de adesão opcional durante a versão Beta. Um administrador de account deve ativá-lo na página **prévias** do console da account antes que você possa criar ou query Endpoint de gateway. Consulte Gerenciar prévias do Databricks.

  2. Aponte seu agente para um endpoint do Unity AI Gateway. No código do seu agente, passe o nome do endpoint do Unity AI Gateway como o argumento model e defina use_ai_gateway=True no cliente LLM do Databricks. O cliente roteia o tráfego através do gateway e lida com a autenticação automaticamente.

Python
from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)

Para superfícies de API adicionais (OpenAI Responses API, Anthropic Messages API, Google Gemini) e exemplos REST, consulte Consultar serviços de modelo.

Tópicos avançados de criação​

Respostas de transmissão

Respostas de transmissão​

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

  1. Emitir eventos delta : Envie vários eventos output_text.delta com o mesmo item_id para transmitir blocos de texto em tempo real.
  2. **Finalizar com evento concluído**: Envie um response.output_item.done evento final com o mesmo item_id que os eventos delta contendo o texto de saída final completo.

Cada evento delta transmite um fragmento de texto para o cliente. O evento final concluído contém o texto de resposta completo e sinaliza ao Databricks para fazer o seguinte:

  • Rastreie a saída do seu agente com o rastreamento do MLflow
  • Agregue as respostas de transmissão nas tabelas de inferência do Unity AI Gateway
  • Mostre a saída completa na interface do usuário do AI Playground

Propagação de erros de transmissão

O Databricks propaga quaisquer erros encontrados durante a transmissão com o último token em databricks_output.error. Cabe ao cliente chamador tratar e expor adequadamente este erro.

Bash
{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Entradas e saídas personalizadas

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, o MLflow ResponsesAgent suporta nativamente os campos custom_inputs e custom_outputs. Você pode acessar as entradas personalizadas via request.custom_inputs nos exemplos de framework acima.

O aplicativo de revisão do Agent Evaluation não oferece suporte para renderização de rastreamentos para agentes com campos de entrada adicionais.

Forneça custom_inputs no AI Playground e no aplicativo de análise

Se 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.

  1. No AI Playground ou no aplicativo de revisão de agente, selecione o ícone de engrenagem Ícone de engrenagem..

  2. Ativar **custom_inputs**.

  3. Forneça um objeto JSON que corresponda ao esquema de entrada definido do seu agente.

    Forneça custom_inputs no Playground de AI.

Passo 5. Execução do aplicativo do agente localmente​

Configure seu ambiente local:

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

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

  3. Execute os scripts de início rápido fornecidos para instalar 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 abrir a IU de chat integrada e começar a conversar com o agente.

Etapa 6. Configurar autenticação​

Seu agente precisa de autenticação para acessar recursos do Databricks. O Databricks Apps oferece dois métodos de autenticação: autorização de aplicativo (Service Principal) e autorização de usuário (em nome do usuário). Você pode configurar qualquer um deles através da UI do Workspace ou declarativamente em databricks.yml com os Pacotes de Automação Declarativa. Os modelos do agente são fornecidos com um databricks.yml, portanto, esse caminho é o default quando você começar de um modelo.

Para a referência completa, incluindo todos os tipos de recursos suportados, valores de permissão e um passo a passo databricks.yml de ponta a ponta, consulte Autenticação para agentes de AI.

A autorização do aplicativo usa um Service Principal que o Databricks cria automaticamente para seu aplicativo. Todos os usuários compartilham as mesmas permissões.

Declare cada recurso que o agente usa em resources.apps.<app>.resources em databricks.yml. Implante o bundle para conceder ao Service Principal as permissões declaradas:

YAML
resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'
Bash
databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para a lista completa de tipos de recurso, consulte Autorização do aplicativo.

Passo 7. Avalie o agente​

O padrão inclui código de avaliação de 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 em um terminal:

Bash
uv run agent-evaluate

Passo 8. Implantar o agente no Databricks Apps​

Após configurar a autenticação, implante seu agente no Databricks. Os padrões de agente usam Pacotes de Ativos do Databricks (DABs) para implantação. O arquivo databricks.yml no padrão define a configuração do aplicativo e as permissões de recurso. Certifique-se de que você tenha a Databricks CLI instalada e configurada.

nota

Se você criou seu aplicativo através da interface do usuário do Workspace na Passo 1, execute a execução databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve antes de implantar para vincular o aplicativo existente ao seu pacote. Caso contrário, databricks bundle deploy falha com “Já existe um aplicativo com o mesmo nome”.

  1. Valide a configuração do pacote para detectar erros antes da implantação:

    Bash
    databricks bundle validate

  2. Implante o pacote. Isso faz upload do seu código e configura recursos (experimento MLflow, Endpoint de disponibilização e assim por diante) definidos em databricks.yml:

    Bash
    databricks bundle deploy

  3. Inicie ou reinicie o aplicativo:

    Bash
    databricks bundle run agent_openai_agents_sdk
nota

bundle deploy apenas faz upload de arquivos e configura recursos. bundle run é necessário para começar ou reiniciar o aplicativo com o novo código.

Para atualizações futuras, execute databricks bundle deploy e, em seguida, databricks bundle run agent_openai_agents_sdk para reimplantar.

Passo 9. query o agente implantado​

O exemplo a seguir usa uma solicitação rápida de curl com um token OAuth. Tokens de acesso pessoal (PATs) não são compatíveis com o Databricks Apps.

Para a lista completa de métodos de query, incluindo o Cliente OpenAI do Databricks e a API REST, consulte Query um agente implantado no Databricks.

Gere um token OAuth usando a CLI do Databricks:

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

Use o token para query o agente:

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

Compreenda as assinaturas do modelo para garantir a compatibilidade com os recursos do Databricks​

Databricks usa MLflow Model Signatures para definir os esquemas de entrada e saída dos agentes. Recursos do produto como o AI Playground pressupõem que seu agente tenha um dos conjuntos de assinaturas de modelo compatíveis.

Se você seguir a abordagem recomendada para criar agentes usando a interface ResponsesAgent, o MLflow inferirá automaticamente uma assinatura para seu agente que será compatível com os recursos do produto Databricks.

Limitações​

Próximos passos​

Assim que seu agente funcionar em desenvolvimento, leve-o para produção. Consulte Coloque seu agente Databricks Apps em produção para a sequência recomendada: CI/CD, teste de carga e, em seguida, Unity AI Gateway.

Nesta página