Depurar um agente de código personalizado

Esta página aborda como depurar problemas comuns com agentes de código personalizado implantados no Databricks.

Ir para:

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

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

Crie agentes usando as melhores práticas

Use as seguintes práticas recomendadas ao criar agentes:

• Ative o rastreamento do MLflow: Siga as melhores práticas em Crie um agente de AI e implante-o em Databricks Apps. Ative o autologging de rastreamento do MLflow para facilitar a depuração de seus agentes.

• Documentar ferramentas claramente : Descrições claras de ferramentas e parâmetros garantem que seu agente compreenda suas ferramentas e as utilize adequadamente. Consulte Melhore a chamada de ferramentas com documentação clara.

• Adicione tempos limite e limites de tokens às chamadas LLM : adicione tempos limite e limites de tokens às chamadas LLM em seu código para evitar atrasos causados por passos de longa execução.

  • Se seu agente usa o cliente OpenAI para query um endpoint de disponibilização de LLM do Databricks, defina tempos limite personalizados nas chamadas do endpoint de disponibilização, conforme necessário.

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

• Teste localmente primeiro : use o desenvolvimento local para identificar problemas antes de implantar. Comece seu servidor de agente localmente, teste com solicitações de amostra e verifique se os rastreamentos do MLflow aparecem corretamente antes de implantar no Databricks Apps.

Depurar problemas de desenvolvimento local

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

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

1. **Verifique a versão da CLI do Databricks**: Execute databricks -v para verificar se você tem a versão 0.283.0 ou posterior.

2. Verificar perfis da CLI : Execute databricks auth profiles para ver os perfis de autenticação configurados.

3. Validar 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 da CLI.

Erros comuns de desenvolvimento local

