Customer systems have their own identifiers, permissions, rate limits, and failure behavior. Put an adapter between the AI workflow and each external system so those details do not become scattered through prompts and tool handlers.
Define a narrow adapter
A ticket adapter might expose read_ticket(actor, ticket_id) and propose_reply(actor, ticket_id, text). Resolve the actor from authenticated server context. Do not allow model arguments to select an arbitrary customer identity.
Normalize records while retaining source IDs and versions. Validate required fields and handle missing or retired records. A successful HTTP response can still contain a business-level error; inspect the response contract.
Classify retries
Reading a record is usually easier to retry than creating a record. For mutations, use an idempotency mechanism or reconcile the result before retrying. A timeout can mean the remote system completed the action but the response was lost.
Respect rate limits, give calls a deadline, and redact sensitive fields in logs. Test against a sandbox before connecting a pilot to live data.
Exercise
Build a fake adapter that can return success, access denied, not found, rate limited, and timeout. Include a timeout after a mutation has already been recorded.
Check: unauthorized users never receive records; a retry cannot duplicate the mutation; the workflow distinguishes unavailable data from permission denial. Document what an operator can do to recover each failure.