Conexión de agentes a datos estructurados

Elige una herramienta basada en los datos que necesita tu agente y en quién redacta la consulta:

Consulta datos con Genie One

Azure Databricks recomienda el Genie One MCP para agentes que responden preguntas de negocio en todo el espacio de trabajo en lenguaje natural. Utiliza Genie Ontology para interpretar términos de negocio y consulta los datos de tu espacio de trabajo utilizando los permisos del llamante.

Sigue Utiliza herramientas MCP en un agente Python y configura server_url con la URL MCP de Genie One:

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

Reemplaza <workspace-hostname> por el nombre de host de tu espacio de trabajo. Luego haz una pregunta a tu agente sobre tus datos, como "¿Cuáles fueron los 10 clientes más importantes por ingresos el último trimestre?"

Para Claude Code o Codex, instala Databricks AI Tools y utiliza la habilidad de descubrimiento de datos, que consulta Genie One a través de la CLI de Databricks.

Consulta a un agente Genie específico desde Python

Usa AI Bridge para exponer un agente Genie específico como herramienta en tu agente Python. AI Bridge gestiona solicitudes, sondeos y resultados de consultas a través de la API de Genie.

Para Claude Code o Codex, instala Databricks AI Tools para usar la habilidad Genie Agents a través de la CLI de Databricks.

Antes de empezar

1. Usa Python 3.12. Para desarrollo local, inicia sesión con la CLI de Databricks, usando el DEFAULT perfil para que los clientes de Python puedan encontrar tus credenciales.
2. Elige un Agente Genie al que tu identidad pueda acceder, con los permisos de almacén y datos necesarios. Copia su ID de espacio desde Configuración y reemplaza <genie-agent-id> por ese ID.
3. Sustituye <model-endpoint> por un endpoint de modelo de Azure Databricks que soporte llamada a herramientas y para el que tengas permiso para consultar.
4. Ejecuta el comando de instalación de tu framework en un terminal. En un cuaderno, usa %pip y reinicia Python después de la instalación. Ejecuta ejemplos con await en un notebook que soporte await de nivel superior.

Ejecuta tu agente

Ambos ejemplos permiten que el modelo llame a ask_genie y use el resultado en su respuesta. El Genie cliente de databricks-ai-bridge también puede envolverse como una herramienta de función en Python en otros frameworks. La pestaña del SDK de Agentes OpenAI muestra este cliente sin dependencia de LangChain.

LangGraph

En este ejemplo se encapsula el GenieAgent de AI Bridge como una herramienta de 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 de OpenAI

Este ejemplo utiliza el AI Bridge Genie client y el decorador del SDK de OpenAI Agents function_tool. El modelo funciona en 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)

Comprueba la salida o las trazas del agente para confirmar que llama a ask_genie y utiliza el resultado. Estos ejemplos inician una nueva conversación con Genie para cada llamada a la herramienta. Para mantener el contexto, guarda el ID de conversación devuelto de cada conversación de usuario y pásalo en la siguiente llamada:

• GenieAgent: lee response["conversation_id"] e incluye "conversation_id" junto a "messages" en el siguiente diccionario de entrada.
• Genie: lee response.conversation_id y pásalo como argumento conversation_id a ask_question().

Para opciones del cliente y detalles de implementación, consulte el repositorio AI Bridge, incluyendo el GenieAgent helper y el Genie cliente.

Cuando alojes tu agente en las aplicaciones de Databricks, añade el Agente Genie como recurso de aplicación con permiso Can run. La entidad de servicio de la aplicación también necesita acceso al punto de conexión del modelo, al almacén subyacente y a los datos.

Ejecuta SQL con el Databricks SQL MCP

Usa el Databricks SQL MCP cuando tu agente necesite escribir y ejecutar SQL en tus tablas de Unity Catalog.

Para usar system.ai.dbsql, system.ai.sandbox o system.ai.web_search, un administrador de cuenta debe habilitar la beta de Unity Gateway desde la página de Previews de la consola de la cuenta. Consulte Administrar vistas previas de la cuenta.

Siga Utilizar herramientas MCP en un agente de Python y establezca server_url como:

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

Reemplaza <workspace-hostname> por el nombre de host de tu espacio de trabajo. Pide al agente que ejecute SELECT 1 AS result y confirma que llama a la herramienta y responde 1.

Para agentes de codificación, usa la guía de configuración de tu agente. Para la selección de warehouse y opciones específicas de SQL, consulta la referencia SQL MCP de Databricks.

Ejecuta una consulta predefinida con una función de Unity Catalog

Cree una herramienta de recuperación estructurada mediante funciones SQL del catálogo de Unity cuando la consulta se conozca con antelación y el agente proporcione los parámetros.

El siguiente ejemplo crea una función del Catálogo de Unity llamada lookup_customer_info. Asume que tienes una customer_data tabla con customer_name, customer_id, y customer_email columnas.

Revisa los requisitos y permisos de la función. Sustituye my_catalog.my_schema por un catálogo y un esquema donde puedas crear funciones, y adapta los nombres de las tablas y columnas a tus datos. Ejecuta el siguiente código en un 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;

Prueba la función con el nombre de un cliente de tu tabla:

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

Luego usa Unity Catalog AI para añadir la función a tu agente. Esa guía incluye ejemplos de LangGraph, OpenAI, Anthropic y LlamaIndex.

Usa a Genie en un sistema multiagente

Para coordinar los Agentes Genie con otros agentes y herramientas, consulte Supervisor Agent. Para integraciones existentes de Model Serving, véase Usar Genie en sistemas multiagente.

Consulta un agente Genie usando MCP

Para conectarte a un Agente Genie específico a través de MCP, consulta la referencia Genie Agent MCP para su URL y requisitos. Para consultar un agente Genie de Python sin MCP, utiliza ejemplos de la herramienta AI Bridge.