SDK & Programmatic Access

npm install @vesper/sdk

import { VesperCodeClient } from '@vesper/sdk'

const client = new VesperCodeClient({
  apiKey: process.env.VESPER_API_KEY,
  cwd: process.cwd(),
})

const result = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Create a simple calculator class',
  handleEvent: (event) => {
    console.log('Event:', event.type)
  },
})

const run1 = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Create a calculator class',
})

const run2 = await client.run({
  agent: 'vesper/base@0.0.16',
  prompt: 'Add unit tests for the calculator',
  previousRun: run1,
})

import type { AgentDefinition } from '@vesper/sdk'

const myAgent: AgentDefinition = {
  id: 'my-custom-agent',
  model: 'openai/gpt-5.3-codex',
  displayName: 'My Custom Agent',
  toolNames: ['read_files', 'write_file'],
  instructionsPrompt: 'You are a helpful coding assistant.',
}

await client.run({
  agent: 'my-custom-agent',
  prompt: 'Help me refactor this code',
  agentDefinitions: [myAgent],
})

import { z } from 'zod/v4'
import { getCustomToolDefinition } from '@vesper/sdk'

const fetchTool = getCustomToolDefinition({
  toolName: 'fetch_api_data',
  description: 'Fetch data from an API endpoint',
  inputSchema: z.object({
    url: z.url(),
    method: z.enum(['GET', 'POST']).default('GET'),
  }),
  execute: async ({ url, method }) => {
    const response = await fetch(url, { method })
    const data = await response.text()
    return [{ type: 'json', value: { data } }]
  },
})

await client.run({
  agent: 'my-custom-agent',
  prompt: 'Fetch the latest data',
  customToolDefinitions: [fetchTool],
})

import { loadLocalAgents, VesperCodeClient } from '@vesper/sdk'

const agents = await loadLocalAgents({ verbose: true })

const client = new VesperCodeClient({ apiKey: process.env.VESPER_API_KEY })
await client.run({
  agent: 'my-local-agent',
  agentDefinitions: Object.values(agents),
  prompt: 'Hello',
})

const client = new VesperCodeClient({
  apiKey: string,        // Required: Your Vesper Code API key
  cwd?: string,          // Working directory for file operations
})