Custom tools, guardrails & audit replay
The open contract: register your own tools, gate them with policies, and snapshot writes for replay.
The engine's open contract lets you extend how your data is operated without touching engine code. Three mechanism-level features are available, and all three are off by default: until you opt in, nothing is imported and there's zero runtime overhead.
- Custom tools — register your own business tools beside the generic registry CRUD and introspection tools.
- Guardrail policies — a decision pipeline in front of every tool call (
allow/deny/requireApproval/mask). - Audit diff replay — row
before/aftersnapshots on writes, for forensics and compliance.
Where it fits. The headline scenario is an AI agent operating your business data over MCP:
tools you define, governed by policies you set, with every write backed by diff-able audit evidence.
It's not MCP-exclusive. The same tools run when your own application calls them through the engine
host API (engine.tools.executor); policies gate any path through the tool executor; and audit replay
lives at the data-access boundary, so every write — REST, script hooks, MCP tools, or host code — is
covered.
The engine ships mechanisms only. No business tools or policy rules are built in; business semantics belong to your project.
In this section
- Custom tools — write a tool and its controlled
ctx - Guardrail policies — decisions, approvals, fail-closed behavior
- Audit replay — before/after snapshots
Wiring end to end
// main.ts
import { createEngine } from '@weave-kit/engine';
const engine = await createEngine({
databaseUrl: process.env.DATABASE_URL,
schemaDir: '.',
auth: { source: { 'sk-agent': { id: 'agent-1', roles: ['agent'] } } },
adapters: { mcp: { identities: { alice: { id: 'u-alice', roles: ['agent'] } } } }, // the agent scenario
tools: {
toolsDir: 'tools',
guardrails: { policies: [highValue] },
},
subsystems: { audit: { enabled: true, replay: true } },
});
await engine.app.listen({ port: 3000 });
// agents reach the tool surface at http://localhost:3000/mcp — alice sees reassign_ticket
// approvals: await engine.tools.executor.approvals.approve(key, 'manager')The same surface works without MCP. Invoke a tool from your own host code and policies and audit apply identically:
import { loadToolsDir } from '@weave-kit/engine';
const [tool] = await loadToolsDir('./tools'); // or reuse engine.tools.defs
const result = await engine.tools.executor.execute(tool.definition, { ticket_id: 'T1' }, {
subject: { id: 'u-alice', roles: ['agent'] },
actor: { key: 'host-app', label: 'my-service', onBehalfOf: 'alice' },
action: 'app.tool.reassign_ticket', // you choose the audit action prefix
args: { ticket_id: 'T1' },
});action is supplied by the caller. mcp.tool.<name> is just the prefix the MCP binding composes; a
host caller may use any prefix.
Notes
- Double audit is by design — a custom tool call writes both
mcp.tool.<name>(adapter layer) andcreate/update/delete(data-access layer). The first is call-level evidence, the second write-level. - Audit events (including
before/after) live in PostgreSQL, not git. Git versions yourschema.jsonmetadata (Git-versioned metadata); business-data evidence stays in the audit table.
Related
- MCP — the agent scenario: exposing the tool surface to AI agents
- Audit — the write / tool-call event trail
- Approvals — the human-in-the-loop queue
- Execution & evidence — the pipeline every tool call runs through
- Script subsystem — complementary trust model