# AI agents

Source: https://wire.ia.br/documentation/en/api/agentes-de-ia

> Rules and a script for an AI to use someone's notebook with care.



This page speaks directly to AI agents. If you're a person setting up an agent, send it the text of the **Copy instructions for the AI** button and the link to the map:

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

## Script [#script]

<Steps>
  <Step>
    **Confirm who you serve.** Call `GET /api/v1/me` with `Authorization` and `X-Paper-Account`. If the account doesn't match, stop and tell the person.
  </Step>

  <Step>
    **See what you can do.** The `/me` response brings the token type and the permissions. `GET /vaults` shows the vaults you reach. If the vault id starts with `copia-`, you work on a copy and the person reviews everything afterward.
  </Step>

  <Step>
    **Read before writing.** List the pages, read the ones that matter for the request. Keep the list in memory during the task instead of asking again at every step.
  </Step>

  <Step>
    **Change the minimum.** Prefer `append` over rewriting the whole page. When rewriting, preserve what the person wrote and the format of the blocks (see [Page format](/en/api/formato-das-paginas)).
  </Step>

  <Step>
    **Say what you did.** At the end, tell the person which pages you created, changed or sent to the trash, with the titles.
  </Step>
</Steps>

## Do [#do]

* Respect the permissions. `403` means no: don't try another route.
* Treat protected pages (`423`) as closed. Don't ask the person for the password and don't try to guess the content.
* On `429`, stop, wait and come back at a lower pace. See [Limits](/en/api/limites).
* Write in clear language, the way the person writes. Use Paper's blocks when they help: tasks with `@date`, tables, boards.
* Create a folder for what you produce, if the person didn't say where to put it.
* Send `Accept-Language` with the person's language, so error messages come in a language they read.

## Don't [#dont]

* Don't use the notebook as your own long-term memory, a database, a task queue or an execution log.
* Don't upload files to be hosted somewhere else.
* Don't poll in a loop to see if something changed. One check per minute, at most.
* Don't copy the notebook's content out of the conversation with the person unless they ask.
* Don't show the token in answers, logs or files.
* Don't delete in bulk. For more than 10 pages at once, ask for confirmation.

Breaking these rules leads to the permanent ban of the account of the person who trusted the token to you. The full terms are in [API terms](/en/termos/termos-da-api).

## Sample instructions [#sample-instructions]

```txt
You have access to my Paper notebook through the personal API.
Token (send in the header Authorization: Bearer): paper_…
My account: 3f2a… (also send in the header X-Paper-Account)
API base: https://wire.ia.br/api/v1
Read the documentation map first: https://wire.ia.br/documentation/agents/raw.json
Respect the limits and the API terms of use described there. Use the notebook as a notebook, not as a database.
```

## Tools for the agent [#tools-for-the-agent]

If your agent accepts tools you define, these five cover almost everything:

| Tool                                       | Request                                          |
| ------------------------------------------ | ------------------------------------------------ |
| `list_pages(vault)`                        | `GET /vaults/{vault}/pages`                      |
| `read_page(vault, id)`                     | `GET /vaults/{vault}/pages/{id}?format=md`       |
| `search(vault, text)`                      | `GET /vaults/{vault}/search?q=`                  |
| `create_page(vault, title, text, folder?)` | `POST /vaults/{vault}/pages`                     |
| `append(vault, id, text)`                  | `PATCH /vaults/{vault}/pages/{id}` with `append` |

Ready-made examples in [Examples](/en/api/exemplos).