Depurar um agente implantado AI

Esta página aborda como depurar problemas comuns com agentes AI implantados no Databricks.

Vá para:

• Práticas recomendadas
• Desenvolvimento local
• Problemas de configuração
• Problemas de implantação
• Erros Runtime
• Erros de autenticação
• Memória e armazenamento

A maioria das seções de depuração nesta página se aplicam a agentes implantados em Databricks Apps. No entanto, você também pode encontrar informações de depuração para agentes implantados no modelo instalado (legado) usando os seletores tab .

Agentes autores que utilizam as melhores práticas

Use as seguintes práticas recomendadas ao criar agentes:

• Ative o rastreamento MLflow : siga as melhores práticas em Criar um agente AI e implantá-lo em Databricks Apps. Habilite o registro automático de rastreamento do MLflow para facilitar a depuração de seus 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 limites de tempo e tokens às chamadas LLM : Adicione limites de tempo e tokens às chamadas LLM em seu código para evitar atrasos causados por etapas de longa duração.

  • Se o seu agente utiliza o cliente OpenAI para consultar um endpoint de serviço do Databricks LLM, defina tempos limite personalizados nas chamadas ao endpoint de serviço, conforme necessário.

• Valide a configuração antes da implantação : execute databricks bundle validate antes de implantar para detectar problemas de configuração YAML antecipadamente. Isso ajuda a identificar referências de recursos incompatíveis, permissões inválidas e erros de sintaxe.

• Teste localmente primeiro : Use o ambiente de desenvolvimento local para detectar problemas antes da implantação. Inicie o servidor do agente localmente, teste com solicitações de exemplo e verifique se os rastreamentos MLflow aparecem corretamente antes de implantá-lo no Databricks Apps.

Depurar problemas de desenvolvimento local

Teste seu agente localmente para identificar problemas antes da implantação.

Antes de executar o agente localmente, verifique se o seu ambiente está configurado corretamente:

1. Verifique a versão Databricks CLI : execução databricks -v para verificar se você tem a versão 0.283.0 ou posterior.

2. Verifique os perfis CLI : execute databricks auth profiles para ver os perfis de autenticação configurados.

3. Valide a configuração do ambiente : Verifique se o seu arquivo .env contém as variáveis necessárias, especialmente MLFLOW_TRACKING_URI, que deve usar o formato databricks://PROFILE_NAME para incluir seu perfil de CLI.

Erros comuns de desenvolvimento local

Erro	Causa	soluções
The provided MLFLOW_EXPERIMENT_ID does not exist	Formato de URI de acompanhamento incorreto ou experimento excluído	Verifique se MLFLOW_TRACKING_URI usa o formato databricks://PROFILE_NAME com o nome do seu perfil da CLI.
Module not found	Dependências não instaladas	execução uv sync para instalar dependências
Port already in use	Outro processo que utiliza a porta	Use a flag --port para especificar uma porta diferente (ex: uv run start-app --port 8001)
Erros de autenticação ao executar localmente	O ambiente não está configurado.	execute o script de início rápido ou configure manualmente o arquivo .env com seu perfil CLI

Teste o agente localmente

Para testar seu agente antes da implantação:

1. comece o servidor do agente localmente:

   Bash

   uv run start-app

2. Em outro terminal, envie uma solicitação de teste:

   Bash

   curl -X POST http://localhost:8000/invocations \
     -H "Content-Type: application/json" \
     -d '{"input": [{"role": "user", "content": "hello"}]}'

3. Visualize os rastreamentos MLflow na interface Databricks para verificar se o seu agente está registrando os rastreamentos corretamente.

Problemas de configuração de depuração

Erros de configuração em databricks.yml e app.yaml são causas comuns de falhas de implantação.

Valide a configuração dos Bundles Ativo Databricks .

Valide a configuração do Databricks ativo Bundles antes de implantar o aplicativo:

Bash

databricks bundle validate

Este comando verifica sua configuração para:

• erros de sintaxe YAML
• Campos obrigatórios ausentes
• Referências de recursos inválidas
• Problemas de configuração de permissões

Incompatibilidades comuns de configuração

