Reporting doesn’t gate the work.
The SDK is designed to fail open. A reporting failure should not prevent the AI call or replace its result. Telemetry errors are handled locally.
Two calls around yours.
Then keep building.
A start report before your AI call. A finish report after it. Sam receives the measurements that explain behaviour while your prompts and replies stay in your application.
See the integration shapeFirst, tell Sam
what the feature is for.
Describe the job and review the checks Sam proposes. Then connect one feature in a test environment, starting with observe-only authority.
Two asynchronous calls.
One around each side.
Report a start, run your AI call as usual, then report its finish. The reports go to the Sam platform. Your model call follows its existing route, and your prompts and replies stay in your application.
-
01
Before your call
Send the call identity and locally measured input shape asynchronously.
-
YOUR APP
Run your agent
Your prompt goes to your chosen model. The reply comes back to your application.
-
02
After your call
Send timing, outcome and available usage or shape measurements asynchronously.
The integration shapeIllustrative JavaScript
// Illustrative pseudocode, not a published SDK API.
// sendStart / sendEnd enqueue metadata asynchronously.
async function runWithSam(input) {
const callId = crypto.randomUUID();
const started = performance.now();
let status = "error";
// 1. Report the start. Never send input itself.
void sendStart({
callId,
featureId: "nightly-digest",
inputBytes: new TextEncoder().encode(input).length
}).catch(handleTelemetryFailure);
try {
const reply = await yourAgent(input);
status = "ok";
return reply; // Your reply stays in your application.
} finally {
// 2. Report the finish, including failed calls.
void sendEnd({
callId,
status,
durationMs: performance.now() - started
}).catch(handleTelemetryFailure);
}
}
// Handle reporting failures locally; do not throw.
// Do not log or forward prompts, replies or raw errors.
function handleTelemetryFailure() {}This is pseudocode to explain the boundary, not copy-and-paste SDK documentation. The reporting helpers represent non-blocking metadata delivery. Token counts and output-shape fields can be added from local measurements; no prompt or reply belongs in either payload.
Missing data stays visible.
Asynchronous reporting can arrive late or be missing. Sam must distinguish incomplete visibility from a successful, healthy run.
Alongside your call.
Never in front of it.
Not a proxy.
Sam never sits between your application and your model. Your call goes straight to your provider or your own hardware, with your credentials, the way it does today.
No wait before your call.
The start report is sent and forgotten. Sam does its work while your model is generating, so the finish report gets its answer without holding anything up.
If Sam goes quiet, your agents don’t.
If Sam can’t be reached, your AI calls run and return as normal. You lose visibility for that time, and Sam shows the gap, but your work carries on.
Put Sam in software
your customers run.
The inspector SDK will measure each AI call inside your application and send the two reports for you. You see how your AI behaves on your customers’ devices. Your prompts stay yours. The SDK is coming. Until then, send the two reports directly, as shown above.
Measures where the call runs.
Timings, sizes, token counts and shape statistics are computed in your application. A fingerprint lets Sam compare patterns without receiving the text.
Never sends content.
There is no code path that sends a prompt, a reply or conversation context. Only measurements, identifiers and the fingerprint leave your application.
Asks before it watches people.
Consent is built in. On someone else’s device, nothing is sent until that person agrees.
Fails open.
If reporting fails, your AI call still runs and returns its normal result. Telemetry errors are handled inside the SDK, not thrown into your code.
Match start to finish.
Use the same call identity for both reports. Check one successful call and one failed call. A missing finish report must not look like success.
Keep content out.
Inspect both payloads. Include measurements and identifiers; exclude prompts, replies, conversation context and raw errors that could contain content.
Try a reporting failure.
Confirm your application still gets its normal result or error if telemetry delivery fails. Reporting must not replace the application’s outcome.
Confirm the first finding.
Check that Sam can name the feature, show the relevant evidence and identify the owner. Review the finding before expanding the watch.
Sam is in pilot. The example above explains the pattern; package names, installation commands and production SDK documentation are not published here yet.
One feature.
A clear expectation.
Use the onboarding guide to prepare your feature description and work through the first connection.
Get startedRead our privacy promise