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.

Criar agentes utilizando as melhores práticas

Use as seguintes práticas recomendadas ao criar agentes:

• Habilite o rastreamento do MLflow : Siga as práticas recomendadas em Autorizar um agente de AI e implantado no Databricks Apps. Habilite o autologging de rastreamento do MLflow para facilitar a depuração dos seus agentes.

• **Documente as ferramentas claramente**: Descrições claras de ferramentas e parâmetros garantem que seu agente compreenda suas ferramentas e as utilize de forma adequada. Consulte Aprimorar a chamada de ferramentas com documentação clara.

• Adicionar 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 os passos de longa execução.

  • Se o seu agente usar o cliente OpenAI para consultar um endpoint de serviço LLM da Databricks, defina timeouts personalizados nas chamadas do endpoint de serviço, conforme necessário.

• Validar a 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 recurso incompatíveis, permissões inválidas e erros de sintaxe.

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

Depurar problemas de desenvolvimento local

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

Antes da execução do seu agente localmente, verifique se seu ambiente está configurado corretamente:

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

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

3. Validar 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 de URI de acompanhamento incorreto ou experimento foi 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 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. Comece o servidor de 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 rastreamentos do MLflow na IU do Databricks para verificar se o 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.

Valide a configuração dos Pacotes de Automação Declarativa

Valide a configuração dos Pacotes de Automação Declarativa antes de implantado 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ão

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	Busque pelas strings exatas em ambos os arquivos para verificar se eles 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 Space	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 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 de recurso

Depurar problemas de implantação

Agents deployed to Apps

Erro: o aplicativo já existe

Erro de aplicativo já existente

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

Aplicativo não atualizando após a implantação

App não atualiza após implantado

databricks bundle deploy apenas faz upload de arquivos para o workspace. Você 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>

view status da implementação e log

view status e log da implantação

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

Bash

databricks apps get <app-name>

Para view logs de aplicativo em tempo real:

Bash

databricks apps logs <app-name> --follow

Agents on Model Serving (legacy)

Caso tenha implantado seu agente usando agents.deploy() em um endpoint do Model Serving, consulte o guia de depuração do Model Serving para problemas específicos da 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 runtime

Agents deployed to Apps

Utilize os logs do aplicativo e testes de solicitação para identificar problemas com o agente implantado.

Analisar log de aplicativo

View 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 limite

Erros comuns de tempo de execução

Erro	Causa	soluções
Redirecionamento 302 ao consultar o app	Uso de personal access token em vez de OAuth	Obtenha um tokens OAuth com databricks auth token
Agente não usando as ferramentas disponíveis	Ferramentas não retornadas do cliente MCP	Verifique se a URL do servidor MCP está correta e se o recurso tem as permissões adequadas em databricks.yml
A resposta de transmissão é interrompida 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"	Ausente 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 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 do Model Serving.

Identifique solicitações problemáticas

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

1. No seu workspace, acesse a tab **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 **Resposta** para informações detalhadas de rastreamento.

5. Filtre 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

Analisar problemas de causa raiz

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. View o rastreamento resultante e execute a análise da causa raiz na resposta com falha.

Para um ciclo de desenvolvimento mais rápido, atualize o código do seu 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 tokens OAuth necessária

Autenticação de tokens OAuth necessária

Você deve usar tokens OAuth do Databricks para consultar agentes implantados em Aplicativos. O uso de um access token Pessoal (PAT) resulta em um erro de redirecionamento 302.

Para obter um tokens 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 exige 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'
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 recursos 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 do servidor MCP personalizado

Permissões de servidor MCP personalizado

Se o 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 recurso 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 seu agente implantado encontrar erros de autenticação ao acessar recursos como índices de AI Search ou endpoints LLM, verifique se foi feito o log com os recursos necessários para autenticação passthrough automática. Consulte passagem de autenticação automática.

Para inspecionar os recursos logados, faça a execução do 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 recurso ausentes ou incorretos, faça log do agente e deixe-o implantado novamente.

Se você usar autenticação manual para recursos, verifique se as variáveis de ambiente estão definidas 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 (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 persistente entre conversas.	Diferentes user_id por solicitação	Certifique-se de passar um user_id consistente em custom_inputs para cada usuário

Configuração de exemplo 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())