Ligue agentes a dados estruturados

Escolha uma ferramenta com base nos dados de que o seu agente precisa e em função de quem escreve a consulta:

Consultar dados com o Genie One

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

Siga Use ferramentas MCP num agente Python e defina server_url para o URL MCP do Genie One:

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 os 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 skill de descoberta de dados, que consulta o Genie One através da CLI do Databricks.

Consulta um Genie Agent específico a partir de Python

Use o AI Bridge para expor um agente Genie específico como ferramenta no seu agente Python. O AI Bridge gere solicitações, sondagens e resultados de consulta através da API Genie.

Para o Claude Code ou Codex, instala Databricks AI Tools para usar a skill Genie Agents através da CLI do Databricks.

Antes de começares

1. Use Python 3.12. Para desenvolvimento local, inicia sessão com a CLI da Databricks, usando o DEFAULT perfil para que os clientes Python possam encontrar as tuas credenciais.
2. Escolha um Agente Genie ao qual a sua identidade possa aceder, com as permissões de armazém e dados necessárias. Copia o ID de espaço dele das Definições e substitui <genie-agent-id> por esse ID.
3. Substitua <model-endpoint> por um endpoint de modelo do Azure Databricks que suporte chamada de ferramenta e ao qual tem permissão de consulta.
4. Executa o comando de instalação do teu framework num terminal. Num caderno, usa %pip e reinicia o Python após a instalação. Execute exemplos com await num notebook que suporte await de nível superior.

Executa o teu agente

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

LangGraph

Este exemplo encapsula o helper 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 OpenAI

Este exemplo utiliza o AI Bridge Genie cliente e o decorador do function_tool SDK OpenAI Agents. O modelo é executado 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 chama ask_genie e utiliza o resultado. Estes exemplos iniciam uma nova conversa Genie para cada chamada de ferramenta. Para manter o contexto, guarde o ID da conversa devolvido para a conversa de cada utilizador e transmita-o na próxima chamada:

• GenieAgent: ler response["conversation_id"] e incluir "conversation_id" ao lado de "messages" no dicionário de entrada seguinte.
• Genie: ler response.conversation_id e passar como conversation_id a ask_question().

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

Ao hospedar o seu agente nas aplicações Databricks, adicione o Agente Genie como recurso de aplicação com permissão Pode executar . O principal de serviço da aplicação também precisa de acesso ao endpoint do modelo, ao armazém subjacente e aos dados.

Execute SQL com o Databricks SQL MCP

Usa o Databricks SQL MCP quando o teu agente precisar de escrever e executar SQL contra as 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 da consola da conta. Consulte as pré-visualizações da gestão de conta.

Siga Use ferramentas MCP num 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. Pede ao agente para executar SELECT 1 AS result e confirmar se ele chama a ferramenta e devolve 1.

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

Execute uma consulta pré-definida com uma função do Unity Catalog

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

O exemplo seguinte cria uma função Unity Catalog chamada lookup_customer_info. Assume-se que tem uma customer_data tabela com customer_name, customer_id e customer_email colunas.

Revise os requisitos e permissões da função. Substitui my_catalog.my_schema por um catálogo e esquema onde possas criar funções e adaptar os nomes das tabelas e colunas aos teus dados. Execute o seguinte código num 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 usa o Unity Catalog AI para adicionar a função ao teu agente. Esse guia inclui exemplos do LangGraph, OpenAI, Anthropic e LlamaIndex.

Usar o Genie num sistema multiagente

Para coordenar os Genie Agents com outros agentes e ferramentas, veja Agente Supervisor. Para integrações existentes de Model Serviring, consulte Utilizar o Genie em sistemas multiagente.

Consultar um Agente Genie usando MCP

Para se ligar a um Agente Genie específico através do MCP, consulte a referência do Agente Genie MCP para o seu URL e requisitos. Para consultar um Agente Genie a partir de Python sem MCP, use exemplos da ferramenta AI Bridge.