JavaScript SDK

使用inference.sh JavaScript/TypeScript SDK构建AI应用。

快速开始

bash

npm install @inferencesh/sdk

typescript

import { inference } from '@inferencesh/sdk';

const client = inference({ apiKey: 'inf_your_key' });

// 运行AI应用
const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A sunset over mountains' }
});
console.log(result.output);

安装

bash

npm install @inferencesh/sdk
# 或
yarn add @inferencesh/sdk
# 或
pnpm add @inferencesh/sdk

要求： Node.js 18.0.0+（或支持fetch的现代浏览器）

身份验证

typescript

import { inference } from '@inferencesh/sdk';

// 直接使用API密钥
const client = inference({ apiKey: 'inf_your_key' });

// 从环境变量获取（推荐）
const client = inference({ apiKey: process.env.INFERENCE_API_KEY });

// 前端应用使用（通过代理）
const client = inference({ proxyUrl: '/api/inference/proxy' });

获取API密钥：设置 → API密钥 → 创建API密钥

运行应用

基础执行

typescript

const result = await client.run({
  app: 'infsh/flux-schnell',
  input: { prompt: 'A cat astronaut' }
});

console.log(result.status);  // "completed"
console.log(result.output);  // 输出数据

异步执行（无需等待结果）

typescript

const task = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Drone flying over mountains' }
}, { wait: false });

console.log(`任务ID: ${task.id}`);
// 后续可通过client.getTask(task.id)查询状态

流式进度更新

typescript

const stream = await client.run({
  app: 'google/veo-3-1-fast',
  input: { prompt: 'Ocean waves at sunset' }
}, { stream: true });

for await (const update of stream) {
  console.log(`状态: ${update.status}`);
  if (update.logs?.length) {
    console.log(update.logs.at(-1));
  }
}

运行参数

参数	类型	描述
`app`	string	应用ID（命名空间/名称@版本）
`input`	object	匹配应用 schema 的输入数据
`setup`	object	隐藏的配置参数
`infra`	string	'cloud'（云端）或 'private'（私有部署）
`session`	string	用于有状态执行的会话ID
`session_timeout`	number	空闲超时时间（1-3600秒）

文件处理

自动上传

typescript

const result = await client.run({
  app: 'image-processor',
  input: {
    image: '/path/to/image.png'  // 自动上传
  }
});

手动上传

typescript

// 基础上传
const file = await client.uploadFile('/path/to/image.png');

// 带选项的上传
const file = await client.uploadFile('/path/to/image.png', {
  filename: 'custom_name.png',
  contentType: 'image/png',
  public: true
});

const result = await client.run({
  app: 'image-processor',
  input: { image: file.uri }
});

浏览器文件上传

typescript

const input = document.querySelector('input[type="file"]');
const file = await client.uploadFile(input.files[0]);

会话（有状态执行）

在多次调用间保持工作进程活跃：

typescript

// 启动新会话
const result = await client.run({
  app: 'my-app',
  input: { action: 'init' },
  session: 'new',
  session_timeout: 300  // 5分钟
});
const sessionId = result.session_id;

// 在同一会话中继续执行
const result2 = await client.run({
  app: 'my-app',
  input: { action: 'process' },
  session: sessionId
});

Agent SDK

模板Agent

使用工作区中的预构建Agent：

typescript

const agent = client.agent('my-team/support-agent@latest');

// 发送消息
const response = await agent.sendMessage('Hello!');
console.log(response.text);

// 多轮对话
const response2 = await agent.sendMessage('Tell me more');

// 重置对话
agent.reset();

// 获取聊天历史
const chat = await agent.getChat();

自定义Agent

通过代码创建自定义Agent：

typescript

import { tool, string, number, appTool } from '@inferencesh/sdk';

// 定义工具
const calculator = tool('calculate')
  .describe('Perform a calculation')
  .param('expression', string('Math expression'))
  .build();

const imageGen = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image')
  .param('prompt', string('Image description'))
  .build();

