Diagnosticar um agente

Este guia mostra como descobrir por que um agente não está produzindo execuções.

Trabalhe de cima para baixo: primeiro as execuções do próprio agente, depois o backend dele, depois o servidor e, por fim, o host.

1. Verifique o histórico de execuções do agente

Configurações → Espaço de trabalho → Agentes → selecione o agente → Registros.

Cada execução mostra um selo de status, uma duração (“Running…” enquanto está em andamento), os horários de início e de conclusão, o PID e o adaptador utilizado. Visualizar abre o stream de eventos bruto dessa execução. Parar encerra um processo em execução e marca a execução como “Killed by user”; Encerrar em execução, no cabeçalho, faz o mesmo com todas as execuções em andamento desse agente.

Leia assim:

Nenhuma execução — o despacho nunca aconteceu. As menções no compositor de mensagens são @ mais caracteres de palavra (letras, dígitos, sublinhado). A resolução é uma correspondência exata ou por prefixo no nome do agente, então @code-reviewer é interpretado como code e ainda pode acordar um agente chamado code-reviewer. Um nome com espaço não pode ser mencionado como um único token. Depois, passe para a etapa 2.
Uma execução que terminou imediatamente com erro — abra Visualizar. Uma falha ao iniciar o backend aparece aqui como um erro de processo.
Uma execução presa em “Running…” — pare-a e depois verifique o Tempo de silêncio do agente na aba Configurações. Um tempo limite não definido usa o padrão por modo.
Uma execução concluída sem saída útil — o status no log de execução permanece completed para uma execução que terminou sem o resultado declarado; o sinal confiável é o texto do resumo, e não o selo.

A aba Registros não mostra custo. Para gastos, use a tabela por agente em Observabilidade → Resumo.

2. Verifique o backend do agente

Configurações → Servidor → Provedores de modelos (/settings/server/providers).

A lista Executores detectados mostra cada adaptador com o resultado da sondagem — uma versão instalada, “Verificando…” ou “Não encontrado” — além do caminho resolvido e dos chips de capacidade de uma CLI encontrada. Clique em Atualizar no cabeçalho da página para sondar novamente.

A sondagem é executada na máquina que hospeda o cc_server, e não na máquina que você está usando. Se você estiver no cliente web ou em um dispositivo emparelhado, “Não encontrado” significa que a CLI está ausente no host do servidor.

Duas coisas a confirmar:

Se o agente tem mesmo um adaptador definido. Um agente com adaptador vazio é despachado para o Control Center (built-in) e o log de execução registra cc-harness, então a transcrição nomeia o que foi executado. Sem modelo também, ele pede à Anthropic o modelo padrão dela — o que falha com No credential for provider "anthropic" a menos que você tenha conectado uma conta Anthropic. Os especialistas fornecidos de fábrica vêm sem adaptador.
Se o adaptador integrado tem um modelo. A lista de modelos dele vem ao vivo dos provedores conectados mais abaixo nesta mesma página, então um provedor sem credencial armazenada contribui com zero modelos.

O catálogo de adaptadores em si é fixo — não há como registrar um novo adaptador. O que você pode alterar por adaptador aqui são os argumentos de inicialização e as variáveis de ambiente dele. Observe que uma substituição de ambiente por adaptador supera silenciosamente uma conta de provedor conectada quando as credenciais são resolvidas.

3. Verifique o servidor

Configurações → Servidor → Conexão e status (/settings/server/connection) mostra com qual servidor este cliente está falando e o que ele relata.

Para um servidor headless, GET /healthz traz as mesmas informações sem um cliente. Ele não exige autenticação e é aberto para CORS por design:

curl http://localhost:9030/healthz

Ele retorna o status do servidor, o tempo de atividade em segundos, a contagem de conexões ativas, a porta vinculada, a versão de build e o SHA do git, a versão do esquema do espaço de trabalho, a versão do catálogo de RPC, o id, o nome e a impressão digital de identidade do servidor, se a vinculação é insegura e um bloco codeGraph com contagens de watching / indexing / pending. Quando um cache já recebeu tráfego, ele também inclui um bloco caches; um servidor de demonstração adiciona demo: true.

