Pular para o conteúdo principal

Autor AI agentes em código

Esta página mostra como criar um agente AI em Python usando o Mosaic AI Agent Framework e uma biblioteca popular de autoria de agentes, como LangGraph, PyFunc e OpenAI.

Requisitos​

dica

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

Para criar e implantar agentes usando a abordagem desta página, instale o seguinte:

  • databricks-agents 0.16.0 ou acima
  • mlflow 2.20.2 ou acima
  • Python 3,10 ou acima.
    • Para atender a esse requisito, o senhor pode usar serverless compute ou Databricks Runtime 13.3 LTS ou acima.
%pip install -U -qqqq databricks-agents>=0.16.0 mlflow>=2.20.2

Databricks também recomenda a instalação do pacote de integração Databricks AI Bridge ao criar agentes. Esses pacotes de integração (como databricks-langchain, databricks-openai) fornecem uma camada compartilhada de APIs para interagir com Databricks AI recurso, como Databricks AI/BI Genie e Vector Search, em estruturas de criação de agentes e SDKs.

%pip install -U -qqqq databricks-langchain

Use ChatAgent para criar agentes​

A Databricks recomenda a interface MLflow ChatAgent para criar agentes de nível de produção. Essa especificação do esquema de bate-papo é semelhante, mas não estritamente compatível com, o esquema OpenAI ChatCompletion.

O ChatAgent envolve facilmente os agentes existentes para compatibilidade com o Databricks.

ChatAgent oferece os seguintes benefícios:

  • Capacidades avançadas de agente

    • Suporte multiagente
    • transmissão de saída : Possibilite experiências interativas para o usuário por meio da transmissão da saída em partes menores.
    • Histórico abrangente de mensagens de tool-calling : Retorna várias mensagens, inclusive mensagens intermediárias de chamadas de ferramentas, para melhorar a qualidade e o gerenciamento de conversas.
    • Suporte para confirmação de chamadas de ferramentas

  • Desenvolvimento, implantação e monitoramento simplificados

    • Crie seu agente usando qualquer estrutura : Envolva qualquer agente existente usando a interface ChatAgent para obter compatibilidade imediata com AI Playground, Avaliação de agentes e Monitoramento de agentes.
    • Interfaces de criação digitadas : Escreva o código do agente usando classes Python digitadas, beneficiando-se do preenchimento automático do IDE e do Notebook.
    • Inferência automática de assinaturas : O MLflow infere automaticamente assinaturas ChatAgent ao registrar o agente, simplificando o registro e a implantação. Consulte Inferir assinatura do modelo durante o registro.
    • AI Tabelas de inferência aprimoradas pelo gateway : AI As tabelas de inferência do gateway são ativadas automaticamente para agentes implantados, fornecendo acesso a solicitações detalhadas log metadados.

Para saber como criar um ChatAgent, consulte os exemplos na seção a seguir e a documentação do MLflow - O que é a interface do ChatAgent.

E se eu já tiver um agente?​

Se o senhor já tiver um agente criado com LangChain, LangGraph ou uma estrutura semelhante, não precisará reescrever o agente para usá-lo no Databricks. Em vez disso, basta envolver seu agente existente com a interface ChatAgent do MLflow:

  1. Escreva uma classe envolvente em Python que herda de mlflow.pyfunc.ChatAgent.

    Dentro da classe wrapper, mantenha seu agente existente como um atributo self.agent = your_existing_agent.

  2. A classeChatAgent exige que o senhor implemente um método predict para lidar com solicitações que não sejam de transmissão.

    predict deve aceitar:

    • messages: list[ChatAgentMessage], que é uma lista de ChatAgentMessage, cada um com uma função (como " user " ou " assistant "), o prompt e um ID.

    • (Opcional) context: Optional[ChatContext] e custom_inputs: Optional[dict] para dados extras.

    Python
    import uuid

    # input example
    [
      ChatAgentMessage(
        id=str(uuid.uuid4()),  # Generate a unique ID for each message
        role="user",
        content="What's the weather in Paris?"
      )
    ]

    predict deve retornar um ChatAgentResponse.

    Python
    import uuid

    # output example
    ChatAgentResponse(
      messages=[
        ChatAgentMessage(
          id=str(uuid.uuid4()),  # Generate a unique ID for each message
          role="assistant",
          content="It's sunny in Paris."
        )
      ]
    )

  3. Converter entre formatos

    Em predict, converta as mensagens recebidas de list[ChatAgentMessage] no formato de entrada que seu agente espera.

    Depois que seu agente gerar uma resposta, converta sua saída em um ou mais objetos ChatAgentMessage e envolva-os em ChatAgentResponse.