// 创建Agent
const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  system_prompt: 'You are a helpful assistant.',
  tools: [calculator, imageGen],
  temperature: 0.7,
  max_tokens: 4096
});

const response = await agent.sendMessage('What is 25 * 4?');

可用核心应用

模型	应用引用
Claude Sonnet 4	`infsh/claude-sonnet-4@latest`
Claude 3.5 Haiku	`infsh/claude-haiku-35@latest`
GPT-4o	`infsh/gpt-4o@latest`
GPT-4o Mini	`infsh/gpt-4o-mini@latest`

工具构建器API

参数类型

typescript

import {
  string, number, integer, boolean,
  enumOf, array, obj, optional
} from '@inferencesh/sdk';

const name = string('User\'s name');
const age = integer('Age in years');
const score = number('Score 0-1');
const active = boolean('Is active');
const priority = enumOf(['low', 'medium', 'high'], 'Priority');
const tags = array(string('Tag'), 'List of tags');
const address = obj({
  street: string('Street'),
  city: string('City'),
  zip: optional(string('ZIP'))
}, 'Address');

客户端工具（在你的代码中运行）

typescript

const greet = tool('greet')
  .display('Greet User')
  .describe('Greets a user by name')
  .param('name', string('Name to greet'))
  .requireApproval()
  .build();

应用工具（调用AI应用）

typescript

const generate = appTool('generate_image', 'infsh/flux-schnell@latest')
  .describe('Generate an image from text')
  .param('prompt', string('Image description'))
  .setup({ model: 'schnell' })
  .input({ steps: 20 })
  .requireApproval()
  .build();

Agent工具（委托给子Agent）

typescript

import { agentTool } from '@inferencesh/sdk';

const researcher = agentTool('research', 'my-org/researcher@v1')
  .describe('Research a topic')
  .param('topic', string('Topic to research'))
  .build();

Webhook工具（调用外部API）

typescript

import { webhookTool } from '@inferencesh/sdk';

const notify = webhookTool('slack', 'https://hooks.slack.com/...')
  .describe('Send Slack notification')
  .secret('SLACK_SECRET')
  .param('channel', string('Channel'))
  .param('message', string('Message'))
  .build();

内置工具（原生功能）

typescript

import { internalTools } from '@inferencesh/sdk';

const config = internalTools()
  .plan()
  .memory()
  .webSearch(true)
  .codeExecution(true)
  .imageGeneration({
    enabled: true,
    appRef: 'infsh/flux@latest'
  })
  .build();

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  internal_tools: config
});

Agent响应流式传输

typescript

const response = await agent.sendMessage('Explain quantum computing', {
  onMessage: (msg) => {
    if (msg.content) {
      process.stdout.write(msg.content);
    }
  },
  onToolCall: async (call) => {
    console.log(`\n[工具: ${call.name}]`);
    const result = await executeTool(call.name, call.args);
    agent.submitToolResult(call.id, result);
  }
});

文件附件

typescript

// 从文件路径（Node.js）
import { readFileSync } from 'fs';
const response = await agent.sendMessage('What\'s in this image?', {
  files: [readFileSync('image.png')]
});

// 从base64编码
const response = await agent.sendMessage('Analyze this', {
  files: ['data:image/png;base64,iVBORw0KGgo...']
});

// 从浏览器File对象
const input = document.querySelector('input[type="file"]');
const response = await agent.sendMessage('Describe this', {
  files: [input.files[0]]
});

Skills（可复用上下文）

typescript

const agent = client.agent({
  core_app: { ref: 'infsh/claude-sonnet-4@latest' },
  skills: [
    {
      name: 'code-review',
      description: 'Code review guidelines',
      content: '# Code Review\n\n1. Check security\n2. Check performance...'
    },
    {
      name: 'api-docs',
      description: 'API documentation',
      url: 'https://example.com/skills/api-docs.md'
    }
  ]
});

服务器代理（前端应用）

