Adapters

Where a framework or a system meets the boundary

An adapter does one of two jobs. On the way in, it turns a framework's tool call into a proposal that the trusted runtime captures as an intent. On the way out, it executes an authorized action against a real system and reports what happened.

Source: agent-safe-pipeline v0.3.5
Checked: 2026-09-25

On the way in

Framework tool calls

For the OpenAI Responses API and Agents SDK, the Vercel AI SDK and LangChain, the adapter is a few lines of your own code. What each framework already carries is in the coverage matrix.

Rendered from spec/intent/v1/frameworks.md, “The adapter” in decionis/agent-safe-pipeline at v0.3.5 (b4d5c9e), synced 2026-09-25. The repository is the source of truth. View this file on GitHub

The adapter

The adapter is the few lines between the record and IntentCapture. In the reference test it is exactly this, once per framework:

// OpenAI: the arguments are a JSON string.
const parameters = JSON.parse(item.arguments) as JsonObject;
const proposal = { action: item.name, target: `shopify:order:${parameters.orderId}`, parameters };

// Vercel AI SDK: the input is already an object.
const proposal = {
  action: part.toolName,
  target: `shopify:order:${part.input.orderId}`,
  parameters: part.input,
};

// LangChain: the args are already an object.
const proposal = {
  action: call.name,
  target: `shopify:order:${call.args.orderId}`,
  parameters: call.args,
};

// The same for all three: the trusted runtime states what the record cannot.
const captured = new IntentCapture().capture(proposal, {
  tenantId, // the organization
  actor: { id: "synthetic-support-agent", type: "AI_AGENT", runtime: "openai" }, // the principal, from the runtime's own identity
  downstreamTarget: { system: "shopify", operation: "refund", endpoint: "POST /refunds" },
  context: { source: "conformance", tool_call_id: item.call_id }, // the framework's id, kept for correlation
  idempotencyKey: "refund-synthetic-1-openai-v1", // the runtime's retry identity, never the model's id
});
// captured.intentHash is what the authority is asked about and what the grant is bound to.

The target is the adapter's to name because the framework does not distinguish it from the other arguments; which argument identifies the resource is a property of the tool, not of the framework. The framework's call id is kept in the trusted context so the binding correlates with the framework's own record, and it is not used as the idempotency key: it identifies the model's call, and a retry of the same call by the runtime must present the same intent, while a new call with the same id from a different turn must not.

On the way in

MCP tools

MCP is the one case where the adapter ships with AgentSafe. MCP decides how an agent invokes a tool; McpGuard in @decionis/agentsafe decides nothing, but binds each invocation to an intent so that Decionis can decide whether this exact invocation may run, and the tool runs once, on a claimed grant.

MCP execution interception examples/mcp-tool-gate

On the way out

Effect adapters

An effect adapter is what performs an authorized action against a system of record and accounts for its effect. After the attempt, the outcome is reported to the authority as COMMITTED, FAILED or INDETERMINATE. The contract, as the source defines it:

/**
 * One contract for every family of consequential actions. It is deliberately
 * four small methods, three of them pure:
 *
 * - `prepare` works out what the action asks for and what its effect should
 *   be. It reaches nothing and may be called before the authority is asked.
 * - `execute` performs the side effect, once, inside the dispatch the
 *   pipeline opened. A provider that neither committed nor refused is an
 *   `IndeterminateOutcome`, never a guess.
 * - `observeEffect` reads what the provider said into the profile's
 *   projection. Pure: no second call, no interpretation of silence.
 * - `reconcile` asks the provider what it did with an idempotency key,
 *   read-only, and may never initiate anything.
 *
 * A second family is a directory beside `banking/`, not a rewrite: the
 * handler bridge, the comparison, the evidence and the verifier all work off
 * this contract alone.
 */
export interface EffectAdapter<TAction> {
  readonly id: string;
  readonly version: string;
  /** The transport action names this adapter answers for. */
  readonly actionTypes: readonly string[];
  prepare(action: TAction): PreparedAction;
  execute(execution: AdapterExecution<TAction>): Promise<ProviderResult>;
  observeEffect(result: ProviderResult, prepared: PreparedAction): JsonObject | null;
  reconcile(context: AdapterReconciliation): Promise<ProviderReconciliationResult>;
}

packages/agentsafe/src/adapters/EffectAdapter.ts at v0.3.5. View the file

prepare: works out, before anything leaves the process, the effect the action should have and the digests that bind it
execute: performs the action once, on a verified authorization, with the idempotency key and a deadline, and reports COMMITTED or FAILED
observeEffect: reads back what the provider says happened, for comparison with what was expected
reconcile: answers, after an interrupted attempt, whether the action completed, was never executed, or cannot be known

One family implements it today: banking, which maps the BEAP vocabulary onto this contract. AgentSafe is pre-1.0, so the interface may still change between releases. The banking adapter

At the far end

Provider-side verification

The system being called can check for itself that a request carries a valid grant for exactly that request before it acts, instead of trusting the gateway in front of it.

The profile and its vectors

Three levels: the executor's message signature, the authority's claim attestation for this exact request with replay refused, and the provider's own signed receipt of the effect.

Conformance

Verifiers

A TypeScript reference and verifiers for Envoy and Kong (Go), Spring, Rust and .NET.

verifiers/