@nexart/agent-kit

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.

What this is

@nexart/agent-kit wraps @nexart/ai-execution to make it easier to attach Certified Execution Records (CERs) to individual tool calls and agent decisions. It works with @nexart/signals to bind upstream signal evidence into those records.

It does not change CER hashing, attestation, or verification semantics. Every bundle it produces is a standard cer.ai.execution.v1 artifact that verifies exactly like any other NexArt AI CER.

What this is NOT

• Not an agent framework
• Not an orchestration system
• Not a planning or memory layer
• Not a multi-agent runtime

Installation

npm install @nexart/agent-kit

@nexart/ai-execution and @nexart/signals are installed automatically as dependencies. If your own code imports from those packages directly (e.g. to call verifyCer or createSignalCollector), install them explicitly too:

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

When to use each export

| Use this | When you want to… | |----------|------------------| | wrapTool() | Give an individual tool call its own CER — one record per invocation, capturing input, output, and AIEF-06 tool evidence | | certifyDecision() | Certify the final decision or outcome of an agent workflow — one record for the concluded result, optionally with upstream signal evidence |

Exports

| Export | Description | |--------|-------------| | wrapTool(opts) | Wraps an async function and returns a callable that produces a CER per invocation | | certifyDecision(params) | Certifies a final agent decision or workflow outcome | | AGENT_KIT_VERSION | Package version string |

Basic example

import { wrapTool, certifyDecision } from '@nexart/agent-kit';
import { createSignalCollector } from '@nexart/signals';

// ── 1. Wrap a tool ────────────────────────────────────────────────────────────

const search = wrapTool({
  name: 'web-search',
  source: 'my-agent',
  run: async (args: { query: string }) => {
    const results = await fetchResults(args.query);
    return results;
  },
});

// ── 2. Call it — get result + CER ────────────────────────────────────────────

const { result, bundle, certificateHash } = await search({ query: 'nexart' });
console.log(certificateHash);  // sha256:<64 hex chars>

// ── 3. Collect signals ────────────────────────────────────────────────────────

const collector = createSignalCollector({ defaultSource: 'github-actions' });
collector.add({ type: 'ci-pass', source: 'github-actions', payload: { build: 'green' } });
collector.add({ type: 'approval', source: 'github', actor: 'alice', payload: { pr: 42 } });

// ── 4. Certify the final decision ─────────────────────────────────────────────

const { bundle: decision, certificateHash: decisionHash } = await certifyDecision({
  decision: 'Approve deployment to production',
  output: 'APPROVED',
  provider: 'openai',
  model: 'gpt-4o',
  signals: collector.export().signals,  // evidence bound into the CER
  appId: 'my-app',
  workflowId: 'release-flow',
});

API reference

wrapTool(opts)

Produces a callable that executes the wrapped function and creates a CER for that invocation. Each call gets its own sealed cer.ai.execution.v1 bundle with AIEF-06 tool evidence (snapshot.toolCalls) capturing the input and output hashes.

function wrapTool<TArgs, TResult>(
  opts: WrapToolOptions<TArgs, TResult>
): (args: TArgs) => Promise<WrapToolResult<TResult>>

Options:

| Field | Type | Description | |-------|------|-------------| | name | string | Unique tool name — used as the model identifier in the CER snapshot | | run | (args: TArgs) => Promise<TResult> | The async function to wrap | | provider | string? | Provider label. Defaults to 'tool' | | source | string? | Upstream source tag stored in CER meta | | tags | string[]? | Tags stored in CER meta | | appId | string? | Application ID stored in snapshot | | workflowId | string? | Workflow ID stored in snapshot | | signals | NexArtSignal[]? | Upstream signals bound as context evidence | | attestOptions | AttestOptions? | Node attestation config |

Returns WrapToolResult<TResult>:

| Field | Type | Description | |-------|------|-------------| | result | TResult | Raw tool output | | bundle | CerAiExecutionBundle | Sealed cer.ai.execution.v1 bundle | | certificateHash | string | sha256: hash — primary audit identifier | | receipt | AttestationReceipt? | Present only when attestOptions is supplied |

certifyDecision(params)

Certifies a final agent decision or workflow outcome. Thin async wrapper around @nexart/ai-execution certifyDecision — it does not duplicate or alter any CER hashing or verification logic.

async function certifyDecision(
  params: AgentKitDecisionParams
): Promise<AgentKitDecisionResult>

Defaults inference parameters to { temperature: 0, maxTokens: 0, topP: null, seed: null } as stable, low-variance defaults for decision recording. This does not guarantee deterministic model behavior — it is a recording convention, not a model control guarantee.

Key params:

| Field | Type | Description | |-------|------|-------------| | decision | string | Natural-language decision description (used as prompt/input in the snapshot) | | output | string \| object | Decision output or rationale | | provider | string | AI provider (e.g. 'openai') | | model | string | Model identifier (e.g. 'gpt-4o') | | signals | NexArtSignal[]? | Upstream signals bound as context evidence | | attestOptions | AttestOptions? | Node attestation config |

Returns AgentKitDecisionResult:

| Field | Type | Description | |-------|------|-------------| | bundle | CerAiExecutionBundle | Sealed cer.ai.execution.v1 bundle | | certificateHash | string | sha256: hash — primary audit identifier | | receipt | AttestationReceipt? | Present only when attestOptions is supplied |

Verification

Bundles produced by this package are standard cer.ai.execution.v1 artifacts. They verify exactly like any other NexArt AI CER:

import { verifyCer } from '@nexart/ai-execution';

const result = verifyCer(bundle);
// { ok: true, errors: [], code: 'OK' }

No special verifier is needed. Any existing NexArt verification tooling works without modification.

Backward compatibility

This package does not change any CER, hashing, attestation, or verification semantics. All previously created CERs continue to verify identically.

Version

0.1.1