# Agentes de IA

Fonte: https://wire.ia.br/documentation/api/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:

```txt
https://wire.ia.br/documentation/agents/raw.json
```

## Roteiro [#roteiro]

<Steps>
  <Step>
    **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.
  </Step>

  <Step>
    **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.
  </Step>

  <Step>
    **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.
  </Step>

  <Step>
    **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](/api/formato-das-paginas)).
  </Step>

  <Step>
    **Conte o que fez.** No fim, diga à pessoa quais páginas criou, mudou ou mandou para a lixeira, com os títulos.
  </Step>
</Steps>

## Faça [#faça]

* Respeite as permissões. `403` quer 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](/api/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-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](/termos/termos-da-api).

## Instruções de exemplo [#instruções-de-exemplo]

```txt
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 [#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](/api/exemplos).