@geostack/arc-vercel-ai

Vercel AI SDK adapter for Arc. Wrap your ai tools once and every tool call is submitted to Arc for an allow / ask / block policy decision before the tool's execute runs.

The Vercel AI SDK answers "what tools can the agent call?" Arc answers "should this specific action run right now?" This adapter is the bridge: on allow your execute runs and its result is returned; on ask or block the tool body never runs and the agent loop gets a typed Arc outcome instead. It never approves actions and never bypasses policy.

Install

npm install @geostack/arc-vercel-ai ai

Configure

export ARC_API_URL=https://your-arc-api
export ARC_AGENT_TOKEN=<agent-token>   # from a secret store; never commit
export ARC_APP_SLUG=<app-slug>         # or ARC_APP_ID

Use

Record keys passed to wrapTools must match your Arc action keys.

import { generateText, tool } from "ai";
import { z } from "zod";
import { ArcVercelAiGuard, isArcToolOutcome } from "@geostack/arc-vercel-ai";

const arc = ArcVercelAiGuard.fromEnv();

const tools = arc.wrapTools({
  issue_refund: tool({
    description: "Issue a customer refund.",
    inputSchema: z.object({
      amount: z.number(),
      customerId: z.string(),
      reason: z.string()
    }),
    execute: async (input) => issueRefund(input)
  })
});

const result = await generateText({ model, prompt, tools });

for (const toolResult of result.toolResults) {
  if (isArcToolOutcome(toolResult.output) && toolResult.output.status === "pending_approval") {
    console.log("Waiting for approval in Arc:", toolResult.output.approval_id);
  }
}

Or wrap a single tool with an explicit action key:

import { withArc } from "@geostack/arc-vercel-ai";

const guarded = withArc(refundTool, {
  actionKey: "issue_refund",
  agentToken: process.env.ARC_AGENT_TOKEN,
  appSlug: "ai-support-ops",
  arcApiUrl: process.env.ARC_API_URL
});

Decision behavior

Every tool call creates an Arc invocation (POST /v1/agent/invocations, authenticated with the agent token), so Arc policy, approvals, and audit stay the system of record.

• allow — the wrapped execute runs and its result is returned unchanged.
• ask — execute does not run. The call returns { kind: "arc_tool_outcome", status: "pending_approval", approval_id, ... }. A human approves through the Arc approval flow; the adapter never auto-approves.
• block — terminal. Returns { kind: "arc_tool_outcome", status: "blocked", ... } and never runs execute.
• fail closed — missing config, an unreachable Arc, or an unknown decision/status returns { kind: "arc_tool_outcome", status: "error", code, ... } and never runs execute. Token-like strings are redacted from returned errors.

Branch on outcomes with isArcToolOutcome(value); anything else is your tool's own result.

Idempotency is preserved: the Vercel AI SDK toolCallId is used as the Arc idempotency key (vercel-ai:<toolCallId>), otherwise one is generated per call (configurable via idempotencyKeyFactory).

See the Arc package for the full action-authority model.

License

MIT