Depurar um agente implantado AI

Esta página explica como depurar problemas comuns ao implantar agentes AI usando a estrutura de agentes Mosaic AI. agents.deploy() API.

Agent Framework implantado no endpoint servindo modelo, portanto, o senhor deve revisar o guia de depuração do servindo modelo, além das etapas de depuração do agente nesta página.

Agentes de criação usando as melhores práticas

Use as seguintes práticas recomendadas ao criar agentes:

• Melhore a depuração usando as interfaces de criação de agentes recomendadas e o rastreamento MLflow: Siga as práticas recomendadas em Author AI agents in code, como habilitar oMLflow rastreamento automático para facilitar a depuração dos agentes.
• Documente as ferramentas com clareza : descrições claras de ferramentas e parâmetros garantem que seu agente entenda suas ferramentas e as use adequadamente. Consulte Melhore a chamada de ferramentas com uma documentação clara.
• Adicione timeouts e limites de tokens às chamadas LLM: Adicione timeouts e limites de tokens às chamadas LLM em seu código para evitar atrasos causados por etapas de longa duração.
  • Se o seu agente usar o cliente OpenAI para consultar um endpoint de atendimento do Databricks LLM, defina tempos limite personalizados nas chamadas de endpoint de atendimento, conforme necessário.

Depurar solicitações lentas ou com falha para agentes implantados

Se o senhor tiver ativado o MLflow trace autologging durante a criação do agente, os traços serão automaticamente registrados em tabelas de inferência. Esses rastreamentos podem ajudar a identificar os componentes do agente que estão lentos ou falhando.

Identifique solicitações problemáticas

Siga estas etapas para encontrar solicitações problemáticas:

1. Em seu site workspace, vá para Serving tab e selecione o nome da implantação.

2. Na seção Tabelas de inferência , encontre o nome totalmente qualificado da tabela de inferência. Por exemplo, my-catalog.my-schema.my-table.

3. Execute o seguinte em um notebook Databricks:

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table

4. Verifique a coluna Resposta para obter informações detalhadas sobre o rastreamento.

5. Filtre em request_time, databricks_request_id ou status_code para restringir os resultados.

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200

Analise a causa raiz dos problemas

Depois de identificar solicitações com falha ou lentas, use mlflow.models.validate_serving_input API para invocar seu agente contra a solicitação de entrada com falha. Em seguida, acesse view o rastreamento resultante e faça uma análise da causa raiz da resposta com falha.

Para um ciclo de desenvolvimento mais rápido, você pode atualizar o código do agente diretamente e iterar invocando seu agente no exemplo de entrada com falha.

Depurar erros de autenticação

Se o agente implantado encontrar erros de autenticação ao acessar um recurso, como índices de pesquisa de vetores ou o endpoint LLM, verifique se ele foi registrado com o recurso necessário para a passagem automática de autenticação. Consulte Passagem automática de autenticação.

Para inspecionar o recurso de logs, execute o seguinte em um Notebook:

Python

%pip install -U mlflow[databricks]
%restart_python

import mlflow
mlflow.set_registry_uri("databricks-uc")

# Replace with the model name and version of your deployed agent
agent_registered_model_name = ...
agent_model_version = ...

model_uri = f"models:/{agent_registered_model_name}/{agent_model_version}"
agent_info = mlflow.models.Model.load(model_uri)
print(f"Resources logged for agent model {model_uri}:", agent_info.resources)

Para adicionar novamente o recurso ausente ou incorreto, o senhor deve acessar log o agente e implantá-lo novamente.

Se o senhor estiver usando a autenticação manual para recurso, verifique se a variável de ambiente está definida corretamente. As configurações manuais substituem todas as configurações de autenticação automática. Consulte Autenticação manual.