Sam
Get started
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.

  1. 01

    Before your call

    POST /v1/pre: the run, the step, the model or tool, input tokens and a fingerprint.

  2. YOUR APP

    Run your agent

    Your prompt goes to your chosen model. The reply comes back to your application.

  3. 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.

NOT IN YOUR WAY

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.

With a short timeout and errors ignored, as above, your AI calls run and return as normal if Sam can’t be reached. You lose visibility for that time, but your work carries on.

CHECK THE CONNECTION

Match start to finish.

Use the same run and step for both reports. Check one successful call and one failed call, and see both on the run’s timeline.

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.

Point the reports at an address that doesn’t answer and confirm your application still gets its normal result or error.

See your first finding.

Send the test loop from Connect, or let your feature run, and open the finding: the check, the limit and the run it came from.

START SMALL

One feature.
Your first finding today.

Sign up, create a key and send the two reports. The Connect page walks you through it.

Start a free trial