Crie um agente de IA e implemente-o nas aplicações Databricks

Constrói um agente de IA e implementa-o usando as aplicações Databricks. O Databricks Apps dá-lhe controlo total sobre o código do agente, configuração do servidor e fluxo de trabalho de implementação. Esta abordagem é ideal quando se precisa de comportamento personalizado de servidores, versionamento baseado em git ou desenvolvimento local de IDE.

Tip

Se o seu agente usar apenas ferramentas alojadas em Azure Databricks e não precisar de lógica personalizada entre chamadas de ferramenta, pode usar a API Supervisor (Beta) para Azure Databricks gerir o ciclo do agente por si.

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

Cada modelo de agente conversacional inclui uma interface de chat integrada (mostrada acima) sem necessidade de configuração adicional. A interface de chat suporta respostas em streaming, renderização por markdown, autenticação Databricks e histórico opcional de chat persistente.

Requerimentos

Ative as aplicações Databricks no seu espaço de trabalho. Consulte Configurar seu espaço de trabalho e ambiente de desenvolvimento do Databricks Apps.

Passo 1. Clonar o modelo de aplicação do agente

Comece por usar um modelo de agente pré-construído do repositório de templates da aplicação Databricks.

Este tutorial utiliza o agent-openai-agents-sdk modelo, que inclui:

Um agente criado usando OpenAI Agent SDK
Código inicial para uma aplicação 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 modelo:

Interface do usuário do espaço de trabalho

Instala o modelo da aplicação usando a interface do Workspace. Isto instala a aplicação e implementa-a num recurso de computação no seu espaço de trabalho. Pode então sincronizar os ficheiros da aplicação para o seu ambiente local para desenvolvimento futuro.

No seu espaço de trabalho Databricks, clique em + Nova>Aplicação.
Clique em Agentes>Personalizados (OpenAI SDK).
Crie um novo experimento MLflow com o nome openai-agents-template e complete o resto da configuração para instalar o modelo.
Depois de criares a aplicação, clica no URL da aplicação para abrir a interface do chat.

Depois de criar a aplicação, descarregue o código-fonte para a sua máquina local para a personalizar:

Copie o primeiro comando em Sincronizar os ficheiros
Num terminal local, executa o comando copiado.

Clonar do GitHub

Para começar a partir de um ambiente local, clone o repositório de modelos de agente e abra o agent-openai-agents-sdk diretório:

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk

Passo 2. Compreenda a candidatura do agente

O modelo de agente demonstra uma arquitetura pronta para produção com estes componentes-chave. Abra as secções seguintes para mais detalhes sobre cada componente:

Diagrama simples do Agente na App

Abra as secções seguintes para mais detalhes sobre cada componente:

Interface de chat integrada

O modelo de agente recolhe automaticamente e executa o modelo da aplicação de chat como interface. Esta interface de chat é incluída na mesma implementação do Databricks Apps e servida juntamente com o seu agente, pelo que não é necessária qualquer configuração adicional.

Podes personalizar a interface de chat diretamente no teu projeto. Para mais detalhes sobre as funcionalidades da aplicação de chat, incluindo como ativar o histórico persistente de chat e a recolha de feedback dos utilizadores, consulte Construir e partilhar uma interface de chat com as aplicações Databricks.

MLflow AgentServer

Um servidor FastAPI assíncrono que gere pedidos de agente com rastreamento e observabilidade incorporados. O AgentServer fornece o /responses endpoint para consultar o seu agente e gere automaticamente o encaminhamento dos pedidos, o registo e o tratamento de erros.

ResponsesAgent Interface

O Databricks recomenda o MLflow ResponsesAgent para construir agentes. ResponsesAgent permite criar agentes com qualquer estrutura de terceiros e, em seguida, integrá-la aos recursos de IA do Databricks para recursos robustos de registro, rastreamento, avaliação, implantação e monitoramento.

O ResponsesAgent encapsula facilmente agentes existentes para compatibilidade com Databricks.

Para aprender a criar um ResponsesAgent, veja os exemplos na documentação do MLflow - ResponsesAgent for Model Serving.

ResponsesAgent oferece os seguintes benefícios:

Recursos avançados do agente
- Suporte a vários agentes
- Saída de streaming: transmita a saída em partes menores.
- Histórico abrangente de mensagens de chamada de ferramentas: Devolve várias mensagens, incluindo mensagens intermediárias de chamada de ferramentas, para aperfeiçoar a qualidade e o gerenciamento das conversas.
- Suporte de confirmação de invocação de ferramenta
- Suporte para ferramentas operacionais de longa duração
Desenvolvimento, implantação e monitoramento simplificados
- Crie agentes usando qualquer estrutura: envolva qualquer agente existente usando a interface para obter compatibilidade imediata com o AI Playground, a Avaliação de Agentes e o ResponsesAgent Monitoramento de Agentes.
- Interfaces de autoria tipadas: Escrever código de agente usando classes de Python tipadas, beneficiando do autocompletar do IDE e do notebook.
- Rastreamento automático: O MLflow agrega automaticamente as respostas em fluxo em traços para facilitar a avaliação e visualização.
- Compatível com o esquema OpenAIResponses: Veja OpenAI: Respostas vs. ChatCompletion.

