Criar ferramentas do agente AI

Prévia

Esse recurso está em Pré-lançamento público.

Este artigo mostra ao senhor como criar ferramentas para agentes do AI usando o Mosaic AI Agent Framework. Para saber mais, consulte O que são sistemas compostos AI e agentes AI?

AI Os agentes usam ferramentas para realizar ações além da geração de linguagem, como recuperar dados estruturados ou não estruturados, executar código ou conversar com serviços remotos (por exemplo, enviar uma mensagem para email ou Slack).

Para fornecer ferramentas a um agente com o Mosaic AI Agent Framework, o senhor pode usar qualquer combinação dos seguintes métodos:

  • Crie ferramentas com as funções do Unity Catalog: As funções do Unity Catalog proporcionam fácil descoberta, governança e compartilhamento. Unity Catalog funcionam especialmente bem para aplicar transformações e agregações em grandes conjuntos de dados.

  • Criar ferramentas com código de agente: Essa abordagem é útil ao fazer chamadas para REST APIs, ao usar código ou biblioteca arbitrários ou ao executar ferramentas com latência muito baixa. No entanto, essa abordagem não tem a capacidade de descoberta e a governança integradas fornecidas pelas funções do site Unity Catalog. Avalie essa desvantagem ao criar seu agente para determinar qual abordagem é a melhor.

Ambas as abordagens funcionam para agentes escritos em código Python personalizado ou usando uma biblioteca de autoria de agentes como a LangGraph.

Requisitos

  • A Databricks recomenda instalar a versão mais recente do cliente MLflow Python ao desenvolver agentes.

Melhore a chamada de ferramentas com a documentação

AI Os agentes usam sua documentação para entender quando e como usar as ferramentas que o senhor fornece. Forneça documentação clara e detalhada sobre os parâmetros e valores de retorno de cada ferramenta.

Para as funções do Unity Catalog, use COMMENT para descrever a ferramenta.

Criar ferramentas com as funções do Unity Catalog

Os exemplos a seguir mostram ao senhor como criar ferramentas de agente com as funções do Unity Catalog.

Ferramenta do executor Python

Este exemplo cria uma ferramenta para executar o código Python.

Um LLM pode usar essa ferramenta para executar o código Python fornecido por um usuário ou escrito pelo LLM.

Execute o código a seguir em uma célula do Notebook. Ele usa a magia do %sql Notebook para criar uma função Unity Catalog chamada python_exec.

%sql
CREATE OR REPLACE FUNCTION
main.default.python_exec (
code STRING COMMENT 'Python code to execute. Remember to print the final result to stdout.'
)
RETURNS STRING
LANGUAGE PYTHON
DETERMINISTIC
COMMENT 'Executes Python code in the sandboxed environment and returns its stdout. The runtime is stateless, and you can not read the output of the previous tool executions. No such variables, "rows", or "observations" were defined. Calling another tool inside a Python code is NOT allowed. Use standard Python libraries only.'
AS $$
import sys
from io import StringIO
sys_stdout = sys.stdout
redirected_output = StringIO()
sys.stdout = redirected_output
exec(code)
sys.stdout = sys_stdout
return redirected_output.getvalue()
$$

Ferramenta de consulta de tabela

Este exemplo cria uma ferramenta para consultar dados do cliente em uma tabela Unity Catalog.

Ele cria uma função do Unity Catalog chamada lookup_customer_info que um LLM pode usar para recuperar dados estruturados de uma tabela customer_data hipotética.

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

CREATE OR REPLACE FUNCTION main.default.lookup_customer_info(
  customer_name STRING COMMENT 'Name of the customer whose info to look up'
)
RETURNS STRING
COMMENT 'Returns metadata about a particular customer given the customer name, including the customer 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
  LIMIT 1;

Recuperador de pesquisa vetorial

Este exemplo cria uma ferramenta de recuperação para consultar dados de um índice do Mosaic AI Vector Search.

A função Unity Catalog databricks_docs_vector_search consulta um índice de pesquisa vetorial hipotético que contém a documentação da Databricks. Ela envolve a função vector_search() padrão e usa os aliases page_content e metadata para fazer a correspondência da saída com o esquema de recuperação do MLflow.

