Ligue agentes a dados estruturados

Os agentes frequentemente precisam de consultar ou manipular dados estruturados para responder a perguntas, atualizar registos ou criar pipelines de dados.

O Databricks fornece múltiplas abordagens para ligar agentes a dados estruturados em tabelas do Unity Catalog e armazenamentos externos de dados. Use servidores MCP pré-configurados para acesso imediato a Genie Agents e SQL warehouses, ou construa ferramentas personalizadas para fluxos de trabalho especializados.

Esta página mostra como:

Consultar dados nas tabelas do Unity Catalog

Se o seu agente precisar de consultar dados em tabelas do Unity Catalog, o Databricks recomenda usar Agentes Genie. Um Agente Genie é uma coleção de até 25 tabelas do Catálogo Unity que o Genie pode manter em contexto e consultar usando linguagem natural. Os agentes podem aceder ao Agente Genie usando um URL MCP pré-configurado.

Para se ligar a um Agente Génio:

  1. Crie um Agente Genie com as tabelas que quer consultar e partilhe o agente com os utilizadores, ou principais de serviço, que devem aceder a ele. Veja Criar e gerir um Agente Génio.
  2. Crie um agente e ligue-o ao URL MCP pré-configurado e gerido para o espaço: https://<workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}.

Observação

O servidor MCP gerido para o Genie invoca o Genie como ferramenta MCP, o que significa que o histórico não é passado ao invocar as APIs do Genie.

Adicione uma ferramenta Genie Agent ao seu agente

Os exemplos seguintes mostram como ligar o seu agente a um servidor Genie Agent MCP. Substitua <genie-space-id> pelo ID do seu Agente Génio.

SDK de Agentes OpenAI (Aplicações)

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

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

async with McpServer(
    url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
    name="genie-space",
    workspace_client=workspace_client,
) as genie_server:
    agent = Agent(
        name="Data analyst agent",
        instructions="You are a data analyst. Use the Genie tool to query structured data and answer questions.",
        model="databricks-claude-sonnet-4-5",
        mcp_servers=[genie_server],
    )
    result = await Runner.run(agent, "What were the top 10 customers by revenue last quarter?")
    print(result.final_output)

Conceda à aplicação acesso ao Agente Génio em databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

LangGraph (Aplicações)

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="genie-space",
        url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
        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 were the top 10 customers by revenue last quarter?"}]}
    )
    print(result["messages"][-1].content)

Conceda à aplicação acesso ao Agente Génio em databricks.yml:

resources:
  apps:
    my_agent_app:
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

Serviço 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 Genie Agent MCP server
mcp_client = DatabricksMCPClient(
    server_url=f"{host}/api/2.0/mcp/genie/<genie-space-id>",
    workspace_client=workspace_client,
)

# List available tools from the Genie Agent
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 o agente, consulte Implementar um agente para aplicações de IA (Model Serving). Para detalhes sobre agentes de login com recursos MCP, consulte servidores MCP geridos pelo Azure Databricks.

Sistema multiagente Genie

Importante

Este recurso está no Public Preview.

Para sistemas avançados e multi-agente, também podes usar o Genie como agente em vez de o integrar através do MCP. Quando chamas o Génio como agente, podes passar de forma determinística o contexto da conversa existente para o Génio.

Para uma abordagem centrada no código, veja Use Genie em sistemas multi-agente (Model Serving). Para uma abordagem centrada na interface, consulte Usar Agente Supervisor para criar um sistema multiagente coordenado.

Execute SQL contra tabelas do Unity Catalog com o servidor SQL MCP do Databricks

Quando o seu agente precisar de executar SQL gerado por IA contra tabelas do Unity Catalog através de um SQL warehouse, ligue-o ao servidor SQL MCP gerido pelo Azure Databricks em vez de construir uma ferramenta personalizada. O servidor expõe a execução SQL como uma ferramenta, e o acesso é governado pelas permissões do Unity Catalog. Ligue o seu agente ao URL MCP gerido pré-configurado: https://<workspace-hostname>/api/2.0/mcp/sql.

Para o padrão URL, o âmbito OAuth, _meta parâmetros (como fixar um específico warehouse_id) e exemplos de ligação, veja Databricks SQL.

Consultar dados usando a ferramenta de função SQL 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, que permite a um agente recuperar dados estruturados de uma tabela hipotética customer_data .

Execute o código a seguir em um editor SQL.

CREATE OR REPLACE FUNCTION main.default.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 main.default.customer_data
  WHERE customer_name = customer_name_input
  LIMIT 1;

Depois de criar uma ferramenta de catálogo Unity, adicione-a ao seu agente. Consulte a ferramenta de criação de funções do Catálogo Unity.

  • Last updated on