The Client Handover Pack for an AI Agent

You shipped the agent, the demo landed, the invoice cleared — and then the Slack channel went quiet. Three weeks later, someone asks why the invoice-triage agent stopped posting to the finance channel, and nobody can find the credential, the runbook, or the person who last touched the prompt. That is not a bug; it is a handover gap. A practical AI agent handover checklist turns a working build into an asset the client can operate, audit, and change without calling you at 11pm.

This guide describes the client handover pack an agency should be able to defend in an internal audit: six artifacts, a build sequence, a testing ritual, and the edge cases that break handovers most often. It assumes you are delivering an agent that runs against real systems — CRM records, ticketing, email, internal APIs — and that the client will own it after you leave.

What goes in an AI agent handover pack?

Six artifacts, each with a named human owner on the client side. Ownership is the point: a document nobody owns is a document nobody reads.

Everything else — architecture diagrams, eval results, cost notes — is supporting material. Useful, but not what keeps the system alive.

Prerequisites before writing the handover pack

• A named client owner. One person accountable for the agent, even if a team operates it. If the answer is 'the IT department', keep asking.
• Production access, not staging access. The pack must describe the environment that actually runs.
• A secret store you can point at. Anything with per-item access control and an audit trail. If the client has none, that is a prerequisite to fix, not a line item to skip.
• Two hours of client time. One hour to walk through the pack, one hour for them to drive while you watch.
• A clean run and a failed run to reference. Both go into the pack as worked examples, so pick recent ones.

Build the pack in eight steps

1. Inventory the agents, runtimes, and dependencies

List every agent process, where it executes (a developer laptop, a client VM, a container host, a managed runtime), what triggers it (cron, webhook, chat message, manual), and what it writes to. Include the boring parts: the queue it consumes, the database it reads, the shared mailbox it polls. Note the model provider and the exact model identifier currently pinned in configuration.

This inventory is also your build manifest. If you manage agents across local machines, remote servers, and Docker containers, keep the inventory in the same place you manage them. OPAYA's agent managers surface is built around that idea — one workspace showing what is installed and connected where — which turns 'what exactly did we hand over' into a screenshot instead of an afternoon of archaeology.

2. Write the access matrix with a named credential owner

One row per credential, no exceptions. Columns that earn their keep:

• System and environment (for example, CRM, production)
• Credential type (OAuth app, service account, API key, webhook signing secret)
• Scope actually granted — not 'full access' if the agent only reads contacts
• Named human owner at the client, plus a backup
• Where the secret lives (secret store path, never the value)
• Rotation cadence and last rotation date
• What breaks if the credential is revoked

Two rules make this artifact trustworthy. First, never put a secret value in the pack — put a pointer and an access procedure. Second, every credential should be issued to a client-owned identity, not a personal account at your agency. When the engagement ends, your staff should lose access without breaking the agent.

3. Write one page per workflow, not per agent

Clients think in workflows — 'the invoice triage', 'the lead enrichment' — not in agent architecture. Each page should fit on a screen and contain: purpose in one sentence; trigger; inputs; the numbered steps the agent performs; expected output and where it is written; how to run it manually; how to pause it safely; how to tell it worked; who to call when it did not; and the runtime and token spend per run that you measured during acceptance testing.

Resist the urge to add a second page. If the workflow needs more than one, either split the workflow or move detail into an appendix the runbook links to.

4. Document known limits and failure modes honestly

This is the section agencies skip and clients need most. Write down what the agent will not do, and what happens when the world changes underneath it. Typical entries: model deprecations and the review date you set; provider rate limits and how the agent backs off; context limits on long threads; tool schema changes when a vendor updates an API; OAuth refresh failures on dormant accounts; ambiguous inputs that produce a plausible but wrong classification; partial success where a record is written but the notification is not sent.

Format each entry as symptom, likely cause, first action, escalation. 'Agent stops posting at 02:00' is not useful. 'No posts after 02:00 — check whether the refresh token expired, then re-authorise from the admin console' is.

5. Say exactly where the logs live

There are usually three layers, and clients need all three: the agent runtime log (what the process did), tool and API calls (what left your network and what came back), and model request metadata (which model, token counts, latency, correlation ID). Document retention windows per layer, the query or dashboard URL, and the fields required to pivot between them.

Then write two worked traces: one successful run and one failure, each with the run ID, the timestamp, and the log lines that prove the outcome. Nothing builds client confidence faster than watching their own engineer follow a trace you wrote.

6. Define the change request process

After handover, prompts, tools, and scopes will change. Decide now how. A workable minimum: a single intake form; a named approver on the client side; a rule that scope changes require the credential owner's sign-off; version control for prompts and configuration; a small regression set of test inputs that must pass before any prompt change reaches production; and a short record of what changed, why, and who approved it.

Be explicit about the line between a change and a fix. 'The model started returning a different JSON shape' is a fix inside your support window. 'We want it to also handle refunds' is a change request with new scope and a new estimate.

7. Agree the support window in writing

