Use this agent integration design template to document how one AI agent connects to one business system: which narrow operations it may call, at what depth, under which credential, what data comes back, what happens on retry or failure, and what each call records. One completed template per agent-system pair, approved before any credential is issued.
Why does each integration need its own design?
Most agent incidents in production are not model errors. They are integration errors: a credential with more scope than the job, an endpoint that writes when it should only read, a retry that sends the same instruction twice. The design document is where you catch those before go-live.
The rule underneath is simple. An agent should never hold a capability in a system that it does not hold in its brief. If the agent brief template says the agent drafts refunds at depth 2, the integration must not expose an endpoint that issues them. The design makes that match visible and checkable.
This template sits inside the wider governed agentic operating system, which enforces the bounds at the moment of action. The design is what the operating system enforces against.
How do you complete the template?
Work through the fields with the system owner in the room. They know which operations are dangerous in ways the agent team will not.
- Name operations, not endpoints. "Add note to claim" is an operation. A general-purpose API that can do fifty things is not. The case for narrow, purpose-built operations is made in how to design tools for AI agents.
- Assign a depth to every operation. Reads are depth 1. Anything a person sends is depth 2. Routine writes within bounds are depth 3. Payments and hard-to-undo changes are depth 4.
- Give the agent its own identity. Never reuse a human's login or a shared service account. The audit trail must show the agent acted.
- Strip returned data to what the role needs. If the job never uses date of birth, do not return it.
- Define retry behaviour. Every write carries an idempotency key so a retried call cannot act twice.
- Say what the agent does when the system is down. Usually: stop, tell the customer, and open a case for a person.
The agent integration design template
| Field | Guidance |
|---|---|
| Agent and brief version | Which agent, which version of its brief |
| System and owner | The system and the named person who owns it |
| Purpose | One sentence on why the agent needs this system |
| Operations exposed | Each operation by name, read or write |
| Depth per operation | 1 to 4, matching the brief |
| Operations withheld | Operations the system offers that the agent will never see |
| Credential | Agent identity, scope, rotation period, where it is stored |
| Data returned | Fields included; fields deliberately excluded |
| Provenance class | How facts from this system are stamped (sealed, signed, declared, external) |
| Idempotency | How duplicate calls are detected and ignored |
| Reversibility | For each write, how it is undone and by whom |
| Failure behaviour | What the agent does on timeout, error or partial success |
| Rate limits | Calls per minute and per day |
| Records | What is written to the verdict record for each call |
| Test evidence | Where the integration was tested and the result |
| Approvals | System owner, agent owner, security reviewer |
A worked sample: claims agent to a claims system
Take a regional insurer that wants a first-notice-of-loss agent to work with its claims system.
| Field | Sample entry |
|---|---|
| Agent and brief version | Claims Intake Agent, brief v2.0 |
| System and owner | Claims system; Claims Systems Manager |
| Purpose | Look up claim status and record intake notes |
| Operations exposed | Get claim status (read); add intake note (write); draft document request (write, held) |
| Depth per operation | 1; 3; 2 |
| Operations withheld | Set reserve, change payee, close claim, approve payment |
| Credential | Agent service identity, write limited to notes and drafts, rotated every 30 days |
| Data returned | Claim number, status, policy type, open document list; excludes bank details and medical notes |
| Provenance class | Signed |
| Idempotency | Note carries a request ID; duplicates rejected by the system |
| Reversibility | Notes can be marked void by a claims handler; drafts expire unsent |
| Failure behaviour | On error, tells the customer a handler will follow up and opens a case |
| Rate limits | 60 calls a minute |
| Records | Operation, inputs, result, bound that decided |
| Test evidence | Test environment run on 200 sample claims, no write outside notes |
| Approvals | Signed by all three |
The withheld list is the most useful line. It tells reviewers what the system could do and the agent never will.
What should reviewers check before sign-off?
Compare the operations list to the brief line by line. Any operation without a matching capability is removed. Check that the credential cannot reach a withheld operation even if called directly. If you are designing several integrations at once, step back and read how to design an AI agent architecture for a regulated business, and why roles beat prompts as the basis for agent design.
Questions people ask
Should the agent call our existing API directly?
Only if the API already offers narrow operations with their own permissions. Most general APIs do not, so teams put a thin layer in front that exposes only the approved operations. That layer is also a good place to enforce limits.
Who owns the integration once it is live?
The system owner owns what the system allows; the agent owner owns what the agent asks for. Both sign the design, and both are told when either side changes.
Does a new operation need a new design?
It needs a new version of the design and a matching brief change. Adding a write operation usually means a fresh certification run before it is switched on.