SAM FROM OPS / INTEGRATION
Two calls around yours.
Then keep building.
A start report before each 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
First, a key
for the feature.
Create a key for one AI feature in the dashboard and say what it’s for. The Connect page
gives you working snippets in curl, Node and Python with the key filled in, and sends a
test event and a test loop so you see Sam work before you change any code.
See the first steps
Two small reports.
One on each side.
Report a start, run your AI call as usual, then report its finish. The reports go to the
Sam API. Your model call follows its existing route, and your prompts and replies stay
in your application.
-
01
Before your call
POST /v1/pre: the run, the step, the model or tool, input tokens and a fingerprint.
-
YOUR APP
Run your agent
Your prompt goes to your chosen model. The reply comes back to your application.
-
02
After your call
POST /v1/post: the outcome, output tokens and timing. Sam answers with a verdict.
Around one step of a runJavaScript
// Node 18+, no packages. Your key is on the dashboard's Connect page.
const SAM = "https://api.samfromops.com";
const KEY = process.env.SAM_KEY;
// Reporting must never break or slow your call: short timeout, errors ignored.
const report = (phase, body) =>
fetch(`${SAM}/v1/${phase}`, {
method: "POST",
headers: { authorization: `Bearer ${KEY}`, "content-type": "application/json" },
body: JSON.stringify(body),
signal: AbortSignal.timeout(2000),
}).then((r) => r.json()).catch(() => null);
// One step of a run: run is your run's ID, seq counts its steps from 0.
async function step(run, seq, model, input) {
// 1. Before the call: what's about to run. Never the input itself.
void report("pre", { execution_id: run, seq, model,
input_tokens: countTokens(input), fingerprint: shapeOf(input) });
const started = Date.now();
let status = "error", reply;
try {
reply = await callYourModel(model, input); // straight to your provider, as today
status = "ok";
return reply;
} finally {
// 2. After the call: how it went. Sam answers with a verdict.
const answer = await report("post", { execution_id: run, seq, status,
output_tokens: reply?.usage?.output_tokens, latency_ms: Date.now() - started });
if (answer?.verdict === "halt") stopRun(run); // only once you switch halting on
}
}
countTokens, shapeOf, callYourModel and
stopRun are yours. The fingerprint is a one-way hash your code computes of
the call’s shape, such as its template and tool, so Sam can tell when calls repeat
without seeing them. Every request carries your key as a Bearer token.
What you can send.
execution_id (required) and seq; model or tool; input_tokens, output_tokens, latency_ms; status and error_code; fingerprint; parent_execution_id for a run started by another. Measurements and identifiers only.
What comes back.
continue, or a finding: observe while Sam is only watching, halt once you switch halting on. A halt arrives on the run’s next call; your code decides what to do with it.
A start with no finish.
If a finish report never comes, the run shows up as stalled on Activity after ten minutes, rather than passing for a success.