Agent SDK Quickstart

The @cloudvera/agent-sdk wraps /api/ai-gateway/agents with typed clients + an approval polling helper. Install, instantiate, register the agent, run a session — five lines per stage. Auth accepts either a dashboard JWT (interactive) or a `cv_` personal access token (issue at Settings → API Keys; scope `agents:write` to operate, `admin` to review approvals or use the kill switch). PATs identify as `apikey:<keyId>` for 4-eyes accounting on approvals.

Features

TypeScript-first

Generated types match the worker contract exactly (re-synced via the CLOUDVERA-AGENT-PLATFORM-INVENTORY pass). Tab-complete every agent / key / session field.

apiKey safety

The CloudVera client redacts apiKey from util.inspect AND JSON.stringify — Sentry breadcrumbs and structured logs never leak the secret.

ESM-only, Node 18+

Native fetch, AbortController-based timeouts, no transitive deps beyond TS dev tooling.

Code Examples

Install

npm install @cloudvera/agent-sdk

Register an agent + run a session

import { CloudVera, AgentClient, SessionClient } from '@cloudvera/agent-sdk';

const cv = new CloudVera({ apiKey: process.env.CLOUDVERA_KEY! });
const agents = new AgentClient(cv);
const sessions = new SessionClient(cv);

// One-time registration
const agent = await agents.create({
  name: 'triage',
  framework: 'custom',
  sessionBudgetUsd: 0.5,
  maxStepsPerSession: 25,
  toolCallPolicy: 'whitelist',
  allowedTools: ['lookup_cve', 'fetch_ticket'],
});

// Per-run session — start() returns the full summary so you can
// self-throttle on remainingBudgetUsd / remainingSteps.
const { session } = await sessions.start(agent.id);

// Each LLM step is recorded so the gateway enforces budget + steps
await sessions.recordStep(agent.id, session.id, {
  costUsd: 0.01,
  tokensUsed: 240,
});

// End the session when your loop terminates
await sessions.end(agent.id, session.id, 'completed');