Agent Integration Playbook

A free, vendor-neutral reference on giving AI agents access to real systems — mailboxes, repositories, wikis, databases, and third-party tool servers — without handing over more than the job needs. 18 guides, no gate, no signup.

It is written for engineers shipping agents into production at companies that have to answer who did what, on whose behalf, and with what permission. If you are prototyping against your own API key on your own laptop, most of this is premature. If a real user is about to click Allow on a consent screen, or an agent is about to hold a credential that outlives the request, it is not.

Every guide is one path, start to finish: what breaks without the control, runnable code, a decision table of the options genuinely on the table, a checklist you can paste into a pull request, and the failure modes with the symptom first. External claims link the vendor's own page, an RFC, or a standards document rather than a secondary source that restates them, because scope strings and error codes go stale and blog posts do not get corrected. Where something could not be confirmed against a primary source, the guide says so in place instead of guessing.

The three pillars

The library splits three ways, and the split is by when you need the answer rather than by topic. Connect is before the grant exists. Governis the policy layer that stops you re-deciding the same thing per provider.Fail is after it is live and something is wrong.

The same subject appears in all three and means something different each time. Scope selection is a per-provider table in Connect, a repeatable method in Govern, and a diagnostic you run against an existing grant in Fail. Credentials are an OAuth lifecycle in Connect, a vaulting and rotation problem in Govern, and a leak path in Fail. Pick the pillar that matches where you are standing, not the one whose name matches the noun.

Where to start

Each pillar has a cornerstone guide that carries the whole argument. Those three are the pages worth reading whole; the topic guides underneath them are reference material, so read the one you need and skip the rest.

Nothing granted yet. Start withAI Agent Access: Service Account vs Per-User OAuth, which puts the four ways an agent gets access against one integration and says what each costs, then read the guide for your provider.
Several integrations, same decisions repeating. Start withAI Agent Identity and Permissions: The Four-Axis Model. If you are choosing scopes provider by provider and re-arguing the same points, the decision has moved up a level.
Something is already live. Start withHow Agent Integrations Fail: Six Modes and a Runbook, which sorts the failures by class and tells you which one you are looking at from the symptom.

Connect

Connect answers the question you have before the grant exists: which permission does this agent actually need against this provider, how does it get one, and what does the provider hand over that you did not ask for. One guide per system, each with the real scope names and the consent flow as it actually behaves.

AI Agent Access: Service Account vs Per-User OAuth (cornerstone) — Four ways an agent gets access to a system — shared key, per-user OAuth, service identity, brokered — compared on attribution, blast radius, and cost.
Give an AI Agent Safe Access to Your Postgres Database — Give an agent a dedicated Postgres role, row-level security keyed to the acting user, statement timeouts, and parameterized tools instead of raw SQL.
AI Agent Access to Google Drive and Notion: Grant Boundaries — Pick drive.file over the restricted Drive scopes, put the Picker in the grant loop, and understand why one Notion share hands over a whole page subtree.
Per-User Credentials in LangChain, CrewAI, OpenAI Agents SDK — One tool built three times in LangChain, CrewAI, and the OpenAI Agents SDK, with the per-user credential resolved at call time rather than at import.
Give an AI Agent GitHub Access with a GitHub App — Use a GitHub App installation token instead of a PAT: sign the JWT, scope it to named repositories, open a pull request, and revoke it when the run ends.
Connect an AI Agent to Gmail: OAuth Scopes That Work — Pick the narrowest Gmail scope, run the PKCE consent flow, refresh tokens correctly, and avoid the seven-day expiry that breaks Testing-status apps.
Securing an MCP Server: Authorization and Tool Scope — Where MCP authentication really sits, how to authorize per tool and per argument, and why a server that lets the model choose the target is a confused deputy.
Slack Bot Scopes and Security for an AI Agent — Which Slack bot scopes an agent needs, how to verify the request signature, Socket Mode versus a request URL, and the rate limits that throttle reads.

Govern

Govern is the same material one level up, where the answer stops being per-provider. An agent needs an identity that is neither a person nor a service account, permissions decided per call rather than per grant, credentials it never holds, and a record naming both principals. These are the decisions you make once and apply everywhere.

AI Agent Identity and Permissions: The Four-Axis Model (cornerstone) — An AI agent is its own kind of principal. Model it as agent, user, resource and action, decide at call time, and prove revocation works one cell at a time.
AI Agent Audit Log: Schema, Immutability, Retention — What belongs in an AI agent audit log, field by field: both principals, the policy decision, an append-only store, redaction, and how long to keep it.
AI Agent Credential Management: Issue, Rotate, Revoke — Why an environment variable cannot express per-user access, how to issue a short-lived credential per request, and how to rotate with no downtime.
Agent Delegation vs Impersonation: On-Behalf-Of Flows — Acting for a user is not acting as one. How to run an on-behalf-of token exchange, intersect agent and user permissions, and audit both principals.
OAuth Scopes for AI Agents: A Least-Privilege Method — Enumerate an agent's actions from its tool definitions, map each to the narrowest provider scope, remove the rest, and report unused scopes monthly.
OAuth Flows for AI Agents: The Three Grants That Matter — The three OAuth grants an AI agent actually needs, why RFC 8693 token exchange is the one most teams skip, and how to scope a downstream token down.

Fail

Fail reads the same subject backwards, from the incident. Each guide starts with a symptom you can observe — a token in a trace, a rate limit you did not know you shared, a grant nobody can justify — and works back to the cause and the containment. Read these when something is already live.

How Agent Integrations Fail: Six Modes and a Runbook (cornerstone) — The six ways agent integrations fail, why none of them page you, and the incident order that works: stop the agent, revoke, scope the reach, then rotate.
Over-Scoped OAuth: Audit and Narrow Agent Scopes — An over-scoped agent throws no errors. Diff the scopes you granted against the ones it actually called, then narrow the grant without stranding users.
Runaway Agent Loops, Rate Limits, and Run Budgets — Why agent loops run away, how retries multiply across layers, and the run budgets, jittered backoff, breakers and idempotency keys that actually stop it.
How AI Agents Leak API Keys, and How to Stop It — How an API key in an agent's context escapes into traces, logs, model output and injected requests, and how a credential broker closes the whole class.

The code

Every non-trivial code path in the library has a runnable file behind it, kept in the repository under examples/ and referenced from the guide by path. The examples are checked on every commit: they compile, their imports resolve, and anything touching the Agentic Fabriq SDK is validated against the published surface, so a sample cannot drift into calling something that does not exist. Prose is CC BY 4.0 and code is Apache-2.0, so you can lift either.

Corrections are the most useful contribution. If a scope name changed, a quota moved, or a guide states more than its cited page states, open an issue or a pull request onthe repository. The library is maintained by Agentic Fabriq, which builds a control layer for agent identity, permissions, and audit — every guide teaches the do-it-yourself path first and in full, and says what it costs.