Specify dates, hours, the channel (a shared inbox beats a personal phone number), response targets by severity, and what is excluded. Typical exclusions: upstream vendor outages, changes the client made without telling you, new workflows, and anything requiring new credentials. Give the window an expiry date and describe what happens afterwards — a retainer, an hourly rate, or best-effort with no response target.

Also name the handover of last resort: if your lead engineer leaves, who at the agency takes over? Clients ask this more often than agencies expect.

8. Run the handover session as a test, not a presentation

Walk the pack for fifteen minutes, then hand over the keyboard. The client's engineer should pause the agent, restart it, find a run in the logs, and revoke and replace a test credential while you watch without intervening. Whatever they cannot do, fix before you invoice the final milestone.

Client handover test checklist: what they must do without you

1. Locate the inventory and name every running agent and its host.
2. Find the credential for the primary integration, then trace it to the named owner and rotation date.
3. Run one workflow manually using the runbook alone.
4. Pause the agent, confirm no partial writes occur, then resume it.
5. Trace one successful and one failed run through all three log layers.
6. Simulate an auth failure by revoking a test credential, then follow the documented recovery.
7. Edit a prompt in a staging copy, run the regression set, and promote it.
8. Raise, approve, and close a low-risk change request as a drill.
9. Restore configuration on a clean machine or container and confirm the agent starts.
10. Confirm they can reach you through the agreed channel, and that they know when the window ends.

If any item fails, it is not a documentation problem — it is a delivery problem. Fix the system, then update the page.

Edge cases that break AI agent handovers

• No secret manager at the client. Do not fall back to a shared spreadsheet. Stand up a minimal store, or scope credentials down to the smallest useful permission and record the residual risk in writing.
• Personal API keys. Agents quietly running on a departed employee's key are the most common handover time bomb. Reissue to a service identity before the final walkthrough.
• Multi-tenant deployments. One agent serving several client organisations needs per-tenant credential separation and a documented data boundary. Do not hand over a shared key with a comment that says 'filter by org'.
• Write access to production systems. If the agent can create, refund, or delete, add an approval step or a dry-run flag and put it in the runbook.
• Model or API deprecation mid-window. Record a review date and a named owner for the model identifier in configuration.
• Egress restrictions. Corporate networks block outbound calls more often than agencies assume. Test from the client's network, not yours.
• The agent runs on someone's laptop. That is a support liability. Move it to a host the client controls, or state explicitly that the laptop must stay awake and who owns it.
• Handover during an incident. Freeze changes, hand over the incident first, and defer the pack. A runbook written mid-outage is fiction.
• Agency staff turnover. Put two names on the agency side, and store the pack in the client's systems rather than only in yours.

Where a workspace such as OPAYA helps

Handover pain is usually inventory pain: nobody is certain which machine runs which agent with which connection. OPAYA is a desktop workspace for installing, connecting, and managing AI agents on local computers, remote servers, and Docker, so the runtime map you need for the pack is close to the map you already work from. The features overview covers the management surface; check current documentation for the specifics that apply to your stack, and treat the client's secret manager — not OPAYA — as the system of record for credentials.

Worth saying plainly: tooling reduces the effort of producing an accurate pack, but it does not decide who owns a credential or how long you support the system. Those are commercial decisions you write down.

FAQ: AI agent handover checklist

What is an AI agent handover checklist?

It is the pack of operating artifacts a client needs to run, audit, pause, and change an agent after delivery. In this guide, that means six core artifacts: an access matrix, one-page runbooks, known limits and failure modes, a log map, a change request process, and a support window.

How long should an AI agent handover pack take to produce?

For a single workflow with two or three integrations, budget a day of engineering time plus the client session. Multi-workflow systems with production write access take longer, because the access matrix and failure-mode sections grow fastest.

Should the pack be a PDF, a wiki, or a repo?

Whatever the client will actually maintain, with credentials kept elsewhere. A repo of markdown files with version history is usually the best compromise: engineers can diff changes, and the client can fork it into their own organisation.

Who owns the credentials at the end?

The client. Issue credentials to client-owned identities, name a human owner for each one, and make sure your agency's access can be revoked without stopping the agent.

Do we need to hand over prompts and evals?

Yes, if the client is going to change behaviour. Prompts without a regression set are a liability; hand over both, plus the rule that nothing ships unless the set passes.

What if the client has no engineers?

Simplify the pack, not the truth. Keep the access matrix and failure modes, replace technical runbooks with a clear 'call this person' section, and price a support retainer — then state what happens when it ends.

How is this different from a normal software handover?

Non-determinism. Traditional handovers assume the same input produces the same output. An agent's behaviour shifts with model updates and upstream data, so the pack needs failure modes, a pinned model identifier, and a change process that includes re-testing behaviour.

Your next action

Pick the workflow with the highest business impact and write its one-page runbook today: trigger, steps, expected output, how to pause, how to verify. Then schedule the 45-minute session where the client's engineer runs it without your hands on the keyboard. The other five artifacts get easier once that first page exists.

If you are standardising this across client engagements, OPAYA gives your team one workspace to install, connect, and manage agents across local machines, remote servers, and Docker, so the inventory in your handover pack reflects reality on the day you sign it over. Start with the agent managers overview and see whether it fits how your agency delivers.