dica

Converta automaticamente a saída LangChain

Se o senhor estiver usando um agente LangChain, poderá usar o mlflow.langchain.output_parsers.ChatAgentOutputParser para converter automaticamente as saídas do LangChain no esquema do MLflow ChatAgentMessage e ChatAgentResponse.

A seguir, um padrão simplificado para a conversão de seu agente:

Python
from mlflow.pyfunc import ChatAgent
from mlflow.types.agent import ChatAgentMessage, ChatAgentResponse, ChatAgentChunk
import uuid


class MyWrappedAgent(ChatAgent):
  def __init__(self, agent):
    self.agent = agent

  def predict(self, messages, context=None, custom_inputs=None):
    # Convert messages to your agent's format
    agent_input = ... # build from messages
    agent_output = self.agent.invoke(agent_input)
    # Convert output to ChatAgentMessage
    return ChatAgentResponse(
      messages=[ChatAgentMessage(role="assistant", content=agent_output, id=str(uuid.uuid4()),)]
    )

  def predict_stream(self, messages, context=None, custom_inputs=None):
    # If your agent supports streaming
    for chunk in self.agent.stream(...):
      yield ChatAgentChunk(delta=ChatAgentMessage(role="assistant", content=chunk, id=str(uuid.uuid4())))

Para obter exemplos completos, consulte o Notebook na seção a seguir.

Exemplos deChatAgent​

O seguinte Notebook mostra como criar transmissão e não-transmissão ChatAgents usando a popular biblioteca OpenAI, LangGraph e AutoGen.

Se o senhor estiver usando um agente LangChain, poderá usar o mlflow.langchain.output_parsers.ChatAgentOutputParser para converter automaticamente as saídas do LangChain no esquema do MLflow ChatAgentMessage e ChatAgentResponse.

Agente de chamada de ferramentas LangGraph

Open notebook in new tab

Para saber como expandir os recursos desses agentes adicionando ferramentas, consulte AI agent tools.

Exemplo de multiagente​

Para saber como criar um sistema multiagentes usando o Genie, consulte Usar o Genie em sistemas multiagentes.

agentes de transmissão de saída​

Os agentes de transmissão fornecem respostas em uma transmissão contínua de partes menores e incrementais. A transmissão reduz a latência percebida e melhora a experiência do usuário para agentes de conversação.

Para criar uma transmissão ChatAgent, defina um método predict_stream que retorne um gerador que produza objetos ChatAgentChunk - cada ChatAgentChunk contém uma parte da resposta. Leia mais sobre o comportamento ideal da transmissão ChatAgent nos documentosMLflow.

O código a seguir mostra um exemplo de função predict_stream. Para obter exemplos completos de agentes de transmissão, consulte Exemplos de ChatAgent:

Python
def predict_stream(
  self,
  messages: list[ChatAgentMessage],
  context: Optional[ChatContext] = None,
  custom_inputs: Optional[dict[str, Any]] = None,
) -> Generator[ChatAgentChunk, None, None]:
  # Convert messages to a format suitable for your agent
  request = {"messages": self._convert_messages_to_dict(messages)}

  # Stream the response from your agent
  for event in self.agent.stream(request, stream_mode="updates"):
    for node_data in event.values():
      # Yield each chunk of the response
      yield from (
        ChatAgentChunk(**{"delta": msg}) for msg in node_data["messages"]
      )

