nexart.iodocs

    Agent Kit — Certify Agent Tool Calls

    A thin convenience layer for producing verifiable execution records from agent tool calls and decisions.

    Naming collision: certifyDecision

    @nexart/agent-kit exports an async certifyDecision that dispatches through the workflow runner. @nexart/ai-execution also exports a function named certifyDecision, but that one is synchronous and seals a CER locally with no workflow context.

    The two are not interchangeable. Pick agent-kit when you want workflow-aware tool wrapping and decision certification inside a startWorkflow / step / finish structure. Pick the AI Execution SDK primitives directly for one-shot CERs.

    What It Is

    @nexart/agent-kit is a thin convenience layer for builders who want agent tool calls and final decisions to produce tamper-evident, verifiable execution records with minimal integration work.

    Use @nexart/agent-kit when you want agent steps to emit standard NexArt CERs without wiring the lower-level SDKs manually.

    It sits on top of two existing packages:

    What it is not
    @nexart/agent-kit is not an agent framework. It does not provide orchestration, planning, memory, or multi-agent runtime capabilities. It only handles CER production for agent workflows.
    Setting this up with an AI coding assistant?
    The Agent-Kit Instructions for AI Agents page is a prescriptive runbook you can paste directly into Cursor, Claude Code, Lovable, or Windsurf. It handles install, pattern selection, and verification end to end.

    Installation

    npm install @nexart/agent-kit

    Current version: 0.5.3

    If you also import @nexart/signals or @nexart/ai-execution directly:

    npm install @nexart/agent-kit @nexart/signals @nexart/ai-execution

    Exports

    wrapTool()

    Use wrapTool() when you want an individual tool call to produce its own standard CER.

    wrapTool(opts) returns a callable. When invoked with arguments, it executes the run function and returns the tool result alongside a standard cer.ai.execution.v1 bundle. Signals and node attestation are optional.

    wrapTool()
    import { wrapTool } from "@nexart/agent-kit";

const lookupCustomer = wrapTool({
  name: "lookup_customer",
  model: "gpt-4o",
  run: async (input) => {
    // your tool logic
    return { customerId: "cust_123", tier: "enterprise" };
  },
  // optional
  signals: collector.export().signals,
  attestOptions: {
    nodeUrl: "https://your-node.nexart.io",
    apiKey: process.env.NEXART_API_KEY
  }
});

const { result, bundle, certificateHash } = await lookupCustomer({
  email: "user@example.com"
});

// result          = { customerId: "cust_123", tier: "enterprise" }
// bundle          = standard cer.ai.execution.v1 bundle
// certificateHash = "sha256:..."

    certifyDecision()

    Use certifyDecision() when you want to certify the final decision or outcome of an agent workflow.

    It is a thin wrapper over the AI Execution SDK. It supports optional signals and optional node attestation, and returns a standard cer.ai.execution.v1 bundle. It does not change hashing or verification semantics.

    certifyDecision()
    import { certifyDecision } from "@nexart/agent-kit";

const { bundle } = await certifyDecision({
  model: "gpt-4o",
  input: { query: "Should we approve this refund?" },
  output: { decision: "approve", reason: "within policy" },
  // optional
  signals: collector.export().signals,
  attestOptions: {
    nodeUrl: "https://your-node.nexart.io",
    apiKey: process.env.NEXART_API_KEY
  }
});

    When to Use Which

    • Use wrapTool() when you want one CER per tool invocation.
    • Use certifyDecision() when you want one CER for the final decision or workflow outcome.

    Both can be used together in a single workflow. For example, wrap individual tools to certify each step, then certify the final decision separately.

    Example

    Full workflow example
    import { wrapTool, certifyDecision } from "@nexart/agent-kit";
import { createSignalCollector } from "@nexart/signals";

const collector = createSignalCollector();

// 1. Define and invoke a wrapped tool
const checkPolicy = wrapTool({
  name: "check_policy",
  model: "gpt-4o",
  run: async (input) => ({ eligible: true, policyId: "ret-30d" }),
  signals: collector.export().signals
});

const { result } = await checkPolicy({ orderId: "order_456" });

// 2. Add a signal based on the tool result
collector.add({
  type: "policy.check",
  source: "refund-agent",
  payload: { policyId: result.policyId, result: "pass" }
});

// 3. Certify the final decision
const { bundle } = await certifyDecision({
  model: "gpt-4o",
  input: { orderId: "order_456", policyResult: result },
  output: { decision: "approve_refund" },
  signals: collector.export().signals,
  attestOptions: {
    nodeUrl: "https://your-node.nexart.io",
    apiKey: process.env.NEXART_API_KEY
  }
});

    Workflow Helpers

    For linear multi-step workflows that produce a Project Bundle, agent-kit provides workflow helpers:

    • startWorkflow(opts) begins a new workflow and generates a workflowId
    • step(name, fn) creates a CER per step. Records the step name as input and the function return value as output. Each step gets its own executionId. The workflowId links them. Implicit closure state is NOT recorded.
    • finish() builds the Project Bundle synchronously
    Linear workflow with agent-kit
    import { startWorkflow } from "@nexart/agent-kit";

const workflow = startWorkflow({ projectTitle: "Contract review" });

const clauses = await workflow.step("Extract clauses", async () => {
  return await llm.call("Extract key clauses...");
});

const risks = await workflow.step("Summarize risks", async () => {
  return await llm.call("Summarize risks from: " + clauses);
});

const bundle = workflow.finish();
// bundle.integrity.projectHash is the verifiable hash
    Designed for linear workflows
    agent-kit v0.5.3 handles simple linear workflows. For complex DAGs or non-linear execution graphs, use the lower-level SDK helpers (certify + createProjectBundle).

    Verification

    Bundles produced by @nexart/agent-kit are standard cer.ai.execution.v1 artifacts and verify with existing NexArt verification tooling, including verifyCer() and verify.nexart.io. No special verifier is needed. Project Bundles built with finish() verify via verifyProjectBundle() or verifyProjectBundleAsync().

    Backward Compatibility

    @nexart/agent-kit does not change CER hashing, attestation, or verification semantics. It is additive only. Previously created CERs continue to verify identically.