# Building agents

> Patterns for agents and integrations that read and change PlaybookOps safely.

## Pick the right way in

| You're building | Use |
| --- | --- |
| An AI agent that decides what to do | The [MCP server](https://developers.playbookops.ai/mcp). The model reads each tool's description and picks what it needs. |
| Code with fixed steps: a sync job, a webhook handler, a dashboard | The REST API. Same actions, plain HTTP, and [safe retries](https://developers.playbookops.ai/idempotency). |
| A custom agent with your own model calls | Either. MCP SDKs list the tools for you; or describe a few REST calls as your own tools. |

## Give each agent its own key

One key per agent or integration, named after it, with the least access that works:

- **Read-only** for anything that answers questions or reports. It can't change anything, whatever the model decides to do.
- **Full access** only when it must make changes. Over MCP the agent then sees the tools that change things too.

Keys act as the person who made them, so an agent never sees more than its owner. Admins can see each key's traffic under **Admin → API** and revoke it there.

## Ground answers in your knowledge

For questions about how your organization works, have the agent:

1. Call `search_knowledge` with the whole question, not keywords. Search matches meaning.
2. Call `read_document` for the documents that matter, to read beyond the passage.
3. Cite the `url` of each document it used, so people can check.
4. Call `who_knows` to find someone to ask when the documents don't cover it.

A system prompt line that works well:

```text
When asked how we do something, search PlaybookOps knowledge first and answer only from what you find. Link each document you used. If nothing covers it, say so and suggest who to ask using who_knows.
```

## Make changes safely

- **Read before you write.** Call `get_project` for the board's groups and columns before setting values, and `list_people` before assigning someone.
- **Don't repeat changes.** Over REST, send an `Idempotency-Key` with every change ([how](https://developers.playbookops.ai/idempotency)). Over MCP, check whether something exists before creating it again.
- **Handle limits.** On `429`, wait `Retry-After` seconds. On `402`, tell the person their organization is out of AI credits.
- **Let the app notify people.** Changes made through the API behave like changes in the app: assignees are notified and automations run. Your agent doesn't need to send its own messages.

## Docs for models

These docs come in plain text for models and coding agents:

- [`/llms.txt`](https://developers.playbookops.ai/llms.txt) lists every page with a one-line summary.
- [`/llms-full.txt`](https://developers.playbookops.ai/llms-full.txt) has every guide in one file.
- Every page is also available as Markdown: add `.md` to its address.
- [`/v1/openapi.json`](https://developers.playbookops.ai/v1/openapi.json) describes the API in OpenAPI 3.1, for code generators.