Observação

Para estar em conformidade com o esquema MLflow retriever, todas as colunas de metadados adicionais devem ser adicionadas à coluna metadata usando a função de mapaSQL , em vez de serem a chave de saída de nível superior.

Execute o código a seguir em um editor do Notebook ou do site SQL.

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
  )

Essa ferramenta de recuperação tem as seguintes ressalvas:

  • O MLflow rastreia essa função do Unity Catalog como um tipo de intervalo TOOL em vez de um tipo de intervalo RETRIEVER. Como resultado, os aplicativos downstream do Agent Framework, como o aplicativo de revisão de agentes e o AI Playground, não mostrarão detalhes específicos do retriever, como links para chunks. Para obter mais informações sobre os tipos de span, consulte MLflow Tracing Schema.

  • Os clientes SQL podem limitar o número máximo de linhas ou bytes retornados. Para evitar o truncamento de dados, o senhor deve truncar os valores de coluna retornados pelo UDF. Por exemplo, você pode usar substring(chunked_text, 0, 8192) para reduzir o tamanho de grandes colunas de conteúdo e evitar o truncamento de linhas durante a execução.

  • Como essa ferramenta é um invólucro para a função vector_search(), ela está sujeita às mesmas limitações da função vector_search(). Consulte Limitações.

Se esse exemplo não for adequado para seu caso de uso, crie um buscador vetorial usando um código de agente personalizado. Consulte Criar um buscador vetorial.

Atribuir ferramentas do Unity Catalog aos agentes

Depois que o senhor criar as ferramentas do Unity Catalog, atribua-as ao seu agente para uso.

Os agentes do LangChain podem usar o UCFunctionToolkit para atribuir ferramentas do Unity Catalog.

A seguir, descrevemos como exportar um agente de chamada de ferramenta LangChain para o código do AI Playground.

Ferramenta de exportação - chamando agentes do AI Playground

Use o AI Playground para atribuir ferramentas do Unity Catalog a um LLM, testar o agente e, em seguida, exportar o código que define o agente de chamada de ferramenta.

Para usar o site AI Playground para exportar agentes, o site workspace deve atender aos seguintes requisitos:

  1. No Playground, selecione um modelo com o rótulo Tools enabled (Ferramentas ativadas ).

    Selecione uma ferramenta - chamando o LLM

  2. Selecione Ferramentas e clique em Adicionar uma ferramenta.

  3. No menu dropdown, selecione uma função Unity Catalog:

    Selecione uma ferramenta

  4. Use o Playground para conversar e testar a combinação atual de LLM, ferramentas e prompt do sistema. Experimente variações para ter uma ideia de como a configuração atual funciona.

    Criar um protótipo do LLM

Depois de adicionar as ferramentas, exporte o agente para o site Python Notebook:

  1. Clique em Exportar para gerar o Python Notebook que define e implanta o agente.

    Depois de exportar o código do agente, o senhor verá três arquivos salvos no site workspace:

    • agent Notebook: Contém o código Python que define seu agente usando LangChain.

    • driver Notebook: Contém o código Python para log, rastrear, registrar e implantar o agente AI usando o Mosaic AI Agent Framework.

    • config.yml: Contém informações de configuração sobre seu agente, incluindo definições de ferramentas.

  2. Abra o agent Notebook para ver o código LangChain que define seu agente. Use esse Notebook para testar e iterar o agente programaticamente, como, por exemplo, definir mais ferramentas.

  3. Quando estiver satisfeito com os resultados do agente, o senhor pode executar o driver Notebook para log e implantar seu agente em um modelo de serviço endpoint.

Crie ferramentas com o código do agente

O senhor também pode criar ferramentas no código do agente em vez de nas funções do Unity Catalog.

Essa abordagem é útil ao chamar REST APIs, ao usar código ou biblioteca arbitrários ou ao executar ferramentas de baixa latência. No entanto, a definição de ferramentas no código do agente não tem a capacidade de descoberta e a governança fornecidas pelas funções do Unity Catalog.

Para ver um exemplo de uma ferramenta de recuperação de pesquisa vetorial definida no código do agente, consulte Criar um recuperador de pesquisa vetorial.

Próximos passos