Autor AI agentes em código

Este artigo 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

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

Para criar e implantar agentes usando a abordagem deste artigo, o senhor deve ter as seguintes versões mínimas de pacote:

• databricks-agents versão 0.16.0 e acima
• mlflow versão 2.20.2 e acima
• Python 3,10 ou acima. O senhor pode usar serverless compute ou Databricks Runtime 13.3 LTS e acima para atender a esse requisito.

%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.

LangChain/LangGraph

%pip install -U -qqqq databricks-langchain

OpenAI

%pip install -U -qqqq databricks-openai

Pure Python agents

%pip install -U -qqqq databricks-ai-bridge

Use ChatAgent para criar agentes

A Databricks recomenda usar a interface ChatAgent do MLflow para criar agentes de nível de produção. Essa especificação de esquema de bate-papo foi projetada para cenários de agentes e é semelhante, mas não estritamente compatível com, o esquema OpenAI ChatCompletion. ChatAgent também adiciona funcionalidade para agentes de vários turnos que usam ferramentas.

Criar seu agente usando ChatAgent oferece os seguintes benefícios:

• Capacidades avançadas de agente

  • 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
  • Suporte a sistemas multiagentes

• Desenvolvimento, implantação e monitoramento simplificados

  • Integração de recurso Databricks independente de estrutura : Escreva seu agente em qualquer estrutura de sua escolha e obtenha compatibilidade imediata com AI Playground, Agent Evaluation e Agent monitoring.
  • 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.

Exemplos deChatAgent

O Notebook a seguir mostra ao senhor como criar transmissão e não-transmissão ChatAgents usando a popular biblioteca OpenAI e LangGraph.

Agente de chamada de ferramentas LangGraph

Open notebook in new tab

Agente de chamada de ferramentas OpenAI

Open notebook in new tab

Ferramenta da API de respostas da OpenAI - agente de chamadas

Open notebook in new tab

Agente somente de bate-papo OpenAI

Open notebook in new tab

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

Exemplo do sistema multiagente ChatAgent

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

Autor agentes de transmissão de resultados

Os agentes de transmissão fornecem respostas em uma transmissão contínua de partes menores e incrementais. A saída de transmissão permite que os usuários finais leiam a saída do agente à medida que ela é gerada, reduzindo a latência percebida e melhorando a experiência geral 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 um contendo uma parte da resposta. Leia mais sobre o comportamento ideal de transmissão ChatAgent nos documentos do siteMLflow.

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.

Veja os exemplos a seguir para saber como definir entradas e saídas personalizadas para agentes OpenAI/PyFunc e LangGraph.

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 .

2. Habilite custom_inputs .

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

   

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. Para obter exemplos de ferramentas de recuperação, consulte Recuperação não estruturada AI ferramentas de agente.

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
mlflow.models.set_retriever_schema(
    # Specify the name of your retriever span
    name="vector_search",
    # Specify the output column name to treat as the primary key (ID) of each retrieved document
    primary_key="chunk_id",
    # Specify the output column name to treat as the text content (page content) of each retrieved document
    text_column="text_column",
    # Specify the output column name to treat as the document URI of each retrieved document
    doc_uri="doc_uri",
)

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.

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-dbrx-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-dbrx-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

• Crie suas próprias ferramentas de agente.
• registrar um agente AI.
• Adicionar rastros a um agente AI.
• implantado um agente AI.