SDK de Agentes OpenAI

O modelo utiliza o OpenAI Agents SDK como framework de agentes para gestão de conversas e orquestração de ferramentas. Podes criar agentes usando qualquer framework. A chave é envolver o seu agente com a interface MLflow ResponsesAgent.

Servidores MCP (Model Context Protocol)

O template liga-se aos servidores MCP do Databricks para dar aos agentes acesso a ferramentas e fontes de dados. Consulte Protocolo de contexto de modelo (MCP) em Databricks.

Agentes que criam usando assistentes de codificação com IA

A Databricks recomenda o uso de assistentes de programação por IA como Claude, Cursor e Copilot para criar agentes. Use as competências de agente fornecidas, em /.claude/skills, e o AGENTS.md ficheiro para ajudar os assistentes de IA a compreender a estrutura do projeto, as ferramentas disponíveis e as melhores práticas. Os agentes podem ler automaticamente esses ficheiros para desenvolver e implementar as aplicações Databricks.

Passo 3. Adicione ferramentas ao seu agente

Dá ao teu agente capacidades como consultar bases de dados, pesquisar documentos ou chamar APIs externas, ligando-o a servidores MCP. O template do agente inclui uma ligação padrão ao servidor MCP. 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 as ferramentas de agentes de IA para tipos de ferramentas suportados e exemplos de código.

Definir ferramentas de função Python local

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

SDK de agentes OpenAI

Use o @function_tool decorador do SDK OpenAI Agents:

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

LangGraph

Use o @tool decorador de LangChain:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

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

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

As ferramentas de funções locais não exigem concessões de recursos em databricks.yml porque executam dentro do processo do agente.

Passo 4. Regule o uso de LLMs pelos seus agentes nas aplicações Databricks com o Unity AI Gateway

Encaminhe as chamadas LLM do seu agente através do AI Gateway (Beta) para que cada pedido seja regido pelos mesmos controlos, independentemente do fornecedor que responda. Com o gateway no caminho do pedido, pode centralizar permissões, atribuir o custo por aplicação, alternar modelos e inspecionar ou reproduzir o tráfego sem modificar o código do agente ou alterar as credenciais do fornecedor.

Important

Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a esse recurso na página Visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

Ative o AI Gateway no seu espaço de trabalho. O AI Gateway é opcional durante a fase Beta. Um administrador de conta tem de o ativar na página de Pré-visualizações da consola da conta antes de poder criar ou consultar endpoints de gateway. Ver Gerir as pré-visualizações de Azure Databricks.

Aponta o teu agente para um endpoint de IA Gateway. No código do teu agente, passa o nome do endpoint AI Gateway como argumento model e define use_ai_gateway=True no cliente LLM Azure Databricks. O cliente encaminha o tráfego através do gateway e gere a autenticação automaticamente.

OpenAI

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

LangGraph

from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)

Para interfaces adicionais de API (OpenAI Responses API, Anthropic Messages API, Google Gemini) e exemplos REST, veja Consultar endpoints do Unity AI Gateway.

Tópicos avançados de autoria

Respostas em streaming

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

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

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

Rastreie a saída do seu agente com o rastreamento MLflow
Agregar respostas transmitidas em fluxo nas tabelas de inferência do AI Gateway
Mostrar a saída completa na interface do usuário do AI Playground

Propagação de erros de streaming

O Mosaic AI propaga quaisquer erros que sejam encontrados durante o streaming sob o último token em databricks_output.error. Cabe ao cliente que faz a chamada lidar adequadamente e tratar esse erro.

{
  "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 fontes de recuperação, que não devem constar no histórico de conversas para interações futuras.

Para esses cenários, o MLflow ResponsesAgent suporta nativamente os campos custom_inputs e custom_outputs. Podes aceder às entradas personalizadas através request.custom_inputs dos exemplos do framework acima.

O aplicativo de revisão de Avaliação do Agente não suporta a renderização de rastros para agentes com campos de entrada adicionais.

Fornecer custom_inputs no AI Playground e na aplicação de revisão

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

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

Passo 5. Executa a aplicação do agente localmente

Configure o seu ambiente local:

Instale uv (gestor de pacotes Python), nvm (gestor de versões Node) e a CLI Databricks:
- uv Instalação
- nvm Instalação
- Execute o seguinte para usar o Node 20 LTS:
```
nvm use 20
```
- databricks CLI Instalação
Muda o diretório para a agent-openai-agents-sdk pasta.
Executa os scripts de início rápido fornecidos para instalar dependências, configurar o ambiente e iniciar a aplicação.
```
uv run quickstart
uv run start-app
```

No navegador, vá para http://localhost:8000 para abrir a interface de chat integrada e comece a conversar com o agente.

Passo 6. Configurar a autenticação

O seu agente precisa de autenticação para aceder aos recursos do Azure Databricks. O Databricks Apps fornece dois métodos de autenticação: autorização de aplicação (principal de serviço) e autorização do utilizador (em nome do utilizador). Podes configurar um deles através da interface do espaço de trabalho ou de forma declarativa em databricks.yml com os Declarative Automation Bundles. Os templates de agente vêm com um databricks.yml, por isso esse caminho é o padrão quando começas a partir de um template.

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

Autorização de aplicação (por defeito)

A autorização de aplicações utiliza um princípio de serviço que o Azure Databricks cria automaticamente para a sua aplicação. Todos os utilizadores partilham as mesmas permissões.

Declare todos os recursos que o agente utiliza sob resources.apps.<app>.resources em databricks.yml. Implemente o pacote para conceder ao principal do serviço as permissões declaradas:

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'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para a lista completa de tipos de recursos, veja Autorização de aplicações.

Autorização do utilizador

A autorização do utilizador permite ao seu agente agir com as permissões individuais de cada utilizador. Use isto quando precisar de controlo de acesso por utilizador ou de registos de auditoria.

Adicione este código ao seu agente:

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)