对于浏览器应用，通过后端代理以保护API密钥：

客户端配置

typescript

const client = inference({
  proxyUrl: '/api/inference/proxy'
  // 前端无需配置apiKey
});

Next.js代理（App Router）

typescript

// app/api/inference/proxy/route.ts
import { createRouteHandler } from '@inferencesh/sdk/proxy/nextjs';

const route = createRouteHandler({
  apiKey: process.env.INFERENCE_API_KEY
});

export const POST = route.POST;

Express代理

typescript

import express from 'express';
import { createProxyMiddleware } from '@inferencesh/sdk/proxy/express';

const app = express();
app.use('/api/inference/proxy', createProxyMiddleware({
  apiKey: process.env.INFERENCE_API_KEY
}));

支持的框架

Next.js（App Router & Pages Router）
Express
Hono
Remix
SvelteKit

TypeScript支持

包含完整的类型定义：

typescript

import type {
  TaskDTO,
  ChatDTO,
  ChatMessageDTO,
  AgentTool,
  TaskStatusCompleted,
  TaskStatusFailed
} from '@inferencesh/sdk';

if (result.status === TaskStatusCompleted) {
  console.log('完成!');
} else if (result.status === TaskStatusFailed) {
  console.log('失败:', result.error);
}

错误处理

typescript

import { RequirementsNotMetException, InferenceError } from '@inferencesh/sdk';

try {
  const result = await client.run({ app: 'my-app', input: {...} });
} catch (e) {
  if (e instanceof RequirementsNotMetException) {
    console.log('缺少必要条件:');
    for (const err of e.errors) {
      console.log(`  - ${err.type}: ${err.key}`);
    }
  } else if (e instanceof InferenceError) {
    console.log('API错误:', e.message);
  }
}

人工审批工作流

typescript

const response = await agent.sendMessage('Delete all temp files', {
  onToolCall: async (call) => {
    if (call.requiresApproval) {
      const approved = await promptUser(`是否允许执行${call.name}?`);
      if (approved) {
        const result = await executeTool(call.name, call.args);
        agent.submitToolResult(call.id, result);
      } else {
        agent.submitToolResult(call.id, { error: '用户已拒绝' });
      }
    }
  }
});

CommonJS支持

javascript

const { inference, tool, string } = require('@inferencesh/sdk');

const client = inference({ apiKey: 'inf_...' });
const result = await client.run({...});

参考文档

Agent模式 - 多Agent、RAG、批量处理模式
工具构建器 - 完整的工具构建器API参考
服务器代理 - Next.js、Express、Hono、Remix、SvelteKit配置指南
流式处理 - 实时进度更新和SSE处理
文件处理 - 上传、下载和文件管理
会话 - 带预热工作进程的有状态执行
TypeScript - 类型定义和类型安全模式
React集成 - Hooks、组件和模式

官方文档

JavaScript SDK参考 - 完整API文档
Agent SDK概览 - Agent构建指南
工具构建器参考 - 工具创建指南
服务器代理配置 - 前端集成指南
身份验证 - API密钥配置
流式处理 - 实时更新
文件上传 - 文件处理

javascript-sdk

NPX安装

标签

SKILL.md 内容（中文）

JavaScript SDK

快速开始

安装

身份验证

运行应用

基础执行

异步执行（无需等待结果）

流式进度更新

运行参数

文件处理

自动上传

手动上传

浏览器文件上传

会话（有状态执行）

Agent SDK

模板Agent

自定义Agent

可用核心应用

工具构建器API

参数类型

客户端工具（在你的代码中运行）

应用工具（调用AI应用）

Agent工具（委托给子Agent）

Webhook工具（调用外部API）

内置工具（原生功能）

Agent响应流式传输

文件附件

Skills（可复用上下文）

服务器代理（前端应用）

客户端配置

Next.js代理（App Router）

Express代理

支持的框架

TypeScript支持

错误处理

人工审批工作流

CommonJS支持

参考文档

相关Skills

官方文档