Conexión de agentes a datos no estructurados

A menudo, los agentes de inteligencia artificial necesitan consultar datos no estructurados, como colecciones de documentos, bases de conocimiento o corpora de texto para responder a preguntas y proporcionar respuestas con reconocimiento del contexto.

Databricks proporciona varios enfoques para conectar agentes a datos no estructurados en índices de búsqueda de vectores y almacenes de vectores externos. Utilice servidores MCP preconfigurados para obtener acceso inmediato a los índices de búsqueda vectorial de Databricks, desarrollar herramientas de recuperador localmente con paquetes de AI Bridge o crear funciones de recuperador personalizadas para flujos de trabajo especializados.

Consulta de un índice de búsqueda vectorial de Databricks mediante MCP

Si el agente necesita consultar un índice de Búsqueda vectorial de Databricks, use el servidor MCP administrado por Databricks. Antes de empezar, cree un índice de búsqueda vectorial mediante incrustaciones administradas por Databricks. Consulte Creación de puntos de conexión e índices de búsqueda vectorial.

La dirección URL de MCP administrada para la búsqueda de vectores es: https://<workspace-hostname>/api/2.0/mcp/vector-search/{catalog}/{schema}/{index_name}.

En los ejemplos siguientes se muestra cómo conectar el agente a un índice de búsqueda vectorial. Reemplace <catalog>, <schema>y <index-name> por los nombres del índice de búsqueda vectorial.

SDK de agentes de OpenAI (aplicaciones)

from agents import Agent, Runner
from databricks.sdk import WorkspaceClient
from databricks_openai.agents import McpServer

workspace_client = WorkspaceClient()

async with McpServer.from_vector_search(
    catalog="<catalog>",
    schema="<schema>",
    index_name="<index-name>",
    workspace_client=workspace_client,
    name="vector-search",
) as vs_server:
    agent = Agent(
        name="Research assistant",
        instructions="You are a research assistant. Use the vector search tool to find relevant documents and answer questions.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[vs_server],
    )
    result = await Runner.run(agent, "What is the return policy?")
    print(result.final_output)

Conceda a la aplicación acceso al índice de búsqueda vectorial en databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<index-name>'
            securable_type: 'TABLE'
            permission: 'SELECT'

LangGraph (Aplicaciones)

from databricks.sdk import WorkspaceClient
from databricks_langchain import ChatDatabricks, DatabricksMCPServer, DatabricksMultiServerMCPClient
from langgraph.prebuilt import create_react_agent

workspace_client = WorkspaceClient()
host = workspace_client.config.host

mcp_client = DatabricksMultiServerMCPClient([
    DatabricksMCPServer(
        name="vector-search",
        url=f"{host}/api/2.0/mcp/vector-search/<catalog>/<schema>/<index-name>",
        workspace_client=workspace_client,
    ),
])

async with mcp_client:
    tools = await mcp_client.get_tools()
    agent = create_react_agent(
        ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
        tools=tools,
    )
    result = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "What is the return policy?"}]}
    )
    print(result["messages"][-1].content)

Conceda a la aplicación acceso al índice de búsqueda vectorial en databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: '<catalog>.<schema>.<index-name>'
            securable_type: 'TABLE'
            permission: 'SELECT'

Servicio de modelos

from databricks.sdk import WorkspaceClient
from databricks_mcp import DatabricksMCPClient
import mlflow

workspace_client = WorkspaceClient()
host = workspace_client.config.host

# Connect to the Vector Search MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/vector-search/<catalog>/<schema>/<index-name>",
    workspace_client=workspace_client,
)

# List available tools from the Vector Search index
tools = mcp_client.list_tools()

# Log the agent with the required resources for deployment
mlflow.pyfunc.log_model(
    "agent",
    python_model=my_agent,
    resources=mcp_client.get_databricks_resources(),
)

Para implementar el agente, consulte Deploy an agent for generative AI applications (Model Serving). Para más información sobre el registro de agentes con recursos de MCP, consulte Uso de servidores MCP administrados de Databricks.

Otros enfoques

%pip install --upgrade databricks-langchain

from databricks_langchain import VectorSearchRetrieverTool, ChatDatabricks

# Initialize the retriever tool.
vs_tool = VectorSearchRetrieverTool(
  index_name="catalog.schema.my_databricks_docs_index",
  tool_name="databricks_docs_retriever",
  tool_description="Retrieves information about Databricks products from official Databricks documentation."
)

# Run a query against the vector search index locally for testing
vs_tool.invoke("Databricks Agent Framework?")