Duas coisas que vale a pena saber quando uma alteração “funciona nos testes, mas não no app”:

O desktop inicia um binário cc_server precompilado com preferência sobre o código-fonte. Uma nova operação RPC ou ferramenta MCP não aparece até o binário ser recompilado, e a inicialização registra um aviso quando o SHA do git do processo filho difere do SHA do app.
O desktop encerra um servidor iniciado que não imprimiu o banner de prontidão em até 20 segundos e cai para uma tela de erro.

4. Verifique o host

Configurações → Servidor → Diagnóstico e privacidade (/settings/server/diagnostics) é a página de nível do host. Ela traz:

Sandbox — o interruptor principal, o backend detectado e uma dica de instalação. Apenas o backend detectado vem do servidor; veja o aviso abaixo. Não há controle de redefinição.
Busca semântica — o ciclo de vida do modelo de embedding no dispositivo: instalado, sendo baixado com uma porcentagem, não instalado ou um erro de instalação. Enquanto ele não estiver instalado, a busca em memória e em código permanece apenas por palavra-chave.
Comportamento do sistema — manter o computador acordado enquanto os agentes são executados.
Nível de log — aumente-o antes de reproduzir uma falha.
Privacidade — se o conteúdo bruto do diff pode ser encaminhado ao modelo do agente e se relatórios de falhas são enviados.

A detecção e a aplicação agora concordam: onde o detector relata um backend nativo, as execuções de agentes nesse host realmente são envolvidas por ele. Mas o detector é a única coisa viva nesta seção. O interruptor principal e o seletor de backend são preferências armazenadas no seu dispositivo, e o servidor não lê nenhuma delas — o interruptor do próprio servidor é --sandbox (on por padrão, off para desativar).

Então, vale a pena agir sobre um aviso aqui, mas ele normalmente não é o motivo pelo qual um agente está falhando. Para confirmar em que estado o servidor está, leia o log de inicialização dele: ele imprime agent sandbox ON com a observação do backend, no OS-native agent sandbox on this host com uma dica de instalação, ou agent sandbox DISABLED by --sandbox off. GET /healthz não traz nenhum campo de sandbox.

Onde não há backend — sempre no Windows, e no Linux ou WSL2 sem bwrap e socat — as execuções não usam sandbox, e o que as limita é o próprio checkout da conversa, o token de forge somente leitura dela e o gateway de push, as guardrails de ação, a sanitização do ambiente e a superfície de ferramentas que o modo dela permite.

Falhas comuns

A execução nunca começa e o adaptador mostra “Não encontrado”

Instale a CLI no host do servidor e clique em Atualizar na página Provedores de modelos. Ou mude o agente para o adaptador integrado, que não precisa de CLI, e conecte um provedor na mesma página.

O agente não consegue fazer push nem abrir uma pull request

Leia o que o git ou o agente mostrou. Control Center policy: … significa que uma regra de ação negou ou que uma aprovação ficou sem resposta: verifique Fazer push para um remoto e Abrir um pull request em Configurações → Espaço de trabalho → Permissões dos agentes. Se o git disser que o Control Center não tem nenhuma credencial do GitHub capaz de fazer push, instale o GitHub App nesse repositório ou conecte o GitHub.

A busca semântica não retorna nada útil

Verifique Configurações → Servidor → Diagnóstico e privacidade → Busca semântica. Enquanto o modelo de embedding não estiver instalado, a busca é apenas por palavra-chave. As linhas gravadas antes de o modelo ser instalado nunca são preenchidas retroativamente, então continuam apenas por palavra-chave mesmo depois disso.

O servidor não inicia de forma alguma

As bibliotecas nativas são obrigatórias e não existe modo degradado. Uma dylib ausente faz o cc_server se recusar a iniciar e nomear o culpado no erro. Prepare os nativos com scripts/natives/build_natives.sh e recompile o binário do servidor.

Uma ação é negada silenciosamente

Uma decisão de guardrail prompt sem aprovador conectado é negada, por design. Verifique as regras do espaço de trabalho em Configurações → Espaço de trabalho → Permissões dos agentes.