Tools

Agent behavior may declare host, callback, MCP, and built-in tools. Tool contracts are part of an immutable Agent revision; changing one publishes a new revision.

Bind a host tool locally

import { defineHostTool, defineJsonSchema } from "@deepnoodle/nvoken";
 
const lookupOrder = defineHostTool({
  mode: "host",
  name: "lookup_order",
  description: "Look up one order by ID.",
  inputSchema: defineJsonSchema({
    type: "object",
    properties: { orderId: { type: "string" } },
    required: ["orderId"],
    additionalProperties: false,
  }),
});
 
const runner = client.inline({
  instructions: "Call lookup_order before answering order questions.",
  model: "anthropic/claude-sonnet-5",
  tools: [lookupOrder],
}).bindTools({
  lookup_order: async ({ orderId }, context) => ({
    orderId,
    state: "ready",
    idempotencyKey: context.toolCallId,
  }),
});
 
console.log(await runner.text("Where is order-42?", { tenant: "acme" }));

The SDK drives bound host tools while the calling process is connected. For a remotely durable integration, use callback delivery or submit host-tool results through the exact API after a Turn reaches waiting.

Make side effects idempotent

nvoken may retry execution and delivery. Use the ToolCall ID as the idempotency key in the system that performs a side effect. Authorize the action against host-owned product data before executing it; nvoken's tenant and actor attribution do not replace product authorization.

Signed callbacks and webhooks

Verify signatures over the raw request body, select the secret by signing key ID and version, return retryable errors only for transient failures, and fold deliveries by their durable sequence rather than arrival order.