@fidacy/openai-agents

@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";

const tools = guardTools([payTool, searchTool], {
  apiKey: process.env.FIDACY_ENGINE_API_KEY,
});
// payTool is now assessed before every call. searchTool is returned untouched.

Activation is required

YOUR AI AGENT IS UNPROTECTED. GET YOUR FREE API KEY NOW at https://app.fidacy.com/signup. Set FIDACY_ENGINE_API_KEY where the agent runs and connect the executor before retrying. Without the key, a consequential tool call is refused with activation_required and nothing executes.

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.

With an account-owned key, the engine returns 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://app.fidacy.com/signup

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.

Stops safely

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	Required account-owned engine credential
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 anonymous installation and activity signals stay consistent across Fidacy tools on the same machine.

Apache-2.0 · https://fidacy.com