Author deployment-ready ChatAgents for Databricks servindo modelo​

Databricks implantado ChatAgents em um ambiente distribuído em Databricks servindo modelo, o que significa que, durante uma conversa com vários turnos, a mesma réplica de serviço pode não atender a todas as solicitações. Preste atenção às seguintes implicações para gerenciar o estado do agente:

  • Evite o armazenamento em cache local : ao implantar um ChatAgent, não presuma que a mesma réplica atenderá a todas as solicitações em uma conversa com vários turnos. Reconstrua o estado interno usando um esquema ChatAgentRequest do dicionário para cada turno.

  • Estado de thread-safe: projete o estado do agente para que seja seguro para thread-safe, evitando conflitos em ambientes com vários segmentos.

  • Inicializar estado na função predict : Inicialize o estado sempre que a função predict for chamada, não durante a inicialização ChatAgent. O armazenamento de estado no nível ChatAgent poderia vazar informações entre as conversas e causar conflitos, pois uma única réplica ChatAgent poderia lidar com solicitações de várias conversas.

Entradas e saídas personalizadas​

Alguns cenários podem exigir entradas adicionais do agente, como client_type e session_id, ou saídas como links de fontes de recuperação que não devem ser incluídos no histórico do chat para interações futuras.

Para esses cenários, o MLflow ChatAgent suporta nativamente os campos custom_inputs e custom_outputs.

atenção

Atualmente, o aplicativo Agent Evaluation Review não oferece suporte à renderização de rastreamentos para agentes com campos de entrada adicionais.

Consulte o Notebook a seguir para saber como definir entradas e saídas personalizadas.

Agente de esquema personalizado OpenAI + PyFunc Notebook

Open notebook in new tab

Agente de esquema personalizado LangGraph Notebook

Open notebook in new tab

Fornecer custom_inputs no AI Playground e no aplicativo de avaliação de agentes​

Se o seu agente aceitar entradas adicionais usando o campo custom_inputs, o senhor poderá fornecer manualmente essas entradas no AI Playground e no aplicativo de avaliação do agente.

  1. No AI Playground ou no aplicativo Agent Review, selecione o ícone de engrenagem Ícone de engrenagem..

  2. Habilite custom_inputs .

  3. Forneça um objeto JSON que corresponda ao esquema de entrada definido pelo seu agente.

    Forneça custom_inputs no playground AI.

Especifique esquemas de recuperação personalizados​

AI Os agentes geralmente usam recuperadores para localizar e consultar dados não estruturados de índices de pesquisa de vetores. Por exemplo, ferramentas de recuperação, consulte Criar e rastrear ferramentas de recuperação para dados não estruturados.

Rastreie esses recuperadores dentro de seu agente com MLflow RETRIEVER spans para permitir Databricks produto recurso, incluindo:

  • Exibição automática de links para documentos de origem recuperados na interface do usuário do AI Playground
  • Executando automaticamente juízes de fundamentação e relevância de recuperação na Avaliação de Agentes
nota

Databricks recomenda o uso de ferramentas retriever fornecidas por Databricks AI Bridge pacote como databricks_langchain.VectorSearchRetrieverTool e databricks_openai.VectorSearchRetrieverTool porque elas já estão em conformidade com o esquema retriever MLflow. Consulte Desenvolver localmente ferramentas de recuperação do Vector Search com o AI Bridge.

Se seu agente incluir extensões de retriever com um esquema personalizado, chame mlflow.models.set_retriever_schema quando você define seu agente em código. Isso mapeia as colunas de saída do seu retriever para os campos esperados do MLflow (primary_key, text_column, doc_uri).

