@sanvika/agents

Enterprise client SDK for Sanvika Agent Platform (SAP) — decision intelligence for host platforms such as GAP (Digital Political Organization).

This package is a thin, domain-agnostic SDK. Domain intelligence (for example political) is selected by agentId / workflowId after sap install, not shipped inside this npm package.

AI Riya is a separate product. This SDK is not for end-user Riya chat.

Architecture summary

Host platform (GAP, …)
  → @sanvika/agents (this SDK)
    → in-process SAP runtime bridge  OR  legacy HTTP fleet endpoints
      → registries / governance / workflows / providers
        → domain packs (e.g. political)

Agents only: analyze, verify, audit, recommend, generate drafts, summarize, validate, explain.
Agents never: write business databases, appoint office bearers, perform payments, send WhatsApp/email, or approve decisions.

Installation

pnpm add @sanvika/agents
# or
npm install @sanvika/agents

Requires Node.js 18+.

Quick Start

Canonical APIs (in-process runtime)

Bind a SAP runtime bridge from your host (monorepo / platform process), then call:

import {
  setSapRuntime,
  runAgent,
  runWorkflow,
  runAnalysis,
  runAudit,
} from "@sanvika/agents";

// Host supplies the in-process SAP client (e.g. SapSdkClient from platform)
setSapRuntime(sapClient);

const analysis = await runAnalysis({
  agentId: "political.organization",
  input: { subjectRefs: { orgId: "…" }, question: "Summarize readiness gaps" },
});

const eligibility = await runAgent({
  agentId: "political.eligibility",
  capability: "VERIFY",
  input: { subjectRefs: { memberId: "…", vacancyId: "…" } },
});

const audit = await runAudit({
  agentId: "political.readiness",
  input: { subjectRefs: { orgId: "…" } },
});

const workflow = await runWorkflow({
  workflowId: "political.vacancy-analysis",
  input: { subjectRefs: { orgId: "…" } },
  idempotencyKey: "vacancy-1",
});

Without setSapRuntime, canonical methods throw SDK_RUNTIME_NOT_BOUND (HTTP routes for the new APIs are not part of this release).

Server / client class

import { SanvikaAgentsClient } from "@sanvika/agents/server";

const client = SanvikaAgentsClient.fromProcessEnv();
// Prefer: new SanvikaAgentsClient({ runtime: sapClient })

Configuration

| Variable | Purpose | |----------|---------| | CLIENT_ID / NEXT_PUBLIC_CLIENT_ID | Legacy fleet HTTP client id | | SANVIKA_SERVICE_KEY or AGENTS_CLIENT_SECRET | Legacy fleet auth | | AGENTS_URL / NEXT_PUBLIC_AGENTS_URL | Legacy fleet base URL (default production) | | SAP_SDK_DETERMINISTIC=1 | Host runtime: prefer deterministic agent results |

API reference

runAgent(options)

Execute one registered agent (ANALYZE / VERIFY / …).

runWorkflow(options)

Execute a registered multi-step workflow; returns run id, step results, aggregation.

runAnalysis(options)

Semantic helper for analysis-style capabilities (ANALYZE / SUMMARIZE / CLASSIFY).

runAudit(options)

Semantic helper for audit/validate-style agents.

Discovery

• listAgents({ domain? })
• getAgent(agentId)
• listWorkflows({ domain? })
• getRun(runId)

Runtime bridge

• setSapRuntime(bridge)
• getSapRuntime()

Compatibility / legacy shims

These remain exported for migration. They emit deprecation warnings and call the legacy HTTP fleet API:

| Shim | Prefer | |------|--------| | runFleetExpert | runAgent | | suggestFleetExpert | listAgents / getAgent | | runFleetExpertAuto | runAnalysis / runAgent | | buildStructuredPrompt | structured input on runAgent |

Version policy

| Version | Meaning | |---------|---------| | 0.3.x | SAP SDK surface + fleet shims (pre-1.0) | | 1.0.0 | Reserved for production-stable API + service contracts |

This release is 0.3.0, not 1.0.0.

License

MIT © Sanvika Production