Skip to main content

JamJet

Write the safety policy once. Run it everywhere your agents can act.

CI PyPI License Python Docs

JamJet demo

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
  • @durable keeps a tool call that completed from running again after a crash or restart, with shims for LangChain, CrewAI, ADK, OpenAI Agents SDK, Anthropic Agent SDK
  • jamjet.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 same policy.yaml
  • The runtime's MCP server (/mcp) starts, inspects and approves runs, and jamjet mcp connect lists 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.


Community


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)

Source distribution for jamjet 0.13.0
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)

Table of built distributions (wheels) for jamjet 0.13.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page