Conectar agentes a dados estruturados

Escolha uma ferramenta baseada nos dados que seu agente precisa e em quem escreve a consulta:

Consultar dados com o Genie One

O Azure Databricks recomenda o Genie One MCP para agentes que respondem perguntas de negócios em todo o espaço de trabalho em linguagem natural. Ele utiliza a Ontologia Genie para interpretar termos de negócios e consulta os dados do seu espaço de trabalho usando as permissões do chamador.

Siga as instruções em Usar ferramentas MCP em um agente Python e defina a server_url URL do Genie One MCP:

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

Substitua <workspace-hostname> pelo nome de host do seu espaço de trabalho. Depois, faça uma pergunta ao seu agente sobre seus dados, como "Quais foram os 10 maiores clientes por receita no último trimestre?"

Para Claude Code ou Codex, instale o Databricks AI Tools e use a habilidade de descoberta de dados, que consulta o Genie One através da linha de comando do Databricks.

Consulte um agente Genie específico a partir do Python

Use o AI Bridge para expor um Agente Genie específico como uma ferramenta em seu agente Python. O AI Bridge gerencia solicitações, polling e resultados de consultas através da API do Genie.

Para Claude Code ou Codex, instale Databricks AI Tools para usar a habilidade Genie Agents através da linha de comando do Databricks.

Antes de começar

1. Use o Python 3.12. Para desenvolvimento local, faça login com a interface de comando do Databricks, usando o DEFAULT perfil para que os clientes Python possam encontrar suas credenciais.
2. Escolha um Agente Genie que sua identidade possa acessar, com as permissões necessárias de warehouse e dados. Copie o ID de espaço dele das Configurações e substitua <genie-agent-id> por esse ID.
3. Substitua <model-endpoint> por um endpoint do modelo Azure Databricks que suporte chamada de ferramentas e que você tenha permissão para consultar.
4. Execute o comando de instalação do seu framework em um terminal. Em um notebook, use %pip e reinicie o Python após a instalação. Execute os exemplos com o await em um notebook que suporte o nível superior await.

Execute seu agente

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

LangGraph

Este exemplo encapsula o auxiliar do AI Bridge GenieAgent como uma ferramenta LangChain.

pip install --upgrade databricks-langchain langgraph

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)

SDK de agentes do OpenAI

Este exemplo usa o AI Bridge Genie client e o decorador do function_tool SDK OpenAI Agents. O modelo roda no Azure Databricks.

pip install --upgrade databricks-ai-bridge databricks-openai openai-agents

from agents import Agent, Runner, function_tool
from agents import set_default_openai_api, set_default_openai_client
from agents.tracing import set_trace_processors
from databricks_ai_bridge.genie import Genie
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI())
set_default_openai_api("chat_completions")
set_trace_processors([])
genie = Genie(space_id="<genie-agent-id>", return_pandas=False)


@function_tool
def ask_genie(question: str) -> str:
    """Ask the configured Genie Agent a question about its business data."""
    return genie.ask_question(question).result


agent = Agent(
    name="Data analyst",
    instructions="Use ask_genie to answer questions about business data.",
    model="<model-endpoint>",
    tools=[ask_genie],
)
result = await Runner.run(agent, "What were total sales last month?")
print(result.final_output)

Verifique a saída ou os traços do agente para confirmar que ele chama ask_genie e usa o resultado. Esses exemplos iniciam uma nova conversa do Genie para cada chamada de ferramenta. Para manter o contexto, salve o ID de conversa retornado para cada conversa do usuário e passe na próxima chamada:

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

Para opções do cliente e detalhes de implementação, veja o repositório AI Bridge, incluindo o GenieAgent helper e o Genie cliente.

Ao hospedar seu agente nos aplicativos Databricks, adicione o Agente Genie como um recurso de app com permissão Pode executar . O principal de serviço do app também precisa de acesso ao endpoint do modelo, ao warehouse subjacente e aos dados.

Execute SQL com o Databricks SQL MCP

Use o Databricks SQL MCP quando seu agente precisar escrever e rodar SQL nas suas tabelas do Unity Catalog.

Para usar system.ai.dbsql, system.ai.sandbox, ou system.ai.web_search, um administrador de conta deve ativar a versão beta do Unity Gateway a partir da página de Pré-visualizações do console da conta. Veja Gerenciar visualizações da conta.

Siga Use ferramentas MCP em um agente Python e defina server_url para:

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

Substitua <workspace-hostname> pelo nome de host do seu espaço de trabalho. Peça para o agente executar SELECT 1 AS result e confirmar se ele chama a ferramenta e retorna 1.

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

Execute uma consulta predefinida com uma função do Unity Catalog

Crie uma ferramenta de recuperação estruturada utilizando as funções SQL do Catálogo Unity quando a consulta já é conhecida e o agente fornece os parâmetros.

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

Revise os requisitos e permissões da função. Substitua my_catalog.my_schema por um catálogo e esquema onde você possa criar funções e adapte os nomes das tabelas e colunas aos seus dados. Execute o seguinte código em um editor 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;

Teste a função com o nome de um cliente da sua tabela:

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

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

Use o Genie em um sistema multiagente

Para coordenar Agentes Genie com outros agentes e ferramentas, consulte Agente Supervisor. Para integrações existentes com Model Serving, veja Use o Genie em sistemas multiagente.

Consultar um Agente Genie usando MCP

Para se conectar a um Agente Genie específico via MCP, veja a referência do Agente Genie MCP para sua URL e requisitos. Para consultar um Agente Genie a partir de Python sem MCP, use exemplos da ferramenta AI Bridge.