Python
import mlflow
# Define the retriever's schema by providing your column names
# For example, the following call specifies the schema of a retriever that returns a list of objects like
# [
#     {
#         'document_id': '9a8292da3a9d4005a988bf0bfdd0024c',
#         'chunk_text': 'MLflow is an open-source platform, purpose-built to assist machine learning practitioners...',
#         'doc_uri': 'https://mlflow.org/docs/latest/index.html',
#         'title': 'MLflow: A Tool for Managing the Machine Learning Lifecycle'
#     },
#     {
#         'document_id': '7537fe93c97f4fdb9867412e9c1f9e5b',
#         'chunk_text': 'A great way to get started with MLflow is to use the autologging feature. Autologging automatically logs your model...',
#         'doc_uri': 'https://mlflow.org/docs/latest/getting-started/',
#         'title': 'Getting Started with MLflow'
#     },
# ...
# ]
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="mlflow_docs_vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="document_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="chunk_text",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
    # Specify any other columns returned by the retriever
    other_columns=["title"],
)
nota

A coluna doc_uri é especialmente importante ao avaliar o desempenho do retriever. doc_uri é o identificador principal dos documentos retornados pelo recuperador, permitindo compará-los com os conjuntos de avaliação da verdade básica. Consulte Conjuntos de avaliação (legados).

Parametrize o código do agente para implantação em todos os ambientes​

Você pode parametrizar o código do agente para reutilizar o mesmo código do agente em diferentes ambientes.

Os parâmetros são pares chave-valor que você define em um dicionário no Python ou em um arquivo .yaml.

Para configurar o código, crie um ModelConfig usando um dicionário Python ou um arquivo .yaml. ModelConfig é um conjunto de parâmetros key-value que permite o gerenciamento flexível da configuração. Por exemplo, o senhor pode usar um dicionário durante o desenvolvimento e, em seguida, convertê-lo em um arquivo .yaml para implantação de produção e CI/CD.

Para obter detalhes sobre ModelConfig, consulte a documentação do MLflow.

Um exemplo ModelConfig é mostrado abaixo:

YAML
llm_parameters:
  max_tokens: 500
  temperature: 0.01
model_serving_endpoint: databricks-meta-llama-3-3-70b-instruct
vector_search_index: ml.docs.databricks_docs_index
prompt_template: 'You are a hello world bot. Respond with a reply to the user''s
  question that indicates your prompt template came from a YAML file. Your response
  must use the word "YAML" somewhere. User''s question: {question}'
prompt_template_input_vars:
  - question

No código do agente, o senhor pode fazer referência a uma configuração default (desenvolvimento) do arquivo ou dicionário .yaml:

Python
import mlflow
# Example for loading from a .yml file
config_file = "configs/hello_world_config.yml"
model_config = mlflow.models.ModelConfig(development_config=config_file)

# Example of using a dictionary
config_dict = {
    "prompt_template": "You are a hello world bot. Respond with a reply to the user's question that is fun and interesting to the user. User's question: {question}",
    "prompt_template_input_vars": ["question"],
    "model_serving_endpoint": "databricks-meta-llama-3-3-70b-instruct",
    "llm_parameters": {"temperature": 0.01, "max_tokens": 500},
}

model_config = mlflow.models.ModelConfig(development_config=config_dict)

# Use model_config.get() to retrieve a parameter value
# You can also use model_config.to_dict() to convert the loaded config object
# into a dictionary
value = model_config.get('sample_param')

Em seguida, ao registrar o agente, especifique o parâmetro model_config como log_model para especificar um conjunto personalizado de parâmetros a serem usados ao carregar o agente de registros. Consulte Documentação do MLflow - ModelConfig.

transmissão propagação de erros​

Mosaic AI propagação de quaisquer erros encontrados durante a transmissão com os últimos tokens em databricks_output.error. Cabe ao cliente chamador tratar e revelar adequadamente esse erro.

Bash
{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}

Próximas etapas​

Última atualização em