Erro	Causa	soluções
The provided MLFLOW_EXPERIMENT_ID does not exist	Formato 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 CLI.
Module not found	Dependências não instaladas	Execute uv sync para instalar dependências
Port already in use	Outro processo usando a porta	Use o sinalizador --port para especificar uma porta diferente (por exemplo, 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 da CLI.

Erro	Causa	soluções
The provided MLFLOW_EXPERIMENT_ID does not exist	Formato 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 CLI.
Module not found	Dependências não instaladas	Execute uv sync para instalar dependências
Port already in use	Outro processo usando a porta	Use o sinalizador --port para especificar uma porta diferente (por exemplo, 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 da CLI.

Teste o agente localmente

Para testar seu agente antes da implantação:

1. Inicie 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 do MLflow na UI do Databricks para verificar se o seu agente está registrando rastreamentos corretamente.

Depurar problemas de configuração

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

Validar a configuração de Pacotes de Automação Declarativa

Valide a configuração dos Pacotes de Automação Declarativa 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 recurso inválidas
• Problemas de configuração de permissões

Incompatibilidades de configuração comuns

Ponto de configuração	Regra	Como depurar
valueFrom referências em app.yaml	Deve corresponder exatamente a um recurso name em databricks.yml	Procure a string exata em ambos os arquivos para verificar se elas correspondem
Nome do aplicativo	Deve começar com o prefixo agent- (por exemplo, agent-data-analyst)	Verifique o campo name em resources.apps em databricks.yml
ID do Genie Agent.	Deve ser a string hexadecimal de 32 caracteres da URL do Genie	Extrair do caminho da URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referência da função do Unity Catalog	Deve 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 usar value (não valueFrom) no arquivo app.yaml	O nome da instância é um literal de string, não uma referência de recurso

Ponto de configuração	Regra	Como depurar
valueFrom referências em app.yaml	Deve corresponder exatamente a um recurso name em databricks.yml	Procure a string exata em ambos os arquivos para verificar se elas correspondem
Nome do aplicativo	Deve começar com o prefixo agent- (por exemplo, agent-data-analyst)	Verifique o campo name em resources.apps em databricks.yml
ID do Genie Agent.	Deve ser a string hexadecimal de 32 caracteres da URL do Genie	Extrair do caminho da URL: https://workspace.cloud.databricks.com/genie/rooms/{SPACE_ID}
Referência da função do Unity Catalog	Deve 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 usar value (não valueFrom) no arquivo app.yaml	O nome da instância é um literal de string, não uma referência de recurso

Depurar problemas de implantação

Agents deployed to Apps

Erro: aplicativo já existe

Erro: aplicativo já existe

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

Opção 1: Vincular a 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: Exclua e recrie

Bash

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

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

O aplicativo não atualiza após a implantação

databricks bundle deploy apenas faz upload de arquivos para o workspace. O senhor também deve executar databricks bundle run <bundle-name> para reiniciar o aplicativo com o novo código.

Sempre implante usando ambos os comandos:

Bash

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

Ver status da implementação e Logs

Visualizar status da implantação e logs

Para verificar o status da implementação do seu aplicativo:

Bash

databricks apps get <app-name>

Para visualizar logs do aplicativo em tempo real:

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

Se o senhor implantou seu agente usando agents.deploy() em um Endpoint de Model Serving, consulte o guia de depuração para Model Serving para problemas específicos de implantação.

Para depurar problemas de Runtime, como solicitações lentas ou com falha, consulte Depurar erros de Runtime.

Depurar erros de Runtime

Agents deployed to Apps

Use Logs de aplicativo e teste de solicitação para identificar problemas com seu agente implantado.

Analisar logs de aplicativo

Visualize logs em tempo real do seu aplicativo implantado:

Bash

databricks apps logs <app-name> --follow

Procure por:

• Rastreamentos de pilha indicando erros de código.
• Mensagens de permissão negada para recursos
• Erros de conexão a serviços externos
• Mensagens de tempo esgotado

Erros comuns de Runtime

Erro	Causa	soluções
Redirecionamento 302 ao consultar o aplicativo	Usando Token de Acesso Pessoal em vez de OAuth	Obter um token OAuth com databricks auth token
Agente não usando ferramentas disponíveis.	Ferramentas não retornadas do cliente MCP	Verifique se o URL do servidor MCP está correto e se o recurso possui as permissões adequadas em databricks.yml
Transmissão da resposta é interrompida no meio da resposta	Tempo limite de conexão	Aumente a variável de ambiente CHAT_PROXY_TIMEOUT_SECONDS em app.yaml
O agente está retornando "Memória não disponível".	Ausente user_id na solicitação	Passe custom_inputs.user_id no payload da solicitação
Respostas vazias ou com erro apesar do status 200	Erro ocorrido na resposta em transmissão	Verifique o conteúdo real da transmissão e os logs do aplicativo, não apenas o código de status HTTP

Erro	Causa	soluções
Redirecionamento 302 ao consultar o aplicativo	Usando Token de Acesso Pessoal em vez de OAuth	Obter um token OAuth com databricks auth token
Agente não usando ferramentas disponíveis.	Ferramentas não retornadas do cliente MCP	Verifique se o URL do servidor MCP está correto e se o recurso possui as permissões adequadas em databricks.yml
Transmissão da resposta é interrompida no meio da resposta	Tempo limite de conexão	Aumente a variável de ambiente CHAT_PROXY_TIMEOUT_SECONDS em app.yaml
O agente está retornando "Memória não disponível".	Ausente user_id na solicitação	Passe custom_inputs.user_id no payload da solicitação
Respostas vazias ou com erro apesar do status 200	Erro ocorrido na resposta em transmissão	Verifique o conteúdo real da transmissão e os logs do aplicativo, não apenas o código de status HTTP

Agents on Model Serving (legacy)

Use tabelas de inferência e rastreamentos do MLflow para identificar problemas com agentes implantados em endpoints de Model Serving.

Identificar solicitações problemáticas

Se você habilitou o autologging de rastreamento MLflow ao criar seu agente, os rastreamentos são registrados automaticamente nas tabelas de inferência. Use estes rastreamentos para identificar componentes do agente que estão lentos ou com falha.

1. No seu Workspace, vá para a tab Model Serving e selecione o nome da sua 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. Inspecione a coluna Response para obter informações detalhadas de rastreamento.

5. Filtrar por 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 problemas de causa raiz

Após 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. Visualize o rastreamento resultante e realize a análise da causa raiz na resposta com falha.

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

Depurar erros de autenticação

Agents deployed to Apps

Autenticação de token OAuth necessária.

Autenticação de token OAuth necessária

Você deve usar um token OAuth do Databricks para fazer query em agentes implantados em Apps. 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

Use o token em solicitações para 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 os recursos do 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 Agent	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
AI 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'

Error	Cause	Solution
Permission denied on Genie Agent	Missing genie_space resource	Add a genie_space resource with permission: 'CAN_RUN'
AI 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 de servidor MCP personalizado

Permissões do servidor MCP customizado

Se seu agente se conecta a um servidor MCP personalizado executando como um aplicativo Databricks, você deve conceder permissões manualmente, já que 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 implantado encontrar erros de autenticação ao acessar recursos como índices de Pesquisa de AI ou Endpoints LLM, verifique se ele foi registrado com os recursos necessários para a passagem automática de autenticação. Consulte Passagem automática de autenticação.

Para inspecionar os recursos registrados, execute o seguinte em um notebook:

Python

%pip install -U mlflow[databricks]==2.20.2
%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, registre o agente e implante-o novamente.

Se você usar 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áticas. Consulte Autenticação manual.

Depurar problemas de memória e armazenamento

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

Erro	Causa	soluções
relation 'store' does not exist	Tabelas de memória não inicializadas	Execute await store.setup() localmente antes de implantar 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 corresponde a instance_name em databricks.yml
permission denied for table store	Permissões ausentes do Lakebase	Adicionar um database recurso em databricks.yml com permission: 'CAN_CONNECT_AND_CREATE'
Memória não persistindo entre conversas.	Diferentes user_id por solicitação	Certifique-se de que você passe um user_id consistente em custom_inputs para cada usuário.

Erro	Causa	soluções
relation 'store' does not exist	Tabelas de memória não inicializadas	Execute await store.setup() localmente antes de implantar 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 corresponde a instance_name em databricks.yml
permission denied for table store	Permissões ausentes do Lakebase	Adicionar um database recurso em databricks.yml com permission: 'CAN_CONNECT_AND_CREATE'
Memória não persistindo entre conversas.	Diferentes user_id por solicitação	Certifique-se de que você passe um user_id consistente em custom_inputs para cada usuário.

Exemplo de configuração de recursos 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())