Ponto de configuração	Regra	Como depurar
valueFrom referências em app.yaml	Deve corresponder exatamente a um recurso name em databricks.yml	Procure as mesmas sequências de caracteres em ambos os arquivos para verificar se elas correspondem.
Nome do aplicativo	Deve começar com o prefixo agent- (ex.: agent-data-analyst)	Verifique o campo name em resources.apps em databricks.yml
ID do espaço Genie	Devem ser as strings hexadecimais de 32 caracteres da URL do Genie	Extrair do caminho da URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referência de funções Unity Catalog	Deve-se usar o formato catalog.schema.function_name	Verifique se a função existe usando databricks unity-catalog functions list
Referência da instância do Lakebase	Deve-se usar value (e não valueFrom) no arquivo app.yaml	O nome da instância é uma string literal, não uma referência a um recurso.

Depurar problemas de implantação

Agents deployed to Apps

Erro "Aplicativo já existe"

Erro "Aplicativo já existe"

Se você vir Error: failed to create app - An app with the same name already exists, você tem duas opções:

Opção 1: Vincular a um aplicativo existente (recomendado)

Bash

# Get existing app configuration
databricks apps get <app-name> --output json

# Sync the configuration to your databricks.yml, then bind
databricks bundle deployment bind <bundle-name> <app-name> --auto-approve

# Deploy
databricks bundle deploy
databricks bundle run <bundle-name>

Opção 2: Excluir e recriar

Bash

databricks apps delete <app-name>
databricks bundle deploy
databricks bundle run <bundle-name>

O aplicativo não está atualizando após a implantação.

O aplicativo não está atualizando após a implantação.

databricks bundle deploy Faça o upload de arquivos somente para o workspace. Você também deve executar databricks bundle run <bundle-name> para reiniciar o aplicativo com o novo código.

Sempre implantado usando ambos os comandos:

Bash

databricks bundle deploy && databricks bundle run <bundle-name>

Visualizar o status e logsda implantação

Visualizar o status e logsda implantação

Para verificar o status de implantação do seu aplicativo:

Bash

databricks apps get <app-name>

Para view o registro do aplicativo em tempo real:

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

Se você implantou seu agente usando agents.deploy() em um endpoint de modelo instalado, revise o guia de depuração para modelo instalado para problemas específicos de implantação.

Para depurar problemas de tempo de execução, como solicitações lentas ou com falha, consulte Depurar erros de tempo de execução.

Depurar erros de tempo de execução

Agents deployed to Apps

Utilize logs do aplicativo e solicite testes para identificar problemas com seu agente implantado.

Analisar logsdo aplicativo

Veja logs em tempo real do seu aplicativo implantado:

Bash

databricks apps logs <app-name> --follow

Procurar:

• Rastreamentos de pilha indicando erros de código
• Mensagens de permissão negada para recurso
• Erros de conexão com serviço externo
• mensagens de tempo limite

Erros comuns de tempo de execução

Erro	Causa	soluções
Redirecionamento 302 ao consultar o aplicativo	Utilizando um token de acesso pessoal em vez de OAuth	Obtenha tokens OAuth com databricks auth token
Agente não está utilizando as ferramentas disponíveis	Ferramentas não devolvidas pelo cliente MCP	Verifique se o URL do servidor MCP está correto e se o recurso possui as permissões adequadas. databricks.yml
resposta de transmissão quebra no meio da resposta	Tempo limite de conexão	Aumente a variável de ambiente CHAT_PROXY_TIMEOUT_SECONDS em app.yaml
Agente retornando "Memória não disponível"	Falta user_id na solicitação	Passe custom_inputs.user_id na carga útil da solicitação.
Respostas vazias ou com erro, apesar do status 200.	Ocorreu um erro na resposta de transmissão	Verifique o conteúdo real da transmissão e logs do aplicativo, não apenas o código de status HTTP.

Agents on Model Serving (legacy)

Utilize tabelas de inferência e rastreamentos MLflow para identificar problemas com agentes implantados no endpoint do modelo de serviço.

Identifique solicitações problemáticas

Se você habilitou o registro automático de rastreamentoMLflow ao criar seu agente, os rastreamentos serão registrados automaticamente nas tabelas de inferência. Use esses rastreamentos para identificar componentes do agente que estejam lentos ou apresentando falhas.

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

Após identificar solicitações com falha ou lentas, use o parâmetro `mlflow.models.validate_serving_input`. API para invocar seu agente em relação à solicitação de entrada com falha. Visualize o rastreamento resultante e realize uma análise da causa raiz da resposta com falha.

Para um ciclo de desenvolvimento mais rápido, atualize o código do seu agente diretamente e itere invocando o agente no exemplo de entrada com falha.

Depurar erros de autenticação

Agents deployed to Apps

Autenticação com tokens OAuth necessária

Autenticação com tokensOAuth necessária

