Para que serve o log_work?
O agente não precisa de procurar IDs antes de registar. Chama o log_work diretamente com uma descrição e o que mais souber. A Half5 identifica o cliente, projeto e atividade, ou faz uma pergunta quando não tem certeza.
O registo entra como ‘Por aprovar’ em seu nome. Assim mantém o controlo, mesmo quando o agente preencheu o trabalho. Como ligar um agente está em Registar horas com Claude, ChatGPT ou Cursor.
Que campos envia o agente?
Só a descrição é obrigatória. Os restantes ajudam a Half5 a escolher o cliente e a duração certos. Sem data, a Half5 regista para hoje. Sem duração, não regista nada mas propõe-lhe uma para confirmar. Sem cliente, só escolhe automaticamente quando um cliente é claramente o mais provável.
| Campo | Obrigatório | Descrição |
|---|---|---|
description | Sim | Uma linha de 3 a 500 caracteres, legível para o cliente, na sua língua, sem nomes de ficheiros ou classes. Pode aparecer em fatura. |
date | Não | today, yesterday ou uma data (AAAA-MM-DD). Se não indicar, assume hoje. |
minutes | Não | Duração em minutos, de 1 a 1.440. Deixe em branco se não souber a duração. |
start_time, end_time | Não | Hora de início e fim em HH:MM. Se a hora de fim for anterior à de início, considera-se que passou da meia-noite: 21:30 a 01:30 é um registo de 4 horas no dia de início. |
customer, project, activity | Não | Nome, designação comercial ou referência. Um projeto implica sempre o seu cliente. |
repository | Não | Git remote, owner/repo ou nome da pasta. Nunca um caminho local completo. |
branch, commit_subjects | Não | A branch e até 10 assuntos de commit, como pistas adicionais para cliente e projeto. |
session_id | Não | ID da sessão do agente, apenas se realmente souber. |
Quais são os resultados possíveis?
Cada chamada termina num de quatro estados. Cada um pede algo diferente ao agente.
| Resultado | Significado | O que faz o agente |
|---|---|---|
created | O registo foi guardado, ainda por aprovar. | Informa-o numa frase do que foi registado e porquê naquele cliente. |
preview | Simulação: mostra o que seria registado. Nada é guardado. | Apresenta-lhe a proposta. |
needs_confirmation | A Half5 não tem certeza, por exemplo sobre o cliente, ou falta a duração (‘Quanto tempo trabalhou nisto?’ com uma duração sugerida). | Faz-lhe a pergunta e só regista após a sua escolha, exatamente com a opção selecionada. |
duplicate | Esse trabalho já foi registado. | Não volta a registar. |
Sem duração, a Half5 não guarda nada. A proposta cobre, por exemplo, do fim do seu último registo de hoje até agora; confirma ou ajusta.
Como escolhe a Half5 o cliente e o projeto?
Primeiro o cliente, depois o projeto desse cliente. A Half5 avalia as pistas disponíveis e só regista automaticamente quando um cliente é claramente o mais provável. Caso contrário, o agente pede-lhe para escolher entre as combinações recentes de cliente e projeto.
- O que indicar. Um cliente ou projeto nomeado prevalece. Se dois clientes tiverem o mesmo nome, por exemplo só diferindo em maiúsculas, ganha a grafia exata, depois o cliente em que já registou esse repositório, depois o cliente onde regista mais. Só pergunta se nada disso decidir.
- A memória do seu repositório. A Half5 recorda, por utilizador, a que cliente pertence cada repositório, aprendido a partir de registos que confirmou ou moveu.
- O nome do repositório. Comparado com os nomes (comerciais), etiquetas e domínios de e-mail dos seus clientes, e com nomes de projetos.
- O seu histórico. Descrições anteriores que mencionem o repositório, branch ou número de ticket, e clientes em que regista recentemente e com frequência.
- Descrição, branch e commits. Como pista adicional, não como critério decisivo.
Como funciona a memória do repositório?
A memória é sua. Ao registar via agente, mover esse registo para outro cliente ou registar trabalho do agente na aplicação desktop, a Half5 associa o repositório ao cliente. Da próxima vez, o agente já não precisa de perguntar.
Se a descrição indicar claramente outro cliente diferente da memória, a Half5 não regista sem perguntar: o agente pede-lhe para escolher entre os dois. Com a opção de organização ‘Aprender com colegas’, a Half5 pode sugerir um cliente que um colega já associou ao mesmo repositório. É sempre uma sugestão; o agente pergunta sempre primeiro e a sua própria memória tem prioridade.
Que outras ferramentas existem além do log_work?
O servidor disponibiliza seis ferramentas. Todas funcionam apenas sobre as suas próprias horas, com os clientes, projetos e atividades a que tem acesso na sua organização.
| Ferramenta | Função | Limites |
|---|---|---|
log_work | Registar trabalho | Novos registos entram como por aprovar |
log_work_batch | Até 25 registos numa chamada, por exemplo uma semana inteira em atraso | Cada registo tem as mesmas validações e perguntas que o log_work; uma resposta a uma pergunta de cliente comum aplica-se a todos os registos que a façam |
search_customers_projects | Pesquisar clientes, projetos e atividades por nome, designação comercial, etiqueta ou domínio de e-mail | Só leitura; não é necessário antes do log_work |
list_entries | Listar os seus registos com totais diários | Só leitura; até 31 dias de cada vez |
update_entry | Alterar um dos seus registos | Apenas registos ainda por aprovar, e só a seu pedido |
delete_entry | Eliminar um dos seus registos | Apenas registos ainda por aprovar, após confirmação |
Depois de aprovado, o agente já não pode alterar o registo. Só o pode fazer na própria Half5.
Como a Half5 faz
Em Definições → ‘Agentes ligados’ vê o nome do cliente de cada ligação, se está verificada, quando foi usada pela última vez e o que pode fazer (ver horas, registar horas). ‘Desligar’ retira o acesso.
Na mesma página encontra a memória dos seus repositórios. Pode apagar uma ligação com ‘Esquecer …’ ou recomeçar com ‘Esquecer tudo’. O destino destes dados está em Privacidade com agentes de IA. Para projetos de I&D ao abrigo do WBSO neerlandês, a Half5 não tem exportação WBSO dedicada; como configurar está em Horas WBSO com software.
Perguntas frequentes
O agente precisa de chamar o search_customers_projects antes de registar?
Não. O log_work identifica o cliente e projeto automaticamente. A pesquisa serve para questões como ‘que projetos tem este cliente?’ ou para nomes ambíguos.
O que acontece se o agente enviar o mesmo registo duas vezes?
A Half5 reconhece o mesmo registo e devolve duplicate em vez de criar um segundo. O agente não deve voltar a registar.
O agente envia o meu código ou nomes de ficheiros?
Não deve. O servidor indica explicitamente aos agentes para nunca enviarem caminhos de ficheiros ou código; a descrição é uma linha legível para o cliente e o repositório só é enviado como nome.
A memória de um colega pode decidir a que cliente vão as minhas horas?
Não. A memória de um colega serve apenas de sugestão, e só se ‘Aprender com colegas’ estiver ativo. O agente pergunta-lhe sempre primeiro.
O agente pode alterar horas já aprovadas?
Não. update_entry e delete_entry só funcionam sobre registos seus ainda por aprovar. Horas aprovadas alteram-se na Half5.
