Cloud Concepts

JamJet Cloud follows one through-line: you observe what your agents do, enforce policy on it, and prove it. You observe with spans, traces, and costs. You enforce with policies, budgets, and cost controls. You prove with an audit trail and a readiness view. This page is a one-page tour of the primitives that make that loop work. Each section links to deeper documentation.

Observe

Span

A span is a single unit of observed work, typically one LLM call. Spans carry:

• The model, the prompt, the response (full payloads, opt-in via capture_io=True)
• The agent that produced it
• The user context, environment, release version
• Token counts, latency, cost in USD
• Any policy decisions or approvals that applied

You don't create spans manually. The SDK creates one per wrapped LLM call.

→ Spans & Traces

Agent

An agent is a named identity. Spans are tagged with the agent that produced them. You can have a single default agent or many: researcher, writer-bot, code-reviewer. The dashboard renders agents as nodes in a network graph.

import { agent, withAgent } from '@jamjet/cloud'

const researcher = agent('researcher', { description: 'reads + summarises' })

await withAgent(researcher, async () => {
  // every span emitted here is tagged researcher
  await openai.chat.completions.create(/* ... */)
})

→ Agents

Cost finding

A cost finding is a detected waste pattern, surfaced from your real spans on the Optimize surface. Examples include a cacheable prompt prefix you re-send on every call, an oversized model doing work a cheaper one could do, or context bloat inflating your token count. Each finding is grounded in observed behavior, not a heuristic guess about a config you might be running.

→ Optimize

Enforce

Policy

A policy is a rule that controls which tools an LLM can call. Policies match by glob.

import { policy } from '@jamjet/cloud'

policy('block', 'wire_*')                  // block any tool starting with wire_
policy('require_approval', 'send_email')   // evaluated, but does not gate yet

Policies enforce both pre-call (filter the tool list before sending to the LLM) and post-decision (re-check tool calls in the response). Blocked tools are recorded in the span; require_approval matches are not.

→ Policies

Apply / enforce

To apply a cost finding is to turn it into a live policy in one click, instead of filing a ticket and waiting. A cacheable-prefix finding becomes a cache_inject policy; a context-bloat finding becomes a compaction policy. The enforcement then runs against every matching call going forward, and you watch its effect on the Savings surface.

→ Optimize

Tool-result compaction

Tool-result compaction is a policy that trims oversized tool results before the model call, cutting the tokens the model has to read. It targets the case where a tool returns far more text than the model needs, so you pay for context the answer never uses. The tokens saved are recorded on the span.

→ Savings

Budget

A budget is a cost ceiling. JamJet pre-checks every call against it and throws JamjetBudgetExceeded if the call would push you over.

import { budget } from '@jamjet/cloud'

budget(50)   // $50 ceiling for this project

The pre-check uses an estimated cost from the prompt token count; actual cost is recorded post-call.

→ Budgets

Recovered spend (Savings)

Recovered spend is the dollars enforcement actually saved, measured from real behavior rather than projected from a model. When an applied policy compacts a tool result or injects a cache hit, the tokens it removed translate into a USD figure on the Savings surface. This is the bottom line of the Enforce stage: proof that a finding you applied is paying off.

→ Savings

Prove

Approval

An approval is a human-in-the-loop gate. requireApproval('production_deploy') blocks until a human approves or rejects in the dashboard.

import { requireApproval } from '@jamjet/cloud'

const approvalId = await requireApproval('production_deploy', {
  context: { service: 'auth-api', version: '2.3.1' },
  timeoutMs: 600_000,   // 10 minutes
})
// proceeds only if approved; throws JamjetApprovalRejected on reject

→ Approvals

Next steps