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

Conectar agentes a dados estruturados

Escolha uma ferramenta com base nos dados de que seu agente precisa e em quem escreve a query:

Seu agente precisa

Uso

Responder a perguntas de negócios em todo o workspace

Genie One MCP

Query um Genie Agent curado do Python

Ferramentas do AI Bridge

Escrever e execução de SQL

Databricks SQL MCP

Execução uma query predefinida com parâmetros

Ferramentas de função do Unity Catalog

Seu agente precisa

Uso

Responder a perguntas de negócios em todo o workspace

Genie One MCP

Query um Genie Agent curado do Python

Ferramentas do AI Bridge

Escrever e execução de SQL

Databricks SQL MCP

Execução uma query predefinida com parâmetros

Ferramentas de função do Unity Catalog

query dados com o Genie One​

A Databricks recomenda o Genie One MCP para agentes que respondem a perguntas de negócios em todo o workspace usando linguagem natural. Ele usa a Genie Ontology para interpretar termos de negócios e faz a query dos dados do seu workspace usando as permissões de quem fez a chamada.

Siga Use as ferramentas MCP em um agente Python e defina server_url para a URL do Genie One MCP:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.genie_one_mcp

Substitua <workspace-hostname> pelo hostname do seu workspace. Em seguida, faça uma pergunta ao seu agente sobre os dados, como "Quais foram os 10 principais clientes por receita no último trimestre?"

Para o Claude Code ou o Codex, instale o Databricks AI Tools e use a habilidade de descobrimento de dados, que consulta o Genie One por meio da CLI do Databricks.

query um Genie Agent específico a partir do Python​

Use o AI Bridge para expor um Genie Agent específico como uma ferramenta em seu agente em Python. O AI Bridge gerencia solicitações, polling e resultados de query por meio da Genie API.

For Claude Code or Codex, install Databricks AI Tools to use the Genie Agents skill through the Databricks CLI.

Antes de começar​

  1. Use Python 3.12. For local development, sign in with the Databricks CLI, using the DEFAULT profile so the Python clients can find your credentials.
  2. Choose a Genie Agent that your identity can access, with the required warehouse and data permissions. Copy its space ID from Settings and replace <genie-agent-id> with that ID.
  3. Substitua <model-endpoint> por um Databricks model endpoint que ofereça suporte à chamada de ferramentas e que você tenha permissão para fazer query.
  4. Faça a execução do comando de instalação para sua estrutura em um terminal. Em um notebook, use %pip e reinicie o Python após a instalação. execução exemplos com await em um notebook que dê suporte a await de nível superior.

execução seu agente​

Ambos os exemplos permitem que o modelo chame ask_genie e use o resultado em sua resposta. O cliente Genie de databricks-ai-bridge também pode ser encapsulado como uma ferramenta de função Python em outros frameworks. A tab do OpenAI Agents SDK exibe este cliente sem uma dependência do LangChain.

This example wraps AI Bridge's GenieAgent helper as a LangChain tool.

Bash
pip install --upgrade databricks-langchain langgraph
Python
from databricks_langchain import ChatDatabricks
from databricks_langchain.genie import GenieAgent
from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent

genie = GenieAgent(genie_space_id="<genie-agent-id>")


@tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    response = genie.invoke({
        "messages": [{"role": "user", "content": question}]
    })
    return response["messages"][-1].content


agent = create_react_agent(
    ChatDatabricks(endpoint="<model-endpoint>"),
    tools=[ask_genie],
)
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": "Use Genie to find total sales last month.",
    }]
})
print(result["messages"][-1].content)

Verifique a saída ou os rastreamentos do agente para confirmar se ele chama ask_genie e usa o resultado. Estes exemplos começam uma nova conversa do Genie para cada chamada de ferramenta. Para reter o contexto, salve o ID da conversa retornado para a conversa de cada usuário e repasse-o na chamada seguinte:

  • GenieAgent: leia response["conversation_id"] e inclua "conversation_id" juntamente com "messages" no próximo dicionário de entrada.
  • Genie: leia response.conversation_id e passe-o como conversation_id para ask_question().

Para ver as opções do cliente e detalhes de implementação, consulte o repository do AI Bridge, incluindo o helperGenieAgent e o clienteGenie.

Ao hospedar seu agente no Databricks Apps, adicione o Genie Agent como um recurso do aplicativo com a permissão de execução . O service principal do aplicativo também precisa de acesso ao endpoint do modelo e ao warehouse e aos dados subjacentes.

Execução de SQL com o Databricks SQL MCP​

Use o Databricks SQL MCP quando seu agente precisar escrever e fazer a execução de SQL em suas tabelas do Unity Catalog.

Para usar system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, um administrador de account deve habilitar a versão beta do Unity Gateway na página Previews do console da account. See Gerenciar account previews.

Siga Usar ferramentas MCP em um agente Python e defina server_url como:

Text
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

Replace <workspace-hostname> with your workspace hostname. Ask the agent to execução SELECT 1 AS result and confirm that it calls the tool and returns 1.

Para agentes de codificação, use o guia de configuração do agente. Para a seleção de warehouse e opções específicas de SQL, consulte a referência do Databricks SQL MCP.

execução uma query predefinida com uma função do Unity Catalog​

Crie uma ferramenta de recuperação estruturada usando funções SQL do Unity Catalog quando a query for conhecida antecipadamente e o agente fornecer os parâmetros.

O exemplo a seguir cria uma função do Unity Catalog chamada lookup_customer_info. Ele pressupõe que você tenha uma tabela customer_data com colunas customer_name, customer_id e customer_email.

Revise os requisitos e permissões de função. Substitua my_catalog.my_schema por um catálogo e um esquema onde você possa criar funções e adapte os nomes de tabela e de coluna aos seus dados. Execute o seguinte código em um editor SQL:

SQL
CREATE FUNCTION my_catalog.my_schema.lookup_customer_info(
  customer_name_input STRING COMMENT 'Name of the customer whose info to look up'
)
RETURNS STRING
COMMENT 'Returns metadata about a particular customer, given the customer''s name, including the customer''s email and ID. The
customer ID can be used for other queries.'
RETURN SELECT CONCAT(
    'Customer ID: ', customer_id, ', ',
    'Customer Email: ', customer_email
  )
  FROM my_catalog.my_schema.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

Test the function with a customer name from your table:

SQL
SELECT my_catalog.my_schema.lookup_customer_info('Example Customer');

Em seguida, use o Unity Catalog AI para adicionar a função ao seu agente. Esse guia inclui exemplos do LangGraph, OpenAI, Anthropic e LlamaIndex.

Usar o Genie em um sistema multiagente​

Para coordenar os agentes do Genie com outros agentes e ferramentas, consulte Agente supervisor. Para integrações do Model Serving existentes, consulte Use Genie in multi-agent systems.

Faça query a um Genie Agent usando MCP (legado)​

Para obter uma integração MCP existente com um Genie Agent específico, consulte a referência legada do MCP do Genie Agent para ver sua URL e seus requisitos. Para novos agentes Python, use os exemplos da ferramenta AI Bridge.

Nesta página