JavaScript SDK

1npm install @inferencesh/sdk

1import { inference } from '@inferencesh/sdk';2import type { Task, InferenceConfig } from '@inferencesh/sdk';

1import {2  AppStatusActive,3  AppStatusDeprecated,4  AppStatusMaintenance,5  AppStatusRetired,6} from '@inferencesh/sdk';78const app = await client.apps.getByName('myteam/my-app');9const versions = await client.apps.listVersions(app.id);1011// Promote a staged deploy to current (same as the version picker in the web app)12await client.apps.setCurrentVersion(app.id, versions.items[0].id);1314// Mark deprecated while keeping runs working (see Apps REST API — lifecycle status)15await client.apps.updateStatus(app.id, AppStatusDeprecated, 'Use myteam/flux-v2 instead');1617// Temporarily block new runs18await client.apps.updateStatus(app.id, AppStatusMaintenance, 'Upgrading GPU drivers');1920// Permanently retire (excluded from store/search; historical tasks remain)21await client.apps.updateStatus(app.id, AppStatusRetired, 'Replaced by myteam/flux-v2');

1import type { StoreCategoryDTO, StoreTagDTO } from '@inferencesh/sdk';23const { data: categories } = await client.http.request<StoreCategoryDTO[]>(4  'get',5  '/store/categories',6);7const { data: tags } = await client.http.request<StoreTagDTO[]>('get', '/store/tags');

1const flow = await client.flows.create('image-pipeline');2await client.flows.updateVisibility(flow.id, 'public');34const run = await client.flowRuns.create(flow.id, { text: 'hello' });

