Agent SDK

Installation

Choose your preferred package manager:

npm install @hikigai/agent-sdk

yarn add @hikigai/agent-sdk

pnpm add @hikigai/agent-sdk

Quick Start

import {
  AgentClient,
  AgentConfig,
  InputSchema,
  OutputSchema,
  tool,
} from '@hikigai/agent-sdk'

// Initialize client
const client = new AgentClient({
  apiKey: process.env.HIKIGAI_API_KEY,
  projectId: process.env.HIKIGAI_PROJECT_ID,
})

// Deploy an agent
const agent = await client.deploy({
  name: 'medical-coder',
  displayName: 'Medical Coding Assistant',
  description: 'Extracts ICD-10 and CPT codes from clinical notes',
  instruction: 'You are a medical coding expert...',
  model: 'claude-3.5-sonnet',
  version: '1.0.0',
  inputSchema: new InputSchema({
    clinical_note: { type: 'string', required: true },
  }),
  outputSchema: new OutputSchema({
    icd_codes: { type: 'array' },
    cpt_codes: { type: 'array' },
  }),
})

console.log(`Deployed: ${agent.slug}`)

Core Concepts

class AgentClient {
  constructor(options?: {
    apiKey?: string          // API key (or HIKIGAI_API_KEY env var)
    projectId?: string       // Project ID (or HIKIGAI_PROJECT_ID env var)
    baseUrl?: string         // API endpoint
    timeout?: number         // Request timeout in milliseconds
  })

  readonly jobs: JobsClient
  readonly storage: StorageClient

  deploy(config: AgentConfigInput, options?: {
    timeout?: number; pollInterval?: number
  }): Promise<DeployedAgent>
  deployFromFile(filePath: string, options?: {
    name?: string; description?: string
  }): Promise<DeployedAgent>
  listAgents(): Promise<DeployedAgent[]>
  getAgent(agentId: string): Promise<DeployedAgent>
  updateAgent(agentId: string, update: Record<string, unknown>): Promise<DeployedAgent>
  deleteAgent(agentId: string): Promise<void>
  invoke(agentId: string, input: string | Record<string, unknown>, options?: {
    sessionId?: string; provider?: string; model?: string
  }): Promise<Record<string, unknown>>
  stream(agentId: string, input: string | Record<string, unknown>, options?: {
    sessionId?: string; provider?: string; model?: string
  }): AsyncIterable<string>
  getAuthToken(): Promise<AuthTokenResponse>
  close(): void
}

const job = await client.jobs.enqueue('agent.invoke', {
  input: 'Batch-code these notes',
}, { agentId: agent.id, priority: 'standard' })

const detail = await client.jobs.wait(job.id)
console.log(detail.status)

// Also: get, list, cancel, replay, stream

const uploaded = await client.storage.upload('app_123', fileBuffer, 'note.pdf', {
  contentType: 'application/pdf',
})
const { signedUrl } = await client.storage.signedUrl('app_123', uploaded.objectId, 3600)
await client.storage.list('app_123')
await client.storage.delete('app_123', uploaded.objectId)

interface AgentConfig {
  // Identity
  name: string                    // 3-64 chars, lowercase, hyphens only
  displayName: string             // 3-100 chars
  description: string             // 10-500 chars
  longDescription?: string

  // Core
  agentType?: 'llm' | 'sequential' | 'parallel' | 'loop'  // Default: 'llm'
  instruction: string
  model: string                   // Default: 'claude-3.5-sonnet'

  // Schemas
  inputSchema: InputSchema | Record<string, unknown>
  outputSchema: OutputSchema | Record<string, unknown>

  // Modality
  inputModality?: 'text' | 'audio' | 'text_and_audio'   // Default: 'text'
  outputModality?: 'text' | 'audio' | 'text_and_audio'  // Default: 'text'

  // Tools & connectors
  tools?: unknown[]
  connectors?: ConnectorConfig[]
  subAgents?: SubAgentConfig[]

