TypeScript SDK

Install

npm install @velerion/sdk

Node 20 or later. The package ships ESM and CommonJS builds and its own type declarations.

Define an agent

src/agents/support-triage.ts

import { defineAgent, mcp, tool } from '@velerion/sdk';
import { z } from 'zod';

export default defineAgent({
  name: 'support-triage',
  model: 'claude-opus-5',
  instructions: `
    Classify inbound support tickets by urgency and product area.
    Cite the ticket fields that drove your decision. If the ticket is
    ambiguous, say so rather than guessing.
  `,
  tools: [
    mcp('velerion/postgres', {
      connection: 'warehouse-ro',
      tools: ['query'],
    }),
    tool({
      name: 'escalate',
      description: 'Page the on-call engineer for a P1 ticket.',
      input: z.object({
        ticketId: z.string(),
        reason: z.string().min(20),
      }),
      async run({ ticketId, reason }, ctx) {
        ctx.logger.info('escalating', { ticketId });
        await pager.page({ ticketId, reason });
        return { paged: true };
      },
    }),
  ],
});

Call a deployed agent

import { Velerion } from '@velerion/sdk';

const velerion = new Velerion({
  // Falls back to VELERION_TOKEN, then the local CLI session.
  environment: 'prod',
});

const run = await velerion.agents.run('support-triage', {
  input: { ticket: await loadTicket(id) },
  metadata: { requestId },
});

console.log(run.output, run.usage.totalTokens);

Streaming

const stream = await velerion.agents.stream('support-triage', {
  input: { ticket },
});

for await (const event of stream) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.delta);
      break;
    case 'tool_call':
      console.error(`→ ${event.name}`);
      break;
    case 'error':
      throw new Error(event.message);
  }
}

Always handle the error event. A stream that ends without a done event and without an error means the connection dropped, and the run may still be executing server-side — use velerion.runs.get(run.id) to find out.

Error handling

import { VelerionError, RateLimitError } from '@velerion/sdk';

try {
  await velerion.agents.run('support-triage', { input });
} catch (error) {
  if (error instanceof RateLimitError) {
    // `retryAfterMs` is derived from the Retry-After header.
    await sleep(error.retryAfterMs);
  } else if (error instanceof VelerionError) {
    logger.error({ status: error.status, requestId: error.requestId }, error.message);
  } else {
    throw error;
  }
}

error.requestId is the value to quote in a support ticket; it maps directly to an entry in the audit log.

Testing agents locally

velerion dev --agent support-triage

This runs the agent in-process against your local tool implementations while resolving MCP servers from the dev environment. Tool calls are printed with their arguments, which is usually enough to diagnose a bad allow-list without opening the Console.