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
  })

  async deploy(config: AgentConfig): Promise<DeployedAgent>
  async listAgents(): Promise<RuntimeAgent[]>
  async getAgent(agentId: string): Promise<DeployedAgent>
  async deleteAgent(agentId: string): Promise<void>
}

interface AgentConfig {
  // Identity
  name: string                    // 3-64 chars, lowercase, hyphens only
  displayName: string             // 3-100 chars
  description: string             // 10-500 chars
  longDescription?: string        // Optional longer description
  
  // Core
  agentType?: 'llm' | 'planner'  // Default: 'llm'
  instruction: string             // Agent system prompt
  model: string                   // e.g., 'claude-3.5-sonnet'
  
  // Schemas
  inputSchema: InputSchema | Record<string, unknown>
  outputSchema: OutputSchema | Record<string, unknown>
  
  // Tools
  tools?: unknown[]               // Functions, OpenAPI, MCP
  
  // Runtime
  timeout?: number                // Default: 60
  memoryMb?: number              // Default: 512
  minInstances?: number          // Default: 0
  maxInstances?: number          // Default: 10
  
  // Versioning
  version: string                 // Semantic version
  changelog?: string              // Release notes
  
  // Compliance
  hipaaCompliant?: boolean       // Default: true
}

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' },
})

Field Types

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 Model

const agents = await client.listAgents()
for (const agent of agents) {
  console.log(`${agent.name}: ${agent.deploymentStatus}`)
}

const agent = await client.getAgent('agent-id-or-slug')
console.log(agent.id)
console.log(agent.version)
console.log(agent.endpointUrl)

await client.deleteAgent('agent-id-or-slug')

DeploymentResult Model

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
}

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: 'medical-coding',
  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}`)
  }
}