# Bind the retriever tool to your Langchain LLM of choice
llm = ChatDatabricks(endpoint="databricks-claude-sonnet-4-5")
llm_with_tools = llm.bind_tools([vs_tool])

# Chat with your LLM to test the tool calling functionality
llm_with_tools.invoke("Based on the Databricks documentation, what is Databricks Agent Framework?")

from databricks_langchain import VectorSearchRetrieverTool
from databricks_langchain import DatabricksEmbeddings

embedding_model = DatabricksEmbeddings(
    endpoint="databricks-bge-large-en",
)

vs_tool = VectorSearchRetrieverTool(
  index_name="catalog.schema.index_name", # Index name in the format 'catalog.schema.index'
  num_results=5, # Max number of documents to return
  columns=["primary_key", "text_column"], # List of columns to include in the search
  filters={"text_column LIKE": "Databricks"}, # Filters to apply to the query
  query_type="ANN", # Query type ("ANN" or "HYBRID").
  tool_name="name of the tool", # Used by the LLM to understand the purpose of the tool
  tool_description="Purpose of the tool", # Used by the LLM to understand the purpose of the tool
  text_column="text_column", # Specify text column for embeddings. Required for direct-access index or delta-sync index with self-managed embeddings.
  embedding=embedding_model # The embedding model. Required for direct-access index or delta-sync index with self-managed embeddings.
)

%pip install --upgrade databricks-openai

from databricks_openai import VectorSearchRetrieverTool
from openai import OpenAI
import json

# Initialize OpenAI client
client = OpenAI(api_key=<your_API_key>)

# Initialize the retriever tool
dbvs_tool = VectorSearchRetrieverTool(
  index_name="catalog.schema.my_databricks_docs_index",
  tool_name="databricks_docs_retriever",
  tool_description="Retrieves information about Databricks products from official Databricks documentation"
)

messages = [
  {"role": "system", "content": "You are a helpful assistant."},
  {
    "role": "user",
    "content": "Using the Databricks documentation, answer what is Spark?"
  }
]
first_response = client.chat.completions.create(
  model="gpt-4o",
  messages=messages,
  tools=[dbvs_tool.tool]
)

# Execute function code and parse the model's response and handle function calls.
tool_call = first_response.choices[0].message.tool_calls[0]
args = json.loads(tool_call.function.arguments)
result = dbvs_tool.execute(query=args["query"])  # For self-managed embeddings, optionally pass in openai_client=client

# Supply model with results – so it can incorporate them into its final response.
messages.append(first_response.choices[0].message)
messages.append({
  "role": "tool",
  "tool_call_id": tool_call.id,
  "content": json.dumps(result)
})
second_response = client.chat.completions.create(
  model="gpt-4o",
  messages=messages,
  tools=[dbvs_tool.tool]
)

from databricks_openai import VectorSearchRetrieverTool

vs_tool = VectorSearchRetrieverTool(
    index_name="catalog.schema.index_name", # Index name in the format 'catalog.schema.index'
    num_results=5, # Max number of documents to return
    columns=["primary_key", "text_column"], # List of columns to include in the search
    filters={"text_column LIKE": "Databricks"}, # Filters to apply to the query
    query_type="ANN", # Query type ("ANN" or "HYBRID").
    tool_name="name of the tool", # Used by the LLM to understand the purpose of the tool
    tool_description="Purpose of the tool", # Used by the LLM to understand the purpose of the tool
    text_column="text_column", # Specify text column for embeddings. Required for direct-access index or delta-sync index with self-managed embeddings.
    embedding_model_name="databricks-bge-large-en" # The embedding model. Required for direct-access index or delta-sync index with self-managed embeddings.
)

CREATE OR REPLACE FUNCTION main.default.databricks_docs_vector_search (
  -- The agent uses this comment to determine how to generate the query string parameter.
  query STRING
  COMMENT 'The query string for searching Databricks documentation.'
) RETURNS TABLE
-- The agent uses this comment to determine when to call this tool. It describes the types of documents and information contained within the index.
COMMENT 'Executes a search on Databricks documentation to retrieve text documents most relevant to the input query.' RETURN
SELECT
  chunked_text as page_content,
  map('doc_uri', url, 'chunk_id', chunk_id) as metadata
FROM
  vector_search(
    -- Specify your Vector Search index name here
    index => 'catalog.schema.databricks_docs_index',
    query => query,
    num_results => 5
  )

