# Resource notes for teams and AI agents

> For AI agents: the complete documentation index is at https://buddy.works/llms.txt

Add a note for teammates and instructions for AI agents to artifacts, integrations, environments, sandboxes, targets, variables, and distributions in Buddy.

Resource notes add context to Buddy resources without storing it in the repository, similar to an `AGENTS.md` file associated with a specific artifact, integration, environment, or sandbox. They can describe information that is not visible from the resource name, for example a read-only integration, a broken migration in an artifact version, or an environment that requires manual approval.

Every note has two fields:

- **Note for humans** (`note`) - context for teammates.
- **Note for agents** (`agent_note`) - instructions for AI agents that use the resource.

Pipelines support the same fields - see [Pipeline notes](https://buddy.works/docs/pipelines/introduction/pipeline-notes.md).

> **Warning**
>
> Do not put tokens, passwords, or other secrets in notes. Anyone who can view the resource, and any agent with read access to it, can read them.

## Resources that support notes

| Resource | Dashboard | YAML | REST API |
| :--- | :---: | :---: | :---: |
| Artifacts | Yes | - | Yes |
| Artifact versions | Yes | - | Yes |
| Integrations | Yes | - | Yes |
| Environments | Yes | Yes | Yes |
| Sandboxes | Yes | Yes | Yes |
| Targets | Yes | Yes | Yes |
| Variables | Yes | Yes | Yes |
| Distributions and routes | Yes | Yes | Yes |

## Add a note in the dashboard

Open the resource, expand the menu in the upper-right corner, and select **Add note**. Fill in **Note for humans**, **Note for agents**, or both, and click **Add note**. To change it later, select **Edit note** from the same menu and click **Save changes**.

![Editing the notes of an artifact](https://buddy.works/docs/ai-agents/resource-notes/edit-note-form.png)

For an artifact version, a variable, a distribution, or a route, open its page first. The menus on the lists do not have this option.

Saved notes appear in a panel above the resource tabs. **Note for humans** is expanded, **Note for agents** is collapsed - click it to expand.

![Notes for humans and agents above the artifact tabs](https://buddy.works/docs/ai-agents/resource-notes/notes-panel.png)

## Manage notes in YAML

Environments, sandboxes, targets, variables, distributions, and routes accept `note` and `agent_note` in their YAML definitions:

```yaml
- sandbox: preview-app
  name: Preview App
  os: ubuntu:24.04
  note: Preview of the main branch, rebuilt on every push.
  agent_note: |
    Do not install system packages here.
    Change the boot commands in the YAML definition instead.
  variables:
  - key: API_URL
    value: https://api.example.com
    note: Backend API URL
```

## Manage notes with the CLI

Commands that create or update environments, variables, distributions, routes, artifacts, and artifact versions accept `--note` and `--agent-note`. These options are also available for `bdy sandbox create`, `bdy artifact publish`, `bdy integration update`, and tunnel commands:

```bash
bdy env update production --agent-note "Requires manual approval. Never deploy outside business hours."
bdy artifact version update my-artifact 1.4.0 --agent-note "Broken migration, do not deploy."
```

To clear a note, pass an empty string, for example `--note ""`. To change the notes of an existing sandbox, target, or pipeline, edit its YAML definition.

In JSON output (`--format json`), `get` commands return `note`, `agent_note`, and `parent_notes`. The `parent_notes` field contains notes from parent resources, such as the pipeline or environment, ordered from the closest parent. Retrieving each parent requires an additional API request, so use `--no-parent-notes` to skip them. The `target list`, `variable list`, and `integration list` commands also return notes.

## Manage notes with the REST API

The `note` and `agent_note` fields are part of the request and the response bodies, for example:

- [Update an artifact](https://buddy.works/docs/api/artifacts/update.md)
- [Update an artifact version](https://buddy.works/docs/api/artifacts/versions/update.md)
- [Edit an integration](https://buddy.works/docs/api/integrations/edit.md)
- [Edit an environment](https://buddy.works/docs/api/environment/edit.md)
- [Edit a sandbox](https://buddy.works/docs/api/sandboxes/edit.md)
- [Edit a variable](https://buddy.works/docs/api/variables/edit.md)
- [Update a distribution](https://buddy.works/docs/api/distributions/update.md)

## How AI agents read notes

Through the [Buddy MCP server](https://buddy.works/docs/ai-agents/mcp.md), an agent gets the notes from the `get-*` tools, for example `get-artifact`, `get-integration`, `get-environment`, `get-target`, or `get-distro`. The `list-*` tools do not return notes, so an agent should fetch the resource before it acts on it. An agent that works with the [CLI](#manage-notes-with-the-cli) reads them from `get` commands with `--format json`. A note that is not set is left out of the response.

> **Info**
>
> An `agent_note` does not block anything. To stop an agent from deploying or deleting, use permissions, a read-only integration, or [manual approval](https://buddy.works/docs/pipelines/parameterized-pipelines/manual-approval.md), and explain the rule in the note.

## What to put in notes

- **Integration:** "Read-only token, use for reporting only."
- **Artifact version:** "Broken migration, do not deploy."
- **Environment:** "Requires manual approval before every deployment."
- **Target:** "Shared database server, never run migrations from a sandbox."
- **Sandbox:** who owns it and whether it can be deleted.

## Related documentation

- [Pipeline notes](https://buddy.works/docs/pipelines/introduction/pipeline-notes.md)
- [MCP with Buddy](https://buddy.works/docs/ai-agents/mcp.md)
- [Skills with Buddy](https://buddy.works/docs/ai-agents/skills.md)


---
Original source: https://buddy.works/docs/ai-agents/resource-notes