@fidacy/openai-agents

Gate OpenAI Agents SDK tool calls behind a signed Fidacy verdict. A denied payment never executes.

npm i @fidacy/openai-agents @openai/agents

import { guardTools } from "@fidacy/openai-agents";

// No key, no signup: the offline judge decides your first 20 calls.
const tools = guardTools([payTool, searchTool]);
// payTool is now assessed before every call. searchTool is returned untouched.

Two ways it decides

Offline, out of the box. With no credential the deterministic local judge runs: deny-by-default, your own limits, a hash-chained log on your machine. The first 20 decisions on an install are free and need no account, so you can watch a payment get blocked before deciding whether you want any of this.

Set the limits that fit your case:

const tools = guardTools([payTool], {
  mandate: { payees: ["acme-inc"], perTxMax: 5_000, maxTotal: 50_000 },
});

A blocked call tells you what was stopped, in money terms, and prints the exact edit that would allow it.

Hosted, with an account. Pass apiKey and the engine decides instead, returning a verdict signed with a stable key that anyone can verify against the public JWKS, plus a Bitcoin-anchored audit chain that outlives your process.

Free key, no card: https://fidacy.com/claim

Where it hooks in

The SDK's function tools expose invoke(runContext, input), where input is the raw JSON string the model produced. Replacing invoke is the only spot between the model deciding to pay and the money moving. The SDK's own guardrails run around the agent turn, not around this call, and needsApproval puts a human in the loop rather than a policy.

Fail-closed

If the engine is unreachable, the key is wrong, or the request times out, the call is refused, never executed. review also blocks by default; set reviewIsDeny: false to let it through.

Refusal, not a crash

By default a blocked call returns a refusal string the model can read, so the agent explains what happened instead of dying with a stack trace. The payment still did not run.

Fidacy deny for send_payment (risk score 97, assessment as_1). Nothing was
executed. Tell the user the payment was blocked by their firewall and quote the
assessment id.

Set throwOnDeny: true for a hard stop that throws FidacyDenied with the signed proof (verdict.riskPayloadJws, verifiable offline with @fidacy/verify).

Options

| Option | Default | What it does | | --- | --- | --- | | apiKey | FIDACY_ENGINE_API_KEY | Engine credential. Omit it to stay offline | | mandate | none | Offline limits: payees, perTxMax, maxTotal, currency | | engineUrl | https://api.fidacy.com | Engine base URL | | client | built from apiKey | Bring your own @fidacy/sdk client | | isPayment | name heuristic | Which tools guardTools gates | | toMandate | payee/amount/currency + raw args | Build the mandate the engine assesses | | reviewIsDeny | true | Whether review blocks | | throwOnDeny | false | Throw instead of returning a refusal | | onDecision | none | Observe every decision, including approvals |

The wrapped tool keeps name, description, parameters and strict, so the model and the runner see the same function tool.

zod 4: @openai/agents requires zod ^4. This package does not depend on zod itself, so it works with whatever version the SDK pulls in.

Anonymous telemetry

The adapter reports anonymous usage so we can tell which surfaces are alive: an install marker, an "agent active" ping, the result class of local decisions (allow, deny_payee, deny_cap and so on) and the moment the free-trial wall is shown. Every field is a closed enum. It never carries payees, amounts, currencies, tool arguments or any content, and it never sits on the path of a decision: failures are swallowed and nothing blocks.

Disable it entirely with:

export FIDACY_DISABLE_TELEMETRY=1

The anonymous id lives in ~/.fidacy/config.json, shared with @fidacy/mcp, so the free-decision counter and a later account claim stay consistent across Fidacy tools on the same machine.

Apache-2.0 · https://fidacy.com