Paper Agentes de IA
Regras e roteiro para uma IA usar o caderno de alguém com cuidado.
Esta página fala direto com agentes de IA. Se você é uma pessoa configurando um agente, mande para ele o texto do botão Copiar instruções para a IA e o link do mapa:
https://wire.ia.br/documentation/agents/raw.jsonRoteiro
Confirme quem você atende. Chame GET /api/v1/me com Authorization e X-Paper-Account. Se a conta não bater, pare e avise a pessoa.
Veja o que pode. A resposta de /me traz o tipo do token e as permissões. GET /vaults mostra os cofres que você alcança. Se o cofre tem id começando com copia-, você trabalha numa cópia e a pessoa revisa tudo depois.
Leia antes de escrever. Liste as páginas, leia as que importam para o pedido. Guarde a lista em memória durante a tarefa em vez de pedir de novo a cada passo.
Mude o mínimo. Prefira append a reescrever a página inteira. Ao reescrever, preserve o que a pessoa escreveu e o formato dos blocos (veja Formato das páginas).
Conte o que fez. No fim, diga à pessoa quais páginas criou, mudou ou mandou para a lixeira, com os títulos.
Faça
- Respeite as permissões.
403quer dizer não: não tente outro caminho. - Trate páginas protegidas (
423) como fechadas. Não peça a senha à pessoa e não tente adivinhar o conteúdo. - Em
429, pare, espere e volte num ritmo menor. Veja Limites. - Escreva em português claro, como a pessoa escreve. Use os blocos do Paper quando ajudarem: tarefas com
@data, tabelas, quadros. - Crie uma pasta para o que você produzir, se a pessoa não disse onde pôr.
Não faça
- Não use o caderno como memória de longo prazo sua, banco de dados, fila de tarefas ou log de execução.
- Não envie arquivos para hospedar em outro lugar.
- Não consulte em laço para saber se algo mudou. Uma checagem por minuto, no máximo.
- Não copie o conteúdo do caderno para fora da conversa com a pessoa sem ela pedir.
- Não mostre o token em respostas, logs ou arquivos.
- Não apague em massa. Para mais de 10 páginas de uma vez, peça confirmação.
Quebrar essas regras leva ao banimento permanente da conta da pessoa que confiou o token a você. Os termos completos estão em Termos da API.
Instruções de exemplo
Você tem acesso ao meu caderno do Paper pela API pessoal.
Token (envie no cabeçalho Authorization: Bearer): paper_…
Minha conta: 3f2a… (envie também no cabeçalho X-Paper-Account)
Base da API: https://wire.ia.br/api/v1
Leia primeiro o mapa da documentação: https://wire.ia.br/documentation/agents/raw.json
Respeite os limites e os termos de uso da API descritos lá. Use o caderno como caderno, não como banco de dados.Ferramentas para o agente
Se o seu agente aceita ferramentas definidas por você, estas cinco cobrem quase tudo:
| Ferramenta | Pedido |
|---|---|
listar_paginas(cofre) | GET /vaults/{cofre}/pages |
ler_pagina(cofre, id) | GET /vaults/{cofre}/pages/{id}?format=md |
buscar(cofre, texto) | GET /vaults/{cofre}/search?q= |
criar_pagina(cofre, titulo, texto, pasta?) | POST /vaults/{cofre}/pages |
acrescentar(cofre, id, texto) | PATCH /vaults/{cofre}/pages/{id} com append |
Exemplos prontos em Exemplos.