from unitycatalog.ai.langchain.toolkit import UCFunctionToolkit

toolkit = UCFunctionToolkit(
    function_names=[
        "main.default.databricks_docs_vector_search"
    ]
)
tools = toolkit.tools

Agregar seguimiento a una herramienta de recuperación

Añada seguimiento MLflow para monitorizar y depurar su recuperador. El seguimiento le permite ver entradas, salidas y metadatos para cada paso de ejecución.

El ejemplo anterior añade el decorador @mlflow.trace a los métodos __call__ y análisis. El decorador crea un intervalo de que se inicia cuando se invoca la función y finaliza cuando la función retorna. MLflow registra automáticamente la entrada y salida de la función y las excepciones generadas.

import mlflow
from mlflow.entities import Document

# This code snippet has been truncated for brevity. See the full retriever example above.
class VectorSearchRetriever:
  ...

  # Create a RETRIEVER span. The span name must match the retriever schema name.
  @mlflow.trace(span_type="RETRIEVER", name="vector_search")
  def __call__(...) -> List[Document]:
    ...

  # Create a PARSER span.
  @mlflow.trace(span_type="PARSER")
  def parse_results(...) -> List[Document]:
    ...

Para comprobar que las aplicaciones posteriores, como la Evaluación del Agente y el AI Playground, representen el seguimiento del recuperador correctamente, asegúrese de que el decorador cumple los siguientes requisitos:

• Use el esquema de intervalo del recuperador de MLflow y compruebe que la función devuelve un objeto List[Document].
• El nombre de seguimiento y el retriever_schema nombre deben coincidir para configurar el seguimiento correctamente. Consulte la siguiente sección para conocer cómo configurar el esquema del sistema de recuperación.

Establecimiento del esquema del recuperador para comprobar la compatibilidad de MLflow

Si el seguimiento devuelto desde el recuperador o span_type="RETRIEVER" no se ajusta al esquema del recuperador estándar de MLflow, debe asignar manualmente el esquema devuelto a MLflow campos esperados. Esto comprueba que MLflow puede realizar un seguimiento correcto del recuperador y representar seguimientos en aplicaciones de bajada.

Para establecer el esquema del recolector manualmente:

1. Llame a mlflow.models.set_retriever_schema cuando defina su agente. Use set_retriever_schema para asignar los nombres de columna de la tabla devuelta a los campos esperados de MLflow, como primary_key, text_columny doc_uri.

   # Define the retriever's schema by providing your column names
   mlflow.models.set_retriever_schema(
     name="vector_search",
     primary_key="chunk_id",
     text_column="text_column",
     doc_uri="doc_uri"
     # other_columns=["column1", "column2"],
   )
   

2. Especifique columnas adicionales en el esquema del recuperador proporcionando una lista de nombres de columna con el other_columns campo .

3. Si tiene varios recuperadores, puede definir varios esquemas mediante nombres únicos para cada esquema del recuperador.

El esquema del recuperador establecido durante la creación del agente afecta a las aplicaciones y flujos de trabajo posteriores, como la aplicación de revisión y los conjuntos de evaluación. En concreto, la columna doc_uri actúa como identificador principal para los documentos devueltos por el recuperador.

• La aplicación de revisión ,, muestra el doc_uri para ayudar a los revisores a evaluar las respuestas y rastrear los orígenes de los documentos. Consulte Revisión de la interfaz de usuario de la aplicación.
• Los Conjuntos de evaluación utilizan doc_uri para comparar los resultados del recuperador con conjuntos de datos de evaluación predefinidos para determinar la exhaustividad y precisión del recuperador. Consulte Conjuntos de evaluación (MLflow 2).

Leer archivos de un volumen de catálogo de Unity

Si el agente necesita leer archivos no estructurados (documentos de texto, informes, archivos de configuración, etc.) almacenados en un volumen de catálogo de Unity, puede crear herramientas que usen la API de archivos del SDK de Databricks para enumerar y leer archivos directamente.

En los ejemplos siguientes se crean dos herramientas que puede usar el agente:

• list_volume_files: enumera los archivos y directorios del volumen.
• read_volume_file: lee el contenido de un archivo de texto del volumen.

LangChain/LangGraph

Instale la versión más reciente de databricks-langchain que incluye Databricks AI Bridge.

%pip install --upgrade databricks-langchain

from databricks.sdk import WorkspaceClient
from langchain_core.tools import tool

VOLUME = "<catalog>.<schema>.<volume>"  # TODO: Replace with your volume
w = WorkspaceClient()