  // Runtime
  timeout?: number                // Default: 60
  memoryMb?: number              // Default: 512
  minInstances?: number          // Default: 0
  maxInstances?: number          // Default: 10

  // Versioning & compliance
  version: string
  changelog?: string
  hipaaCompliant?: boolean       // Default: true
  category?: string
  tags?: string[]
}

Configuration

AgentConfig

Define input and output data structures with full type safety.

import { InputSchema, OutputSchema } from '@hikigai/agent-sdk'

const inputSchema = new InputSchema({
  patient_id: { type: 'string', required: true },
  age: { type: 'integer', required: true, minimum: 0, maximum: 150 },
  symptoms: { type: 'array', items: { type: 'string' } },
})

const outputSchema = new OutputSchema({
  diagnosis: { type: 'string' },
  confidence: { type: 'integer', minimum: 0, maximum: 100 },
  recommendations: { type: 'array' },
})

Tools

Add tools to your agents: functions, OpenAPI specs, or MCP servers.

Function Tools

import { tool } from '@hikigai/agent-sdk'

const searchDatabase = tool(function searchDatabase(query: string): string {
  // Implementation
  return JSON.stringify(results)
})

await client.deploy({
  // ...
  tools: [searchDatabase],
})

OpenAPI Tools

import { OpenAPITool } from '@hikigai/agent-sdk'

const weatherApi = new OpenAPITool({
  specUrl: 'https://api.weather.com/openapi.json',
  operationId: 'getCurrentWeather',
})

Built-in Tools

await client.deploy({
  // ...
  tools: ['web_search', 'execute_code', 'read_file'],
})

DeployedAgent

interface DeployedAgent {
  id: string
  name: string
  slug: string
  version: string
  displayName?: string
  description?: string
  deploymentStatus: 'active' | 'pending' | 'error'
  deploymentType: 'config_based' | 'adk' | 'file'
  endpointUrl?: string
  cloudProvider?: string
  region?: string
  hipaaCompliant: boolean
  hipaaVerified: boolean
  createdAt?: Date
  deployedAt?: Date
}

const agents = await client.listAgents()
const agent = await client.getAgent('agent-id-or-slug')
await client.updateAgent(agent.id, { description: 'Updated description' })
await client.deleteAgent(agent.id)

// Dev helpers
const result = await client.invoke(agent.id, 'Hello')
for await (const chunk of client.stream(agent.id, 'Summarize')) {
  process.stdout.write(chunk)
}

Complete Examples

import {
  AgentClient,
  InputSchema,
  OutputSchema,
  tool,
} from '@hikigai/agent-sdk'

const client = new AgentClient()

// Define tools
const searchCodes = tool(function search(q: string) {
  return JSON.stringify([{ code: 'E11.9', desc: 'Type 2 diabetes' }])
})

// Deploy agent
const agent = await client.deploy({
  name: 'icd-cpt-coder',
  displayName: 'ICD-10 & CPT Coder',
  description: 'Medical coding assistant',
  instruction: 'You are a medical coding expert...',
  model: 'claude-3.5-sonnet',
  category: 'coding-billing',
  version: '1.0.0',
  inputSchema: new InputSchema({
    clinical_note: { type: 'string', required: true },
  }),
  outputSchema: new OutputSchema({
    icd10_codes: { type: 'array' },
    cpt_codes: { type: 'array' },
  }),
  tools: [searchCodes],
  hipaaCompliant: true,
})

console.log(`Deployed: ${agent.slug}`)

Error Handling

import {
  HikigaiError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  DeploymentError,
} from '@hikigai/agent-sdk'

try {
  const agent = await client.deploy(config)
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key')
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter}ms`)
  } else if (error instanceof ValidationError) {
    console.error(`Validation error: ${error.message}`)
  } else if (error instanceof HikigaiError) {
    console.error(`API error: ${error.message}`)
  }
}