Diagnosticar um agente

Este guia explica como descobrir porque é que um agente não está a produzir execuções.

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

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

Definições → Espaço de trabalho → Agentes → selecione o agente → Registos.

Cada execução mostra um distintivo de estado, uma duração (“Em execução…” enquanto está em curso), as horas de início e de conclusão, o PID e o adaptador utilizado. Ver abre o fluxo de eventos em bruto dessa execução. Parar encerra um processo em execução e marca a execução como “Encerrada pelo utilizador”; Encerrar em execução, no cabeçalho, faz o mesmo a todas as execuções em curso desse agente.

Leia-o assim:

Nenhuma execução de todo — o despacho nunca aconteceu. As menções no compositor são @ mais caracteres de palavra (letras, dígitos, sublinhado). A resolução é uma correspondência exata ou por prefixo com o nome do agente, pelo que @code-reviewer é interpretado como code e ainda pode despertar um agente chamado code-reviewer. Um nome com um espaço não pode ser mencionado como um único token. Avance então para o passo 2.
Uma execução que terminou de imediato com erro — abra Ver. Uma falha ao iniciar o backend aparece aqui como um erro de processo.
Uma execução presa em “Em execução…” — pare-a e verifique depois o Tempo de silêncio do agente no separador Definições. Um tempo limite não definido usa a predefinição de cada modo.
Uma execução concluída sem resultado útil — o estado no registo de execução permanece completed numa execução que terminou sem o resultado declarado; o sinal honesto é o texto do resumo, não o distintivo.

O separador Registos não mostra custos. Para os gastos, use a tabela por agente em Observabilidade → Resumo.

2. Verifique o backend do agente

Definições → Servidor → Fornecedores de modelos (/settings/server/providers).

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

A sonda é executada na máquina que aloja o cc_server, não na máquina que está a ver. Se estiver no cliente web ou num dispositivo emparelhado, “Não encontrado” significa que falta a CLI no anfitrião do servidor.

Dois pontos a confirmar:

O agente tem sequer um adaptador definido. Um agente com o adaptador vazio é despachado para o Control Center (built-in) e o registo de execução regista cc-harness, pelo que a transcrição indica o que foi executado. Sem modelo também, pede à Anthropic o respetivo modelo predefinido — o que falha com No credential for provider "anthropic" a menos que tenha ligado uma conta Anthropic. Os especialistas pré-instalados vêm sem adaptador.
O adaptador integrado tem um modelo. A sua lista de modelos vem em tempo real dos fornecedores ligados mais abaixo nesta mesma página, pelo que um fornecedor sem credencial guardada contribui com zero modelos.

O catálogo de adaptadores em si é fixo — não há forma de registar um novo adaptador. O que pode alterar por adaptador aqui são os respetivos argumentos de arranque e variáveis de ambiente. Note que uma substituição do ambiente por adaptador ganha silenciosamente a uma conta de fornecedor ligada quando as credenciais são resolvidas.

3. Verifique o servidor

Definições → Servidor → Ligação e status (/settings/server/connection) mostra com que servidor este cliente está a comunicar e o que este reporta.

Num servidor headless, GET /healthz dá a mesma informação sem um cliente. É não autenticado e aberto a CORS por conceção:

curl http://localhost:9030/healthz

Devolve o estado do servidor, o tempo de atividade em segundos, o número de ligações ativas, a porta de associação, a versão da build e o SHA do git, a versão do esquema do espaço de trabalho, a versão do catálogo RPC, o id, o nome e a impressão digital de identidade do servidor, se a associação é insegura e um bloco codeGraph com contagens de watching / indexing / pending. Quando uma cache já viu tráfego, inclui também um bloco caches; um servidor de demonstração acrescenta demo: true.

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

O cliente de computador inicia um binário cc_server pré-compilado, com preferência sobre o código-fonte. Uma nova operação RPC ou ferramenta MCP só aparece depois de o binário ser recompilado, e o arranque regista um aviso quando o SHA do git do processo filho difere do SHA da aplicação.
O cliente de computador encerra um servidor lançado que não tenha impresso o seu aviso de disponibilidade em 20 segundos e passa para um ecrã de erro.

4. Verifique o anfitrião

Definições → Servidor → Diagnóstico e privacidade (/settings/server/diagnostics) é a página ao nível do anfitrião. Contém:

Sandbox — o interruptor principal, o backend detetado e uma sugestão de instalação. Só o backend detetado vem do servidor; veja a advertência abaixo. Não existe controlo de reposição.
Pesquisa semântica — o ciclo de vida do modelo de embedding no dispositivo: instalado, a transferir com uma percentagem, não instalado ou um erro de instalação. Enquanto não estiver instalado, a pesquisa na memória e no código fica limitada a palavras-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 do diff em bruto pode ser encaminhado para o modelo do agente e se são enviados relatórios de falhas.

A deteção e a aplicação coincidem agora: quando o detetor reporta um backend nativo, as execuções de agentes nesse anfitrião são realmente envolvidas por ele. Mas o detetor é a única coisa ativa nesta secção. O interruptor principal e o seletor de backend são preferências guardadas no seu dispositivo e o servidor não lê nenhuma delas — o interruptor do próprio servidor é --sandbox (on por predefinição, off para desativar).

Por isso, vale a pena agir sobre um aviso aqui, mas normalmente não é a razão pela qual um agente está a falhar. Para confirmar em que estado está o servidor, leia o registo de arranque: imprime agent sandbox ON com a nota do backend, no OS-native agent sandbox on this host com uma sugestão de instalação, ou agent sandbox DISABLED by --sandbox off. O GET /healthz não inclui qualquer campo de sandbox.

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

Falhas comuns

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

Instale a CLI no anfitrião do servidor e clique em Atualizar na página Fornecedores de modelos. Ou mude o agente para o adaptador integrado, que não precisa de CLI, e ligue um fornecedor 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 o negou ou que uma aprovação ficou sem resposta: verifique Fazer push para um remoto e Abrir um pull request em Definiçõ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 a GitHub App nesse repositório ou ligue o GitHub.

A pesquisa semântica não devolve nada de útil

Verifique Definições → Servidor → Diagnóstico e privacidade → Pesquisa semântica. Enquanto o modelo de embedding não estiver instalado, a pesquisa é apenas por palavras-chave. As linhas escritas antes de o modelo ser instalado nunca são preenchidas retroativamente, pelo que continuam apenas por palavras-chave mesmo depois.

O servidor não arranca de todo

As bibliotecas nativas são obrigatórias e não existe modo degradado. Uma dylib em falta faz com que o cc_server se recuse a arrancar e indique o responsável no erro. Prepare as bibliotecas nativas 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 nenhum aprovador ligado é negada, por conceção. Verifique as regras do espaço de trabalho em Definições → Espaço de trabalho → Permissões dos agentes.