Examples

Working examples that demonstrate Fuze's core capabilities. Each example is self-contained and produces a trace file you can inspect.

TypeScript

01 — Basic Guard

The simplest possible example. Wrap a function with guard() and see the trace output.

import { guard } from 'fuze-ai'

const search = guard(async function searchDocuments(query: string) {
  return await vectorDb.search(query)
})

const results = await search('AI agent safety')
// Check ./fuze-traces.jsonl for the trace

02 — Budget Ceiling

Set a $1.00 budget. Each step costs $0.30. The 4th call gets blocked.

import { guard, configure, BudgetExceeded } from 'fuze-ai'

configure({ defaults: { maxCostPerRun: 1.00 } })

const analyse = guard(analyseFn, { maxCost: 0.30 })

try {
  await analyse('doc')
} catch (err) {
  if (err instanceof BudgetExceeded) {
    // Budget ceiling hit — step blocked before execution
  }
}

03 — Loop Detection

Simulate an agent stuck retrying the same failed search. Fuze catches it after 3 identical calls.

import { guard, configure, LoopDetected } from 'fuze-ai'

configure({
  defaults: { maxIterations: 20, onLoop: 'kill' },
  loopDetection: { repeatThreshold: 3 },
})

const search = guard(searchFn)
// 3rd identical call throws LoopDetected

04 — Side-Effect Tracking

Create an invoice (side-effect with compensation), then fail on email send. Shows how Fuze tracks which steps need rollback.

const invoice = guard(createInvoice, {
  sideEffect: true,
  compensate: cancelInvoice,
})

05 — Multi-Agent

Two agents (researcher + writer) share a single budget using createRun().

import { createRun } from 'fuze-ai'

const run = createRun('research-team', { maxCostPerRun: 5.00 })
const search = run.guard(webSearch, { maxCost: 0.10 })
const draft = run.guard(writeDraft, { maxCost: 1.00 })

await search('query')
await draft('outline')
console.log(run.getStatus()) // { totalCost, stepCount, ... }
await run.end()

06 — MCP Proxy

Protect any MCP server with zero code changes.

# Before: unprotected
npx @modelcontextprotocol/server-postgres postgres://localhost/mydb

# After: Fuze protection
npx fuze-ai proxy -- npx @modelcontextprotocol/server-postgres postgres://localhost/mydb

See the full MCP Proxy docs for configuration options.

Python

01 — Basic Guard

from fuze_ai import guard

@guard
async def search(query: str) -> list[str]:
    return await vector_db.search(query)

02 — Budget Ceiling

from fuze_ai import guard, configure

configure({'defaults': {'max_cost_per_run': 1.00}})

@guard(max_cost=0.30)
async def analyse(text: str) -> str:
    return f'Analysis of {text}'

03 — Loop Detection

from fuze_ai import guard, configure

configure({
    'defaults': {'max_iterations': 20},
    'loop_detection': {'repeat_threshold': 3}
})

@guard
async def search(query: str) -> str:
    return 'No results found.'

04 — Side-Effects

@guard(side_effect=True, compensate=cancel_invoice)
async def create_invoice(customer_id: str, amount: float) -> dict:
    return {'invoice_id': f'INV-{customer_id}'}

05 — LangGraph Adapter

from fuze_ai.adapters.langgraph import fuze_tool

@fuze_tool(max_cost=0.10)
def search_web(query: str) -> str:
    return f'Results for: {query}'

Running all examples

# TypeScript
cd examples/typescript/01-basic-guard && npm install && npx tsx index.ts

# Python
cd examples/python/01-basic-guard && pip install fuze-ai && python main.py

Every example produces a fuze-traces.jsonl file. Each line is a JSON record with timestamps, costs, and guard events.

QuickstartConfiguration