Building agents

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

Pick the right way in

You're buildingUse
An AI agent that decides what to doThe MCP server. The model reads each tool's description and picks what it needs.
Code with fixed steps: a sync job, a webhook handler, a dashboardThe REST API. Same actions, plain HTTP, and safe retries.
A custom agent with your own model callsEither. 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:

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). 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 lists every page with a one-line summary.
  • /llms-full.txt has every guide in one file.
  • Every page is also available as Markdown: add .md to its address.
  • /v1/openapi.json describes the API in OpenAPI 3.1, for code generators.