JamJet
Write the safety policy once. Run it everywhere your agents can act.
JamJet sits underneath your Python agent — Claude Code, OpenAI Agents SDK, MCP clients, LangChain, CrewAI, ADK, custom code — and enforces what prompts cannot:
- 🛡️ Block unsafe tool calls at runtime (database deletes, payments, file writes)
- ✋ Pause for human approval on risky actions, durably
- 💸 Cap cost per agent, per run, per project
- 📒 Record an audit trail of every decision, with approvals signed and hash-chained
- ⏪ Replay or resume crashed runs from the last checkpoint
Keep your agent framework. Add JamJet where tool calls need control.
See it in 60 seconds
pip install jamjet
jamjet demo unsafe-tool-call
No API key. No Docker. No cloud account. The model is mocked; the policy check is the SDK's own evaluator. The demos run in process and do not start the runtime. Three more demos run the same way:
jamjet demo approval # pause-for-approval flow
jamjet demo budget-cap # $0.05 cost cap
jamjet demo mcp-tool-policy # MCP-shaped policy
The rest of this README is the Python authoring guide — workflows, durability shims, MCP/A2A integration, and the hosted control plane. For the full positioning + cross-language adapters (Claude Code hook, MCP shim, OpenAI guardrail, TypeScript SDK, CLI), see the main repo README.
What you get in the Python package
jamjet demo <scenario>— runnable enforcement demos with no setup- Policy as code — YAML beside your workflow OR
jamjet.cloud.policy(...)in Python @durablekeeps a tool call that completed from running again after a crash or restart, with shims for LangChain, CrewAI, ADK, OpenAI Agents SDK, Anthropic Agent SDKjamjet.cloud— optional two-line install for the hosted control plane (free tier: 5K traces/mo, single project)jamjet.integrations.openai_guardrail— drop-in guardrail for the OpenAI Agents SDK that runs the samepolicy.yaml- The runtime's MCP server (
/mcp) starts, inspects and approves runs, andjamjet mcp connectlists any MCP server's tools
Quick Start
Requirements: Python 3.11 or newer (the memory extra, which adds Engram, needs 3.12+)
# In-process runs, including the scripted model (no API key needed)
pip install jamjet
# `jamjet dev` and durable runs also need the sidecar
pip install 'jamjet[sidecar]'
# Real providers need the model client too
pip install 'jamjet[model,sidecar]'
# Option A: scaffold a new project
jamjet init my-agent-project
cd my-agent-project
# Option B: add JamJet to an existing project (works like git init)
cd my-existing-project
jamjet init
# Start the local dev stack (SQLite, no server setup needed).
# The starter workflow calls claude-haiku-4-5, so export a key first.
export ANTHROPIC_API_KEY=sk-ant-...
jamjet dev
jamjet dev uses the jamjet-server on your PATH, or downloads the one
published with the latest SDK release. The
Quickstart
says which runtime it needs and how to build one.
In another terminal, from the project directory:
# Check, then run, the workflow the template created (it reads `query`)
jamjet validate workflow.yaml
jamjet run workflow.yaml --input '{"query": "What is JamJet?"}'
Run an agent with no API key
Set model="scripted/<path to a YAML file>" and each model call is answered from
the file. Only the model is scripted. Policy, approval, budget and durability are
the real ones.
# scripts/book.yaml: turn N answers the agent's Nth model call
turns:
- tool_calls:
- name: search_venues
arguments: {city: Lisbon, date: "2026-12-11"}
- tool_calls:
- name: check_dates
arguments: {venue: Casa do Rio}
- tool_calls:
- name: pay_deposit
arguments: {venue: Casa do Rio, amount: 500}
- content: "Booked Casa do Rio in Lisbon for 11 December. The 500 deposit is paid."
# venue_tools.py: plain `def` functions work with @tool
import json
from jamjet import tool
VENUES = {
"lisbon": [
{"venue": "Casa do Rio", "capacity": 120, "price_per_day": 2400},
{"venue": "Armazem 16", "capacity": 300, "price_per_day": 5200},
],
}
FREE_DATES = {
"Casa do Rio": ["2026-12-04", "2026-12-11"],
"Armazem 16": ["2026-12-18"],
}
@tool
def search_venues(city: str, date: str) -> str:
"""Find event venues in a city that are free on a date (YYYY-MM-DD)."""
venues = VENUES.get(city.strip().lower(), [])
return json.dumps([v for v in venues if date in FREE_DATES[v["venue"]]])
@tool
def check_dates(venue: str) -> str:
"""List the free dates for one venue."""
return json.dumps(FREE_DATES.get(venue, []))
@tool
def pay_deposit(venue: str, amount: float) -> str:
"""Pay a booking deposit for a venue. In production this moves real money."""
return f"Deposit of {amount} paid for {venue}."
# book.py
import asyncio
from jamjet import Agent
from venue_tools import search_venues, check_dates, pay_deposit
agent = Agent(
"venue-booker",
model="scripted/scripts/book.yaml",
tools=[search_venues, check_dates, pay_deposit],
instructions="You book event venues. Use the tools.",
strategy="react",
policy={"require_approval_for": ["pay_deposit"], "blocked_tools": ["cancel_*"]},
)
result = asyncio.run(agent.run_durable("Book a venue in Lisbon for 2026-12-11."))
print(result.output, result.execution_id)
A relative script path is resolved from the working directory of the process that
reads it. In a durable run that is the engine's sidecar, which jamjet dev starts
from the folder you run it in. Run jamjet dev from your project folder, or give
an absolute path.
jamjet dev needs pip install 'jamjet[sidecar]'. Start the stack in the first
terminal, from the project folder:
jamjet dev --modules venue_tools
Run python book.py in a second terminal. The run stops at pay_deposit and
waits. From a third terminal:
jamjet executions # every run
jamjet approvals # every run waiting for approval
jamjet approve <id> -d approved --as <name>
jamjet audit <id>
jamjet approvals prints a command you can paste. This is what it printed
on a real run:
exec_f89599febf784b7e908a8b596f608b88 __tools_2__
covers step 0; calls: pay_deposit -> venue_tools:pay_deposit({"amount": 500, "venue": "Casa do Rio"})
jamjet approve exec_f89599febf784b7e908a8b596f608b88 --decision approved --node-id=__tools_2__ --action-digest=d636deba2b4b63cf81995a39cbe5bc010a9bca9b7ab8a16425dcf007475c31a6
Add --as <name> to record who approved. Then:
approved node=__tools_2__ execution=exec_f89599febf784b7e908a8b596f608b88
$ jamjet audit exec_f89599febf784b7e908a8b596f608b88
Audit trail for exec_f89599febf784b7e908a8b596f608b88
Agent: venue-booker Status: completed Started: 2026-11-18 03:09:17
Source: the engine's event log and approval records. Times are UTC.
03:09:17 model asked for search_venues call_0_0 {"city":"Lisbon","date":"2026-12-11"}
03:09:19 ran search_venues call_0_0 -> [{"venue": "Casa do Rio", "capacity": 120, "price_per_day": ...
03:09:19 model asked for check_dates call_1_0 {"venue":"Casa do Rio"}
03:09:21 ran check_dates call_1_0 -> ["2026-12-04", "2026-12-11"]
03:09:21 model asked for pay_deposit call_2_0 {"amount":500,"venue":"Casa do Rio"}
03:09:23 pay_deposit needs approval approver: human
03:09:24 approved by tester dev mode, name not verified
03:09:25 ran pay_deposit call_2_0 -> Deposit of 500 paid for Casa do Rio.
03:09:27 final answer Booked Casa do Rio in Lisbon for 11 December. The 500 deposit is paid.
search_venues ran 1 time
check_dates ran 1 time
pay_deposit ran 1 time, approved by tester at 03:09:24
"ran N time(s)" counts the tool results the engine recorded. A tool whose worker
died before its result was recorded is not counted, though it may still have had
an effect. That is why the series keeps its own payments.log.
In dev mode the engine records the name you pass. With an API token it records
the token's name. If the engine stops while run_durable waits, the call keeps
waiting and resumes when the engine is back. kill -9 on the worker mid-tool
is not handled: the run fails.
Hello World — Python
from jamjet import Workflow, tool
from pydantic import BaseModel
class SearchResult(BaseModel):
summary: str
sources: list[str]
@tool
async def web_search(query: str) -> SearchResult:
# your implementation here
...
workflow = Workflow("research")
@workflow.state
class ResearchState(BaseModel):
question: str
result: SearchResult | None = None
@workflow.step
async def search(state: ResearchState) -> ResearchState:
result = await web_search(query=state.question)
return state.model_copy(update={"result": result})
@workflow.step
async def summarize(state: ResearchState) -> ResearchState:
# model call here
...
Hello World: YAML, with a human in the loop
# workflow.yaml
workflow:
id: refund-reply
version: 0.1.0
start: draft
nodes:
draft:
type: model
model: claude-haiku-4-5-20251001
prompt: "Draft a reply to: {{ state.request }}"
next: review
review:
type: human_approval
description: Approve the draft before it is sent
timeout: 1h
fallback: end # nobody decided in time: stop, do not send
next: send
send:
type: model
model: claude-haiku-4-5-20251001
prompt: "Send this: {{ state.last_model_output }}"
next: end
jamjet validate workflow.yaml
jamjet run workflow.yaml --input '{"request": "refund order 42"}'
# In another terminal, while the run waits at `review`:
jamjet approvals <exec-id> # what is waiting, and the exact approve command
The run stops at review until someone decides. The decision is recorded in
the run's state at state.__approvals.review (approved, approver, comment,
time), which only the engine writes. If nobody decides within the hour, the
approval expires, send is skipped and the run ends. Outside dev mode the
person who started the run cannot approve it.
When jamjet run follows a text-mode execution, it also prints the recorded
terminal step results with known durations, proportional bars, and a clearly
labelled recorded step-time total. Missing step timings are shown as unknown;
JSON output keeps its existing event payload unchanged.
MCP and A2A
A workflow cannot call MCP tools or A2A agents: registration refuses
mcp_tool and a2a_task nodes. The runtime itself is an MCP server at
/mcp. See the
MCP guide
and the
A2A guide.
Durability across frameworks
Wrap a side-effecting tool with @durable and its result is cached under a
key built from the run id, the function and its arguments. After a crash or
restart, a call that already completed returns the cached result instead of
running again, whichever agent framework you use. A call that crashed before
its result was stored runs again, so pass an idempotency key to the external
system as well.
from jamjet import durable
@durable
def charge_card(amount: float) -> dict:
return stripe.charges.create(amount=amount)
Pair it with a durable_run() context manager — one shim per framework:
| Framework | Import |
|---|---|
| LangChain | from jamjet.langchain import durable_run |
| CrewAI | from jamjet.crewai import durable_run |
| Google ADK | from jamjet.adk import durable_run |
| Anthropic Agent SDK | from jamjet.anthropic_agent import durable_run |
| OpenAI Agents SDK | from jamjet.openai_agents import durable_run |
Example with LangChain:
from langchain.agents import AgentExecutor
from jamjet import durable, durable_run
@durable
def charge_card(amount): ... # your real tool
executor = AgentExecutor(...)
# Use a stable execution_id that survives process restarts.
# (Persist this id in your job queue / DB / wherever you start agent runs.)
AGENT_RUN_ID = "booking-agent-run-abc123"
with durable_run(AGENT_RUN_ID):
executor.invoke({"input": "book a flight to Tokyo"})
# If the process crashes after `charge_card` returns and restarts under
# the same AGENT_RUN_ID, the cached result is returned on replay and
# Stripe is not called again.
For framework-native run-identity (where you'd otherwise want with durable_run(executor):), see the per-shim docs in jamjet/<framework>/__init__.py — note that most frameworks expose run_id only per-invocation via callbacks, so threading a stable identity across crash boundaries is the user's responsibility.
See the per-module guide at jamjet/durable/README.md.
JamJet Cloud — Hosted Governance (jamjet.cloud)
Starting in 0.6.0, the jamjet package includes a jamjet.cloud submodule for the hosted control plane. Two-line install:
import jamjet.cloud as jamjet
from openai import OpenAI
jamjet.configure(api_key="jj_xxxxxxxxxxxx", project="my-agent")
# Every OpenAI / Anthropic call is now captured automatically.
resp = OpenAI().chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "hello"}],
)
Open app.jamjet.dev/dashboard/traces — the call appears within ~5 seconds with model, tokens, cost, and duration.
Optional governance primitives:
jamjet.policy("block", "payments.*") # strip matching tools, refuse matching tool calls
jamjet.budget(max_cost_usd=5.00) # cap spend; raises BudgetExceeded
approval = jamjet.require_approval(action="charge_card", context={...})
@jamjet.trace # decorate any function
def lookup_customer(...): ...
Policy and budget apply to the sync clients: OpenAI chat.completions.create,
.parse(), .stream() and with_raw_response, and Anthropic messages and
beta.messages create / parse, legacy OpenAI functions included.
Blocked tools are stripped from the request, and a tool call the model returns
for a blocked tool raises JamJetPolicyBlocked. With stream=True, text
streams through as it arrives; once any policy rule is set, chunks from the
first tool call onward are held until the stream ends and checked before your
code sees them, and the streamed usage counts toward the budget. Server tools
(such as web search) and MCP toolsets run on the vendor's side before a tool
call could be refused, so a rule that could match them removes them from the
request; Anthropic's own client tools (bash, text editor, computer, memory)
are gated like any other tool. Not enforced, so they raise
JamJetUnenforceableCall while any block or require_approval rule is set:
OpenAI's Responses API, Anthropic's messages.stream(), the async clients
(AsyncOpenAI, AsyncAnthropic), the batch APIs, and
with_raw_response / with_streaming_response with stream=True.
jamjet.policy("require_approval", "payments.*") keeps the tool available.
When the model calls it, the SDK opens an approval in JamJet Cloud with the
tool name, call id, arguments, model and rule, and waits for a reviewer's
decision before returning the response. A rejection raises
JamJetApprovalRejected. No decision within approval_timeout_seconds
(a configure() argument, default 1 hour), or no way to reach Cloud, raises
JamJetApprovalTimeout. The timeout is sent to Cloud as the approval's
deadline (clamped to 1 minute to 24 hours); JamJet Cloud deployments since
jamjet-cloud #87 refuse decisions after it. The approval shows the call's
arguments with credentials always masked, PII masked when redaction is on
(IBANs and card numbers keep their last 4), and an arguments_sha256 that the
SDK re-checks before releasing the approved call.
Install with the LLM SDK you use:
pip install jamjet[openai] # auto-instrument OpenAI
pip install jamjet[anthropic] # or Anthropic
pip install jamjet[cloud-all] # both
Full guide: Cloud Quickstart · Sign up free
Architecture
┌──────────────────────────────────────────────────────────┐
│ Authoring Layer │
│ Python SDK | YAML | CLI │
├──────────────────────────────────────────────────────────┤
│ Compilation / Validation │
│ Graph IR | Schema | Policy lint │
├────────────────────────────┬─────────────────────────────┤
│ Rust Runtime Core │ Protocol Layer │
│ Scheduler | State SM │ MCP server (/mcp) │
│ Event log | Snapshots │ Agent discovery │
│ Workers | Timers │ │
├────────────────────────────┴─────────────────────────────┤
│ Governance │
│ Policy | Approvals | RBAC | Signed audit log │
├──────────────────────────────────────────────────────────┤
│ Runtime Services │
│ Model adapters | Model sidecar | External workers │
├──────────────────────────────────────────────────────────┤
│ Storage │
│ SQLite | In-memory (ephemeral) │
└──────────────────────────────────────────────────────────┘
Read more: Architecture Overview
Documentation
Start here
| Guide | Description |
|---|---|
| Quickstart | Get a workflow running in 10 minutes |
| Core Concepts | Agents, workflows, nodes, state, durability |
| Workflow Authoring | YAML and Python authoring guide |
| Python SDK | Full SDK reference |
| YAML Reference | Complete YAML spec |
Connect to other systems
| Guide | Description |
|---|---|
| MCP Integration | The runtime's MCP endpoint, and listing a server's tools |
| A2A Integration | Reading and registering Agent Cards |
| Agent Model | Agent Cards, lifecycle, autonomy levels |
| Human-in-the-Loop | Approval nodes, deadlines, separation of duties |
| Observability | Event timelines, replay, OpenTelemetry, token counts |
| Deployment | Running the server: SQLite, tokens, workers, Docker |
Advanced & enterprise
| Guide | Description |
|---|---|
| Security | Tokens, RBAC, tenant policy, secrets, signed audit log |
| Tool Sandboxing | What runs where, and how to contain workers |
| Eval Node | Evaluation as a workflow primitive |
| ANP Discovery | Decentralized agent discovery via DID |
Architecture deep-dives
| Document | Description |
|---|---|
| Architecture Overview | Full system architecture |
| Execution Model | State machine, node types, IR |
| State & Durability | Event sourcing, snapshotting, recovery |
| Agent Model | Agent-native runtime design |
| MCP Architecture | MCP client/server internals |
| A2A Architecture | A2A protocol internals |
| Protocol Adapters | Extensible protocol layer |
Contributing
We welcome contributions of all kinds — bug reports, feature requests, documentation, and code.
- Read CONTRIBUTING.md to get started
- Check open issues for
good first issuetags - RFCs for major changes: see docs/rfcs/
- Architecture decisions: see docs/adr/
Community
- GitHub Discussions: github.com/jamjet-labs/jamjet/discussions
License
Apache 2.0. See LICENSE.
Metadata
Release files for jamjet 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jamjet-0.13.0.tar.gz | 946.3 kB | With provenance | Details for jamjet-0.13.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jamjet-0.13.0-py3-none-any.whl | Python 3 | none | any | Details for jamjet-0.13.0-py3-none-any.whl |
Total release size: 1.3 MB
Release files / jamjet-0.13.0.tar.gz
| Download URL | jamjet-0.13.0.tar.gz |
|---|---|
| Size | 946.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
06a08f2f2b257065ec1c24acdfd5fd54af6028e4e0b695debc59190628862020
|
|
BLAKE2b-256 checksum How to use checksums |
d1fb4eb95026c6739830c07bef85b17291130dae1f7be87995647c55ef87eddb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / jamjet-0.13.0-py3-none-any.whl
| Download URL | jamjet-0.13.0-py3-none-any.whl |
|---|---|
| Size | 386.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d57f53695f9f9c73baf904a724f2d2d0fe901b0b9edfd66208c1219ea6a04b39
|
|
BLAKE2b-256 checksum How to use checksums |
e3cdb252e631f51dcb837cbca7d565f1fd3eb34626916de575425a7a49bf1493
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for jamjet 0.13.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for jamjet-0.13.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.