ADR-0028: Calls to systems we do not own are guarded, signed, keyed and recorded before they are sent
- Status: Accepted
- Date: 2026-11-11
- Scope: core (any product that calls an address a user, a customer or a model supplied, or delivers events to
another party’s system)
Context
The agents platform calls its tenants’ own systems: operations imported from an OpenAPI document, MCP servers, and
webhooks that receive a confirmed action (agents 0009-calls-to-tenant-systems, 0020-actions-end-a-conversation-and-land-in-the-inbox,
0021-a-tools-kind-is-what-it-is-for-not-how-it-is-carried-out). The address of each comes from a person or from
a model, and the call often changes something on the other side (books a time, cancels it). Building it showed the
same needs every time:
- an address that points inward (localhost, a private range, a metadata endpoint), directly or through a redirect;
- a receiver that cannot tell our call from anyone’s, nor which of our users it is acting for;
- a call sent twice — a retry, a resend, a timeout that actually succeeded — doing the thing twice;
- a failed call losing what the user had confirmed;
- an event whose shape changed under a receiver that parses it.
Decision
1. Every address from outside passes an egress guard, on every hop
Before connecting: https only, and every address the host resolves to is public. A redirect is followed only after
its target passes the same check, up to a small number of hops; a response is capped in size and in time. A
guard’s switches for private addresses or plain http exist for tests only. The guard runs before every call,
not when the address is saved: DNS answers change.
2. Every outgoing call is signed, and the signed payload is versioned
The signature is an HMAC over a timestamp, the method, the path and query, the identity we act for, the call’s
idempotency key and a hash of the body, sent as v<N>=<hex> with the timestamp in its own header. The receiver
checks it before trusting anything the request claims, including who the user is. The payload never changes
without a new version; a version never released is replaced, not kept beside the new one.
3. Every call carries an idempotency key, stable for one logical delivery
The key is fresh for a one-off call and the same on every attempt of one delivery (derived from what is delivered:
<record id>:<destination>). Because it is signed, it is also the call’s nonce. Receivers deduplicate on the key,
never on the bytes: a JSON store may reorder an object’s keys, so a resent body can differ byte for byte and be
the same content.
4. The record is written first; delivering is a separate, recorded attempt
What the user confirmed is stored before any delivery starts, in its own transaction, and a failed delivery never
undoes it. Each attempt is kept on the record: when, where, what it sent, its key, the outcome and a reason. A
resend sends the same arguments with the same key, outside a transaction (core 0002-clean-architecture-and-use-cases:
no transaction across a remote call). Only a delivery whose latest attempt failed can be resent; a test record is
delivered nowhere.
5. An event we send whole has a type and a version
When the receiver gets our object rather than its own operation’s arguments (a webhook), the body names its
type and version. Its shape changes only with a new version.
6. A request sent to us again is the same request
The other direction: a client request that may be retried carries an Idempotency-Key; the same key returns the
first request’s result (waiting while it is still being processed), and the same key with a different body is a
conflict, never a second execution.
Consequences
- An address a model found, or a user pasted, cannot reach our network.
- A receiver can trust who is calling and whom for, and can make its side idempotent with one lookup.
- Resending is safe to offer to a user, and automatic retries become a scheduling question, not a correctness one.
- Accepted: two resends at the same moment are not locked against each other; the key makes the duplicate
harmless at a receiver that honours it. - A receiver that ignores the key can still act twice; the integration guide must say to honour it.
Related
- Agents 0009-calls-to-tenant-systems —
EgressGuard,ToolCallSignature(v2), sealed credentials - Agents 0020-actions-end-a-conversation-and-land-in-the-inbox — delivery attempts, resend, the webhook event
- Agents 0021-a-tools-kind-is-what-it-is-for-not-how-it-is-carried-out — HTTP, MCP and WEBHOOK as ways to carry
out one action; an API connected from a link to its documentation - 0024-model-writes-are-proposals-the-user-confirms — what is confirmed before anything is sent