@tool
def list_volume_files(directory: str = "") -> str:
    """Lists files and directories in the Unity Catalog volume.
    Provide a relative directory path, or leave empty to list the volume root."""
    base = f"/Volumes/{VOLUME.replace('.', '/')}"
    path = f"{base}/{directory.lstrip('/')}" if directory else base
    entries = []
    for f in w.files.list_directory_contents(path):
        kind = "dir" if f.is_directory else "file"
        size = f" ({f.file_size} bytes)" if not f.is_directory else ""
        entries.append(f"  [{kind}] {f.name}{size}")
    return "\n".join(entries) if entries else "No files found."


@tool
def read_volume_file(file_path: str) -> str:
    """Reads a text file from the Unity Catalog volume.
    Provide the path relative to the volume root, for example 'reports/q1_summary.txt'."""
    base = f"/Volumes/{VOLUME.replace('.', '/')}"
    full_path = f"{base}/{file_path.lstrip('/')}"
    resp = w.files.download(full_path)
    return resp.contents.read().decode("utf-8")

Enlace las herramientas a un LLM y ejecute un bucle de llamada a herramientas:

from databricks_langchain import ChatDatabricks
from langchain_core.messages import HumanMessage, ToolMessage

llm = ChatDatabricks(endpoint="databricks-claude-sonnet-4-5")
llm_with_tools = llm.bind_tools([list_volume_files, read_volume_file])

messages = [HumanMessage(content="What files are in the volume? Can you read about_databricks.txt and summarize it in 2 sentences?")]
tool_map = {"list_volume_files": list_volume_files, "read_volume_file": read_volume_file}

for _ in range(5):  # max iterations
    response = llm_with_tools.invoke(messages)
    messages.append(response)
    if not response.tool_calls:
        break
    for tc in response.tool_calls:
        result = tool_map[tc["name"]].invoke(tc["args"])
        messages.append(ToolMessage(content=result, tool_call_id=tc["id"]))

print(response.content)

OpenAI

Instale la versión más reciente de databricks-openai que incluye Databricks AI Bridge.

%pip install --upgrade databricks-openai

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI
import json

VOLUME = "<catalog>.<schema>.<volume>"  # TODO: Replace with your volume
w = WorkspaceClient()
client = DatabricksOpenAI()

# Define the tool specifications
tools = [
    {
        "type": "function",
        "function": {
            "name": "list_volume_files",
            "description": "Lists files and directories in the Unity Catalog volume. Provide a relative directory path, or leave empty to list the volume root.",
            "parameters": {
                "type": "object",
                "properties": {
                    "directory": {
                        "type": "string",
                        "description": "Relative directory path within the volume. Leave empty for root.",
                    }
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "read_volume_file",
            "description": "Reads a text file from the Unity Catalog volume. Provide the path relative to the volume root, for example 'reports/q4_summary.txt'.",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {
                        "type": "string",
                        "description": "Path to the file relative to the volume root.",
                    }
                },
                "required": ["file_path"],
            },
        },
    },
]


def execute_tool(name: str, args: dict) -> str:
    base = f"/Volumes/{VOLUME.replace('.', '/')}"
    if name == "list_volume_files":
        directory = args.get("directory", "")
        path = f"{base}/{directory.lstrip('/')}" if directory else base
        entries = []
        for f in w.files.list_directory_contents(path):
            kind = "dir" if f.is_directory else "file"
            size = f" ({f.file_size} bytes)" if not f.is_directory else ""
            entries.append(f"[{kind}] {f.name}{size}")
        return "\n".join(entries) if entries else "No files found."
    elif name == "read_volume_file":
        full_path = f"{base}/{args['file_path'].lstrip('/')}"
        resp = w.files.download(full_path)
        return resp.contents.read().decode("utf-8")
    return f"Unknown tool: {name}"


# Call the model with tools
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "List the files in the volume, then read about_databricks.txt and summarize it."},
]

response = client.chat.completions.create(
    model="databricks-claude-sonnet-4-5", messages=messages, tools=tools
)

# Execute tool calls and send results back
while response.choices[0].finish_reason == "tool_calls":
    messages.append(response.choices[0].message)
    for tool_call in response.choices[0].message.tool_calls:
        args = json.loads(tool_call.function.arguments)
        result = execute_tool(tool_call.function.name, args)
        messages.append(
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        )
    response = client.chat.completions.create(
        model="databricks-claude-sonnet-4-5", messages=messages, tools=tools
    )

print(response.choices[0].message.content)