1const { results } = await client.search.suggest({2  query: 'flux image',3  context: 'user asked about image models', // optional POST /suggest context; query is embedded first, then context4  scope: ['git:github.com/acme/design', 'lang:typescript'], // optional; environment signals for ranking5  limit: 5,6});7// Result descriptions are clipped to DescriptionLimitListing (200 characters).89for (const hit of results) {10  console.log(`[${hit.type}] ${hit.name} — ${hit.command}`);11}1213// Full-text search in a single collection14const apps = await client.search.search({ q: 'transcribe', type: 'apps', limit: 10 });

1const { data: { user, team } } = await client.teams.me();2const { data: teams } = await client.teams.list();34await client.secrets.create({5  key: 'OPENAI_API_KEY',6  value: 'sk-...',7  description: 'OpenAI',8});910const { data: { items: keys } } = await client.apiKeys.list({ limit: 50 });11const { data: newKey } = await client.apiKeys.create({12  name: 'deploy-bot',13  scopes: ['tasks:read', 'tasks:write'],14  scope: 'workspace', // optional: 'user' (default) or 'workspace'; a workspace key needs manage_keys15  expires_at: '2026-12-31T00:00:00Z', // optional16});1718const project = await client.projects.create({ name: 'Production' });

1const entry = await client.knowledge.create({2  name: 'deployment-order',3  description: 'Services must deploy in dependency order',4  type: 'observation',5  version: {6    content: {7      path: 'content.md',8      content: '# Deployment Order\n\nDeploy common-go before api.',9    },10    scope: ['git:github.com/acme/api', 'lang:go'], // optional; see Knowledge API — Scoping11  },12});1314const skill = await client.skills.getByName('myteam', 'code-review');15const content = await client.skills.getContent('myteam', 'code-review');16const { items } = await client.skills.listStore({ limit: 20 });

1const caps = await client.credentials.getCapabilities();2const { auth_url } = await client.credentials.connect({3  provider: 'google',4  type: 'oauth',5  scopes: ['https://www.googleapis.com/auth/spreadsheets'],6});78await client.credentials.checkRequirements({9  secrets: [{ key: 'OPENAI_API_KEY' }],10  credentials: [{ key: 'google.sheets' }],11});1213const linear = await client.mcpServers.get('linear');14const tools = await client.mcpServers.listTools('linear');15const result = await client.mcpServers.callTool('linear', 'list_issues', { limit: 10 });

1const { data: chat } = await client.chats.get('chat_abc123');2const { data: { status } } = await client.chats.getStatus('chat_abc123');3const { data: trace } = await client.chats.getTrace('chat_abc123');4await client.chats.stop('chat_abc123');56const { data: logs } = await client.tasks.getLogs('task_abc123');7const { data: timings } = await client.tasks.getTimings('task_abc123');8const { data: samples } = await client.tasks.getTelemetry('task_abc123');

1import type { TaskFileDTO, DeleteTaskFilesResponse } from '@inferencesh/sdk';2import { TaskFileRoleInput, TaskFileRoleOutput } from '@inferencesh/sdk';34const { data: files } = await client.tasks.files('task_abc123');5const { data: inputs } = await client.tasks.files('task_abc123', TaskFileRoleInput);67const { data: result } = await client.tasks.deleteFiles('task_abc123', TaskFileRoleOutput);8// result.deleted, result.skipped910await client.tasks.delete('task_abc123', { files: true });

1const { data: { items } } = await client.engines.list({ limit: 20 });2const { data: engine } = await client.engines.get('eng_abc123');3console.log(engine.engine_version); // installed inferencesh-engine binary, e.g. "v1.10.15"45await client.engines.drain('eng_abc123');6await client.engines.updateBinary('eng_abc123'); // POST /engines/{id}/update7await client.engines.extend('eng_abc123');89// Cloud engines include nested instance pricing (spot vs on-demand)10if (engine.instance?.rental_type === InstanceRentalTypeSpot) {11  console.log('Spot price (cents/hr):', engine.instance.hourly_price);12}

1import { inference } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45// Run and wait for completion (default)6const result = await client.run({7  app: 'infsh/echo',8  input: { message: 'Hello from JavaScript!' }9});1011console.log(result.output);

1const result = await client.run(2  { app: 'infsh/flux-schnell', input: {...} },3  {4    onUpdate: (update) => {5      console.log(`Status: ${update.status}`);6      if (update.logs?.length) {7        console.log(update.logs[update.logs.length - 1]);8      }9    }10  }11);

1const task = await client.run(2  { app: 'infsh/slow-task', input: {...} },3  { wait: false }4);5console.log(`Task ID: ${task.id}`);

1import { inference } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45// Use an agent you created in the web app6const agent = client.agent('my-org/my-agent@abc123'); // Format: namespace/name@version78const response = await agent.sendMessage('Hello!');9console.log(response);

1const agent = client.agent('my-team/pricing-agent@latest', {2  context: { version_id: 'v1', app_id: 'app_123' },3});

1import { AgentChatProvider, useAgentActions } from '@inferencesh/sdk/agent';2import type { ChatSettingsRequest } from '@inferencesh/sdk';34function ChatControls() {5  const { updateChatSettings, switchAgent } = useAgentActions();67  const rename = () =>8    updateChatSettings({ name: 'Incident triage', visibility: 'team' });910  const clearStaleMemory = () =>11    updateChatSettings({ forget_memory: ['stale_goal'] });1213  const handOff = () => switchAgent('my-team/escalation-agent@latest');1415  // ...16}

1import { useAgentActions } from '@inferencesh/sdk/agent';23const {4  approveTool,5  rejectTool,6  getAlwaysAllowOptions,7  alwaysAllowTool,8  explainTool,9} = useAgentActions();1011async function onApprovalPrompt(toolInvocationId: string) {12  const options = await getAlwaysAllowOptions(toolInvocationId);13  if (!options?.options.length) {14    console.warn(options?.unavailable ?? 'No always-allow choices');15    return;16  }1718  // options.default is the narrowest key that would auto-approve this call again19  const key = options.default ?? options.options[0].key;20  try {21    const result = await alwaysAllowTool(toolInvocationId, { option: key });22    console.log('Saved chat rules:', result?.rules);23  } catch (err) {24    // 409: option stale — re-fetch getAlwaysAllowOptions and try again25    // 400: call no longer awaiting approval26    throw err;27  }28}2930async function onExplainClick(toolInvocationId: string) {31  const { risk_level, explanation, reasoning, risk } = await explainTool(toolInvocationId);32  console.log(risk_level, explanation, reasoning, risk);33}

1import type { AgentPermissions, PolicyRuleDTO } from '@inferencesh/sdk';2import { PolicyKindRemoteExec, PolicyKindTool } from '@inferencesh/sdk';34function describeRule(rule: PolicyRuleDTO): string {5  if (rule.kind === PolicyKindRemoteExec) {6    return `remote command: ${rule.specifier}`;7  }8  if (rule.kind === PolicyKindTool) {9    return `tool: ${rule.specifier}`;10  }11  return `${rule.kind} ${rule.specifier}`;12}1314// Agent template default for new chats (YAML `version.permissions` / AgentDTO)15const defaults: AgentPermissions = { allow_all_tools: true };

1const card = await client.agents.getA2ACard('agent_abc123');2// or by namespace/name ref via GET /agents/{namespace}/{name}/card

1const { data: categories } = await client.agents.getInternalTools();23for (const category of categories) {4  // default_enabled is false for opt-in categories5  console.log(category.id, category.default_enabled);6}

1import { inference, tool, string, internalTools } from '@inferencesh/sdk';23const client = inference({ apiKey: 'inf_your_key' });45// Define tools6const calculator = tool('calculator')7  .describe('Performs math operations')8  .param('expression', string('Math expression'))9  .build();1011// Create ad-hoc agent12const agent = client.agent({13  core_app: { ref: 'infsh/claude-sonnet-4@latest' },14  name: 'Math Assistant',15  system_prompt: 'You help with math. Use the calculator tool.',16  tools: [calculator],17  internal_tools: internalTools().memory().build(),18});1920const response = await agent.sendMessage('What is 42 * 17?');

1await agent.sendMessage('Explain quantum computing', {2  onDelta: (d) => {3    // d.delta is this batch, d.output everything so far for d.messageId4    process.stdout.write(d.delta.response ?? '');5  },6  onMessage: (msg) => {7    if (msg.content) {8      for (const c of msg.content) {9        if (c.type === 'text' && c.text) {10          process.stdout.write(c.text);11        }12      }13    }14  },15  onToolCall: async (call) => {16    console.log(`\n[Tool: ${call.name}]`);17    // Execute the tool and submit its result string18    const result = await executeMyTool(call.name, call.args);19    await agent.submitToolResult(call.id, result);2021    // A result can carry files uploaded first with client.files.upload:22    // const ref = await client.files.upload(pngBlob);23    // await agent.submitToolResult(call.id, 'Screenshot attached.', [ref]);24    25    // For widget interactions, you can also pass action + form_data:26    // await agent.submitToolResult(call.id, {27    //   action: { type: 'confirm' },28    //   form_data: { name: 'John', email: '[email protected]' }29    // });30  },31});

1// From Blob2const imageBlob = new Blob([imageBuffer], { type: 'image/png' });3const response = await agent.sendMessage('What\'s in this image?', {4  files: [imageBlob]5});67// From data URI8const response = await agent.sendMessage('Analyze this', {9  files: ['data:image/png;base64,iVBORw0KGgo...']10});1112// Reuse an uploaded FileRef without re-uploading13const ref = await agent.uploadFile(imageBlob, { filename: 'photo.png' });14await agent.sendMessage('Summarize this', { files: [ref] });

1const chat = await agent.getChat();2console.log(chat?.channel_context?.channel_type); // "slack"

1const output = await agent.run('Summarize this document in JSON');2console.log(output);

1// Get current chat2const chat = await agent.getChat();3console.log(`Chat ID: ${chat?.id}`);4console.log(`Messages: ${chat?.messages.length}`);56// Stop generation7await agent.stopChat();89// Start fresh10agent.reset();1112// Cleanup streams13agent.disconnect();

1import { InterruptResourceHookEvent, InterruptResourceToolInvocation } from '@inferencesh/sdk';23// List pending interrupts for a run (GET /agent-runs/{runId}/interrupts)4const { data: pending } = await client.agents.listRunInterrupts('ar_abc123');56for (const interrupt of pending ?? []) {7  if (interrupt.resource_type === InterruptResourceHookEvent) {8    console.log('Hook gate:', interrupt.meta);9  }10}1112// Resolve with allow or deny (POST /interrupts/{id}/resolve)13const { data: resolved } = await client.agents.resolveInterrupt('int_abc123', 'allow');1415// From the Agent SDK helper (same endpoints)16await agent.resolveInterrupt('int_abc123', 'deny');

1import type { ToolInvocationDTO } from '@inferencesh/sdk';2import {3  parseMCPInputState,4  elicitParams,5  isURLElicitation,6  useAgentActions,7} from '@inferencesh/sdk/agent';89function MCPInputForm({ invocation }: { invocation: ToolInvocationDTO }) {10  const { submitMCPInput } = useAgentActions();11  const state = parseMCPInputState(invocation.data);12  if (!state) return null;1314  async function submitLogin() {15    await submitMCPInput(invocation.id, {16      login: { action: 'accept' },17    });18  }1920  return (21    <>22      {Object.entries(state.input_requests).map(([key, request]) => {23        const params = elicitParams(request);24        if (!params) return null;25        if (isURLElicitation(params)) {26          return (27            <a key={key} href={params.url} target="_blank" rel="noreferrer">28              {params.message}29            </a>30          );31        }32        // Render a form from params.requestedSchema, then:33        // await submitMCPInput(invocation.id, { [key]: { action: 'accept', content: { field: value } } });34        return <p key={key}>{params.message}</p>;35      })}36      <button type="button" onClick={submitLogin}>37        Continue38      </button>39    </>40  );41}

1const agent = client.agent('my-org/support@latest');23// After you locate the awaiting_input MCP invocation on a message:4await agent.submitMCPInput('tinv_abc123', {5  step_a: { action: 'accept', content: { email: '[email protected]' } },6  step_b: { action: 'decline' },7});

1import {2  tool, appTool, agentTool, callTool, httpTool, mcpTool, webhookTool, internalTools,3  string, number, integer, boolean, enumOf, array, object, optional,4  CredentialProviderGoogle,5} from '@inferencesh/sdk';

1import {2  CredentialProviderMCP,3  CredentialStatusConnected,4  EngineStatusDisconnected,5  CloudAWS,6  InstanceStatusRunning,7  InstanceRentalTypeOnDemand,8  InstanceRentalTypeSpot,9  ToolParamTypeString,10  ToolParamTypeObject,11  ToolAuthTypeNone,12  ToolAuthTypeCredential,13  ToolAuthTypeBearer,14  ToolAuthTypeAPIKey,15} from '@inferencesh/sdk';

1import {2  ResourceConcurrency,3  ResourceFeatureSeedance,4  EntitlementTypeLimit,5  EntitlementSourceTier,6  type EntitlementDTO,7  type EntitlementErrorMeta,8} from '@inferencesh/sdk';910const ent: EntitlementDTO = {11  resource: ResourceConcurrency,12  type: EntitlementTypeLimit,13  limit: 3,14  source: EntitlementSourceTier,15};

1import { InferenceError, type EntitlementErrorMeta } from '@inferencesh/sdk';23try {4  await client.tasks.run({ app: 'my-app', input: {} });5} catch (e) {6  if (e instanceof InferenceError) {7    const body = JSON.parse(e.responseBody);8    const meta: EntitlementErrorMeta = body.meta ?? body.error?.meta ?? {};9    if (meta.upgrade_available) {10      console.log(meta.resource_label, meta.addon_plan_name);11    }12  }13}

1// Client tool (runs in your code)2const search = tool('search_files')3  .describe('Search for files')4  .param('pattern', string('Glob pattern'))5  .param('recursive', optional(boolean('Search subdirs')))6  .build();78// App tool (calls another inference app)9const generate = appTool('generate', 'infsh/flux-schnell@latest')10  .describe('Generate an image')11  .param('prompt', string('Image description'))12  .build();1314// Agent tool (delegates to sub-agent)15const researcher = agentTool('research', 'my-org/researcher@v1')16  .describe('Research a topic')17  .param('topic', string('Topic'))18  .build();1920// Authenticated HTTP (callTool and httpTool are aliases)21const getData = httpTool('get_data', 'https://api.example.com/data')22  .describe('Fetch data from the API')23  .method('GET')24  .auth({ bearer: 'my_api_key' })25  .build();2627// OAuth: runtime injects the caller's own connected account's access token28const gmailSend = httpTool('gmail_send', 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send')29  .describe('Send email via Gmail')30  .method('POST')31  .auth({ credential: CredentialProviderGoogle })32  .build();3334// Webhook tool (calls external API)35const notify = webhookTool('slack', 'https://hooks.slack.com/...')36  .describe('Send Slack message')37  .secret('SLACK_SECRET')38  .param('message', string('Message'))39  .build();4041// Internal tools config42const internals = internalTools().memory().plan().build();4344// Meta tools are opt-in (search_tools, list_tools, execute_tool)45const withMeta = internalTools().meta().build();

1import type {2  TaskDTO,3  ChatDTO,4  ChatMessageDTO,5  ChannelContext,6  AgentTool,7  AppStatus,8  TaskStatusCompleted,9  TaskStatusFailed,10} from '@inferencesh/sdk';11import {12  AppStatusActive,13  AppStatusDeprecated,14  AppStatusMaintenance,15  AppStatusRetired,16} from '@inferencesh/sdk';1718// Check task status19if (result.status === TaskStatusCompleted) {20  console.log('Done!');21} else if (result.status === TaskStatusFailed) {22  console.log('Failed:', result.error);23}2425// App lifecycle status (on AppDTO.status)26if (app.status === AppStatusDeprecated) {27  console.log(app.status_message);28}

1import type { MeResponse } from '@inferencesh/sdk';23const { data: me } = await client.teams.me(); // Response<MeResponse>4const caps = me.team_view?.can ?? [];

1import type { CredentialConfigDTO, CredentialDTO } from '@inferencesh/sdk';2import { CredentialScopeUser } from '@inferencesh/sdk';34function connectLabel(config: CredentialConfigDTO): string {5  if (config.connection_scope === CredentialScopeUser) {6    return `connect your ${config.name} account`;7  }8  return `connect ${config.name}`;9}1011function listSubtitle(credential: CredentialDTO): string {12  const accountId = credential.account_identifier ?? '';13  if (credential.scope === CredentialScopeUser) {14    return `${accountId} (your account)`;15  }16  return accountId;17}1819const perUserOAuth: CredentialConfigDTO = {20  slug: 'x',21  provider: 'x',22  type: 'oauth',23  name: 'X',24  short_name: 'X',25  description: '',26  allows_byok: false,27  available: true,28  has_managed: true,29  connection_scope: CredentialScopeUser,30};