Você precisa usar tokens OAuth Databricks para consultar os agentes implantados nos aplicativos. O uso de um token de acesso pessoal (PAT) resulta em um erro de redirecionamento 302.

Para obter um token OAuth :

Bash

databricks auth token

Utilize os tokens nas requisições para o seu aplicativo implantado:

Bash

TOKEN=$(databricks auth token | jq -r '.access_token')
curl -X POST <app-url>/invocations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": [{"role": "user", "content": "hello"}]}'

erros de permissão de recurso

erros de permissão de recurso

Quando seu agente não conseguir acessar o recurso workspace , verifique se o recurso está configurado corretamente em databricks.yml. Cada tipo de recurso requer permissões específicas:

Error	Cause	Solution
Permission denied on Genie space	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
Vector search index not accessible	Missing uc_securable resource for the index	Add a uc_securable resource with securable_type: 'TABLE' and permission: 'SELECT'
Unity Catalog function execution denied	Missing uc_securable resource for the function	Add a uc_securable resource with securable_type: 'FUNCTION' and permission: 'EXECUTE'
Serving endpoint access denied	Missing serving_endpoint resource	Add a serving_endpoint resource with permission: 'CAN_QUERY'
SQL warehouse access denied	Missing sql_warehouse resource	Add a sql_warehouse resource with permission: 'CAN_USE'

Exemplo de configuração de recurso em databricks.yml:

YAML

resources:
  apps:
    my_agent:
      name: 'agent-my-app'
      resources:
        - name: 'my_genie_space'
          genie_space:
            space_id: '01234567890abcdef01234567890abcd'
            permission: 'CAN_RUN'
        - name: 'my_vector_index'
          uc_securable:
            securable_full_name: 'catalog.schema.index_name'
            securable_type: 'TABLE'
            permission: 'SELECT'

Permissões personalizadas do servidor MCP

Permissões personalizadas do servidor MCP

Se o seu agente se conectar a um servidor MCP personalizado executado como um aplicativo Databricks , você deverá conceder permissões manualmente, pois os aplicativos ainda não são suportados como dependências de recursos em databricks.yml.

Bash

# Get your agent app's service principal
AGENT_SP=$(databricks apps get <agent-app-name> --output json | jq -r '.service_principal_name')

# Grant permission on the MCP server app
databricks apps update-permissions <mcp-server-app-name> \
  --json "{\"access_control_list\": [{\"service_principal_name\": \"$AGENT_SP\", \"permission_level\": \"CAN_USE\"}]}"

Agents on Model Serving (legacy)

Se o seu agente de implantação encontrar erros de autenticação ao acessar recursos como índices de pesquisa vetorial ou endpoints LLM , verifique se ele registrou os logs necessários para a autenticação automática. Consulte Autenticação automática direta.

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 recursos ausentes ou incorretos, log no agente e implante-o novamente.

Se você utiliza autenticação manual para recursos, verifique se as variáveis de ambiente estão configuradas corretamente. As configurações manuais substituem quaisquer configurações de autenticação automática. Consulte Autenticação manual.

Depurar problemas de memória e armazenamento

Para agentes que utilizam o Lakebase para armazenamento em memória, os seguintes problemas são comuns:

Erro	Causa	soluções
relation 'store' does not exist	Tabelas de memória não inicializadas	execução await store.setup() localmente antes de ser implantado para criar as tabelas necessárias
Unable to resolve :re[LKB] instance	Nome da instância incorreto ou configuração incorreta	Verifique se LAKEBASE_INSTANCE_NAME usa value (e não valueFrom) em app.yaml e se corresponde a instance_name em databricks.yml
permission denied for table store	Permissões ausentes do Lakebase	Adicione um recurso database em databricks.yml com permission: 'CAN_CONNECT_AND_CREATE'
A memória não persiste entre conversas.	Diferentes user_id por solicitação	Certifique-se de passar um user_id consistente em custom_inputs para cada usuário.

Exemplo de configuração de recurso do Lakebase:

YAML

resources:
  apps:
    my_agent:
      resources:
        - name: 'memory_database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

Antes de implantar um agente com memória, inicialize as tabelas localmente:

Python

import asyncio
from databricks_langchain import AsyncDatabricksStore

async def setup_memory():
    async with AsyncDatabricksStore(
        instance_name='your-lakebase-instance',
        embedding_endpoint='databricks-gte-large-en',
        embedding_dims=1024,
    ) as store:
        await store.setup()

asyncio.run(setup_memory())