Important

Inicialize get_user_workspace_client() dentro das suas funções @invoke ou @stream, não durante o arranque da aplicação. As credenciais de utilizador só existem ao lidar com um pedido.

Configure quais Azure Databricks APIs o agente pode invocar em nome do utilizador, adicionando escopos sob user_api_scopes na aplicação em databricks.yml:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Para a lista de escopos disponíveis e instruções completas de configuração, veja Autorização do Utilizador.

Passo 7. Avaliar o agente

O modelo inclui código de avaliação de agentes. Consulte agent_server/evaluate_agent.py para obter mais informações. Avalie a relevância e segurança das respostas do seu agente executando o seguinte num terminal:

uv run agent-evaluate

Passo 8. Implementar o agente para as aplicações Databricks

Depois de configurar a autenticação, implemente o seu agente no Azure Databricks. Os templates de agentes utilizam Databricks Asset Bundles (DABs) para implementação. O databricks.yml ficheiro no modelo define a configuração da aplicação e as permissões de recursos. Certifique-se de que tem a CLI do Databricks instalada e configurada.

Observação

Se criaste a tua aplicação através da interface do Workspace no Passo 1, executa databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve antes de implementar para vincular a aplicação existente ao teu bundle. Caso contrário, databricks bundle deploy falha com "Uma aplicação com o mesmo nome já existe".

Valide a configuração do bundle para detetar erros antes de implementar:
```
databricks bundle validate
```
Lança o pacote. Isto carrega o seu código e configura recursos (experiência MLflow, endpoints de serviço, etc.) definidos em databricks.yml:
```
databricks bundle deploy
```
Inicie ou reinicie a aplicação:
```
databricks bundle run agent_openai_agents_sdk
```
Observação

bundle deploy apenas carrega ficheiros e configura recursos. bundle run é necessário para iniciar ou reiniciar a aplicação com o novo código.

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

Passo 9. Consultar o agente implementado

O exemplo seguinte utiliza um pedido rápido curl com um token OAuth. Tokens de acesso pessoal (PATs) não são suportados para aplicações Databricks.

Para a lista completa de métodos de consulta, incluindo o cliente Databricks OpenAI e a API REST, veja Query an agent implementado em Azure Databricks.

Gerar um token OAuth usando a CLI Databricks:

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

Utilize o token para consultar o agente:

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

Apenas tamanhos de computação médios e grandes são suportados. Veja Configurar recursos de computação para uma aplicação Databricks.
A interface de chat da MLflow Review App não suporta atualmente agentes implementados nas aplicações Databricks. Para avaliar os traços existentes, utilize sessões de rotulagem, que funcionam independentemente do método de implementação. A Databricks está a integrar suporte de revisão e feedback diretamente no modelo do chatbot.

Passos seguintes

Teste o seu agente Databricks Apps

Comentários

Esta página foi útil?

Last updated on 2026-05-03

Crie um agente de IA e implemente-o nas aplicações Databricks

Requerimentos

Passo 1. Clonar o modelo de aplicação do agente

Interface do usuário do espaço de trabalho

Clonar do GitHub

Passo 2. Compreenda a candidatura do agente

Agentes que criam usando assistentes de codificação com IA

Passo 3. Adicione ferramentas ao seu agente

Definir ferramentas de função Python local

SDK de agentes OpenAI

LangGraph

Passo 4. Regule o uso de LLMs pelos seus agentes nas aplicações Databricks com o Unity AI Gateway

OpenAI

LangGraph

Tópicos avançados de autoria

Respostas em streaming

Entradas e saídas personalizadas

Passo 5. Executa a aplicação do agente localmente

Passo 6. Configurar a autenticação

Autorização de aplicação (por defeito)

Autorização do utilizador

Passo 7. Avaliar o agente

Passo 8. Implementar o agente para as aplicações Databricks

Passo 9. Consultar o agente implementado

Limitações

Passos seguintes

Comentários

Recursos adicionais