# Agent Kit — Certify Agent Tool Calls

URL: https://docs.nexart.io/docs/agent-kit

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:

- @nexart/ai-execution for CER creation and attestation
- @nexart/signals for structured context signals

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.

## Related

- AI Execution SDK - the underlying CER creation and attestation API
- Project Bundles - multi-step workflow verification
- Context Signals - structured metadata recorded alongside executions
- Verification - how CER verification works