Skip to main content

Runtime SDK

@nambikk/sdk is the supported headless browser boundary for conversation runtime behavior.

It covers:

  • session bootstrap;
  • open and resume;
  • messages, conversation attachments, and structured card interactions;
  • inline and streamed responses;
  • reconnect and history reconciliation;
  • progress, typing, and normalized runtime errors.

It intentionally does not expose Studio authoring, tenant administration, operator actions, analytics, audit inspection, credentials, or internal debug surfaces.

Install the package and follow its versioned package README for the current API:

npm install @nambikk/sdk

The default widget is a reference UI built on the same runtime boundary.

Conversation clients can upload a supported file, include the returned attachment in sendMessage, render attachments from message history, and download the original bytes. See the versioned package README for the exact types and methods.

Agentic execution​

The conversation-level agent runtime uses a model-driven tool loop. Approved tools reuse existing API actions and MCP integrations. The model can choose tools from their descriptions and schemas, observe results, and continue without a predefined journey for every request. Existing capabilities remain reusable prescribed processes.

Large approved catalogs are grouped into namespaces and searched iteratively, so the model receives only relevant tool schemas. Standard MCP servers work as they are: Nambikk can infer groups from their tool names and descriptions, while an optional MCP metadata extension can provide richer grouping. Discovery never grants access; only reviewed tool bindings are searchable.

The existing conversation client exposes an optional agentRuntime; the React adapter adds useNambikkRun and AgentRunView for public activity, approvals, inputs, and results. Tools and capabilities share the same conversation runtime. Follow the matching package README for setup, structured approval submissions, custom rendering, and host record-refresh events.

Input interactions may provide saved initialValues for their declared fields. The React task view uses them to prefill a form and preserves unsent edits while the same interaction remains pending. A new interaction or a reloaded view starts from the server's saved values. Custom forms should follow the same behavior and submit only after the participant acts on the current interaction. This form data does not expose private agent captures or their audit history.

In transcript UIs, associate AgentRunView with metadata.run_id and render it once beside the latest assistant message for that run. Ordinary clarification prompts arrive as assistant messages and are answered through the normal composer; inline forms are reserved for structured multi-field input. The reference view keeps activity collapsed, hides internal model-selection steps, and shows exact approvals explicitly. For a quiet consumer chat, set showActivity={false} and showEvidence={false}; pending approvals and structured input still render. The Nambikk widget exposes the same choice as Status only (default) or Expandable activity, while evidence remains in the trusted Review surface.

Knowledge-backed assistant messages may include knowledge_sources in their message metadata: an array of { sourceRef, title, section? }. These are the sources the agent selected for its answer, not a guarantee that every claim was independently verified. The default widget shows a compact “Sources used” line; custom clients can render the same attribution without calling an admin API.

Progress comes from execution events and, where available, measured tool notifications. A brief model-written approach summary is not private reasoning. Tool discovery, tool execution, approvals, verification, and capability activity are separate public events, so an embedded UI can show meaningful progress without exposing chain-of-thought. Assistant-message revisions use the same runtime event stream, enabling a smooth transition from animated status text to the growing answer. Closing a chat view does not stop server-side work; stopping a task does not undo completed changes. Your platform APIs still enforce business rules and record-level access.

Agentic tasks support existing conversation attachments, nested forms, participant-scoped account connection, assigned knowledge, existing capabilities, and bounded task history. The optional @nambikk/sdk/assistant-ui adapter embeds the runtime in assistant-ui without moving tool execution or approval authority into the browser.

External MCP clients use POST /api/v1/agents/:agentSlug/mcp with the same bearer credential and organization header as the HTTP API. The facade starts, observes and steers durable tasks, but cannot approve effects or connect credentials; show those checkpoints in the trusted product UI. Credentials and headers are configured explicitly—automatic MCP OAuth discovery is not exposed.