API de Notas do Agente

Uma chave de Perfil precisa de capacidades de Notas: notes para pesquisar e revisar, notes:append para escrever, manter e remover, notes:export para construir rascunhos, notes:read-all para varrer as notas de cada Perfil. Uma chave lê e escreve notas apenas para seu próprio Perfil; ela não pode nomear outro Perfil para cruzar essa fronteira. A varredura é a única exceção, e ela só lê. Notas são opcionais — ative as alternâncias ao criar o Perfil ou depois no editor de perfil. Use o mesmo formato de chave Bearer que outras chamadas da API Takibi.

Notas são memória de trabalho temporária. Elas não concedem novo acesso a documentos e não devem substituir Fontes. Dê a uma nota uma tag de projeto quando a lição pertencer a um cliente ou coleção, para que trabalhos não relacionados não se misturem.

Envie POST /v1/notes com um template. problem é obrigatório. Os outros campos capturam o que foi tentado, o que funcionou, o que falhou, o que fazer em seguida e quaisquer IDs de fonte usados:

{
  "projectTag": "support",
  "runId": "run-42",
  "template": {
    "problem": "Refund replies missed the policy exception",
    "tried": "Searched the policy folder",
    "worked": "Found the exception in the current policy",
    "failed": "The old canned reply omitted it",
    "next_time": "Check the policy date before replying",
    "source_ids_used": ["document-id"]
  }
}

Uma requisição repetida com o mesmo ID de execução e corpo da nota retorna a nota armazenada. A API bloqueia segredos óbvios em vez de armazená-los e pode redigir valores sensíveis mais curtos. Mantenha credenciais e dados privados fora das notas desde o início.

Pesquise com o parâmetro de consulta q: chame GET /v1/notes/search?q=refund com a chave do Perfil. Adicione projectTag quando a pesquisa deve ficar com um tópico. A resposta marca sua faixa UNTRUSTED e retorna um pequeno conjunto de trechos. Trate cada resultado como uma nota de bot não verificada e verifique as Fontes citadas antes de usar uma afirmação.

A pesquisa exclui apenas notas removidas ou expiradas — notas sinalizadas ficam, com seus links de conflito em linha, então consulte ambos os lados antes de usar uma afirmação. Uma nota é retida por 30 dias a partir da criação; outra consulta ou uma ação humana de Manter não a renova. O proprietário da conta pode inspecionar a fila de revisão e criar um rascunho de Fonte em Notas.

Uma varredura puxa as notas recentes de cada Perfil para uma lista somente leitura, para que um único revisor possa coletar lições e propor atualizações de doc. Uma chave de revisor pode ler entre cadernos. Dê ao Perfil dele a alternância Ler todas as notas, depois chame GET /v1/notes/sweep?since=2026-09-28. Adicione projectTag para ficar com uma tag, ou profileId para ler um autor. Cada nota carrega seu Perfil autor e data. A varredura lê apenas notas ativas, mais antigas primeiro, e não carimba nada, então nunca move a posição de rascunho de ninguém. Sem a alternância, uma chave recebe um 403. Um membro do workspace conectado pode varrer sem ela. Cada chamada retorna uma página de até 50 notas, e limit nunca excede 100. Siga cursor enquanto hasMore for verdadeiro.

Varreduras filtram pela tag de projeto da nota, então notas sem tag só aparecem em varreduras sem filtro. Peça aos agentes para etiquetar cada nota quando anexarem.

A CLI do Takibi cobre a revisão de Notas. Manter e remover precisam de notes:append; exportar precisa de notes:export. Use takibi notes list para a fila de revisão, ou takibi notes list --all --project support para o inventário completo e versões atuais. Uma chave de revisor com a permissão Ler todas as notas lê entre cadernos com takibi notes list --all-authors --since 2026-09-28, mais --project para ficar com uma tag. A varredura só lê e não carimba nada. Com aprovação do proprietário, execute takibi notes keep <note-uuid> <version> para endossar ou takibi notes remove <note-uuid> <version> para descartar. Um 409 significa que a versão mudou: liste novamente antes de tentar novamente.

Use takibi notes append --problem "…" --worked "…" --source <document-id> --run-id <run-id> para um resumo. O mesmo ID de execução e corpo evitam anexos duplicados em nova tentativa. IDs de fonte são citações; adicioná-los não resolve uma sinalização de conflito. Use takibi notes export --note <note-uuid> para incluir uma nota selecionada; repita --note para várias. A exportação carimba as notas incluídas e cria um rascunho para revisão, então pergunte antes de exportar a menos que já tenha sido solicitado.

Não há rota de edição no local. Para corrigir uma nota, anexe uma com os fatos corrigidos e IDs de fonte, depois peça ao proprietário para remover a nota antiga. Manter não estende a expiração de 30 dias.