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

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.

dica

Se o seu agente utiliza apenas ferramentas hospedadas Databrickse não precisa de lógica personalizada entre as chamadas de ferramentas, você pode usar a API Supervisor (Beta) para permitir que Databricks gerencie o loop do agente para você.

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

Cada agente de conversação padrão inclui uma interface de chat integrada (mostrada acima) sem necessidade de configuração adicional. A interface de chat suporta respostas de transmissão, renderização de Markdown, autenticação Databricks e histórico de chat persistente opcional.

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:

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.

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

  2. Clique em Agentes > Agente personalizado (SDK OpenAI) .

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

  4. 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:

  1. Copie o primeiro comando em Sincronizar os arquivos

    Sincronizar arquivos Databricks Apps

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

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:

Ícone de bate-papo Interface de chat integrada

O agente padrão busca e executa automaticamente o aplicativo de chat padrão como seu frontend. Essa interface de chat está integrada à mesma implantação do Databricks Apps e é fornecida juntamente com o seu agente, portanto, nenhuma configuração adicional é necessária.

Você pode personalizar a interface de bate-papo diretamente no seu projeto. Para obter mais detalhes sobre o recurso do aplicativo de bate-papo, incluindo como ativar o histórico de bate-papo persistente e a coleta de feedback do usuário, consulte Criar e compartilhar uma interface de usuário de bate-papo com Databricks Apps.

Ícone de chip. 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 /responses para consultar seu agente e gerencia automaticamente o roteamento de solicitações, registro e tratamento de erros.

Ícone quadrado entre colchetes. 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.

Ícone de robô. 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 .

Ícone do Mcp. 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.

o passo 3. Adicione ferramentas ao seu agente​

Dê ao seu agente funcionalidades como consultar bancos de dados, pesquisar documentos ou chamar APIs externas, conectando-o aos servidores MCP. O agente padrão 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 a seção Ferramentas de agentesAI para obter informações sobre os tipos de ferramentas compatíveis e exemplos de código.

Defina ferramentas de função Python locais​

Para operações que não requerem fonte de dados externa ou APIs, defina as ferramentas diretamente no código do seu agente. Essas ferramentas funcionam no mesmo processo do seu agente e são úteis para transformações de dados, cálculos ou transações de utilidades.

Use o decorador @function_tool do SDK de Agentes da OpenAI:

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],
)

As ferramentas de função local não requerem concessões de recursos em databricks.yml porque são executadas dentro do processo do agente.

Passo 4. Controle o uso LLM pelos seus agentes nos Databricks Apps com o Unity AI Gateway.​

Encaminhe as chamadas LLM do seu agente através do Unity AI Gateway (Beta) para que cada solicitação seja regida pelos mesmos controles, independentemente do provedor que a atenda. Com o gateway no caminho da requisição, você pode centralizar permissões, atribuir custo por aplicativo, swap modelos e inspecionar ou reproduzir o tráfego sem modificar o código do agente ou rotacionar as credenciais do provedor.

info

Beta

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

  1. Ative o Unity AI Gateway em seu workspace. O Unity AI Gateway é opcional durante a versão Beta. Um administrador account deve ativar essa opção na página de pré-visualizações do console account antes que você possa criar ou consultar o endpoint do gateway. Veja as prévias do Gerenciador Databricks.

  2. Direcione seu agente para um endpoint do Unity AI Gateway. No seu código de agente, passe o nome do endpoint do Unity AI Gateway como o argumento model e defina use_ai_gateway=True no cliente Databricks LLM. O cliente encaminha 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 obter mais informações sobre API ( API de Respostas OpenAI , API de Mensagens Anthropic , Google Gemini) e exemplos REST , consulte o endpoint de consulta do Unity AI Gateway.

Tópicos avançados de autoria​

respostas

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:

  1. 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.
  2. 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
  • Respostas agregadas de jogos em tabelas de inferência do Unity AI Gateway
  • Mostrar a saída completa na interface do usuário do AI Playground

propagação de erro de transmissão

Databricks propaga quaisquer erros encontrados durante a transmissão com os últimos tokens sob databricks_output.error. Cabe ao cliente que fez a chamada tratar e apresentar esse erro adequadamente.

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

  1. No AI Playground ou no aplicativo Agent Review, selecione o ícone de engrenagem Ícone de engrenagem..

  2. Habilite custom_inputs .

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

    Forneça custom_inputs no playground AI.

o 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 do Node) e a CLI 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 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 abrir a interface de chat integrada e começar a conversar com o agente.

o passo 6. Configurar autenticação​

Seu agente precisa de autenticação para acessar o recurso Databricks . O Databricks Apps oferece dois métodos de autenticação: autorização do aplicativo (entidade de serviço) e autorização do usuário (em nome do usuário). Você pode configurar qualquer um deles através da interface do usuário workspace ou declarativamente em databricks.yml com pacotes de automação declarativa. O agente padrão vem com um databricks.yml, então esse caminho é o default quando você inicia a partir de um padrão.

Para obter 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 AI.

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.

Declare todos os recursos que o agente usa sob resources.apps.<app>.resources em databricks.yml. implementou o pacote para conceder à entidade de serviço 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 obter a lista completa de tipos de recursos, consulte Autorização de aplicativo.

o passo 7. 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 8. implantou o agente para Databricks Apps​

Após configurar a autenticação, implante seu agente no Databricks. O agente padrão usa Databricks ativo Bundles (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 ter o Databricks CLI instalado e configurado.

nota

Se você criou seu aplicativo através da interface do usuário do espaço de trabalho na etapa 1, execute 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. implantar o pacote. Este comando carrega seu código e configura o recurso (experimento MLflow , endpoint de serviço, etc.) definido em databricks.yml:

    Bash
    databricks bundle deploy

  3. Iniciar ou reiniciar o aplicativo:

    Bash
    databricks bundle run agent_openai_agents_sdk
nota

bundle deploy Apenas faça o upload de arquivos e configure o recurso. bundle run é necessário para iniciar ou reiniciar o aplicativo com o novo código.

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

o passo 9. Consulte o agente implantado​

O exemplo a seguir usa uma solicitação rápida curl com tokens OAuth . access tokens pessoal (PATs) não são suportados para Databricks Apps.

Para obter a lista completa de métodos de consulta, incluindo o Databricks OpenAI Client e a API REST, consulte Consultar um agente implantado no Databricks.

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>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Limitações​

Próximas etapas​

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

Nesta página