TypeScript

TypeScript 用の SDK。

@subako-ai/function-sdk を使うと、TypeScript や JavaScript のコードを Function package として実行できます。tool で定義したものが、それぞれ Agent の呼び出せる Function になります。

JavaScript の Package はすべて、ビルド済みの同じランタイム Module を共有します。build はコードを 1 つにまとめてバイトコードにコンパイルし、ランタイムはそれを Package の Asset から読み込みます。そのため WebAssembly のツールチェーンは不要で、Node 20 以降があれば十分です。

Package を始める

git clone https://github.com/subako-ai/subako-function-template-typescript orders

package.json と subako-package.json の my-function を書き換え、同じファイルに Package の説明を書きます。自分のプロジェクトを一から設定することもできます。

npm install @subako-ai/function-sdk zod

{
  "compilerOptions": {
    "lib": ["ES2023"],
    "types": ["@subako-ai/function-sdk/env"],
    "strict": true
  }
}

env の型は、ランタイムが提供するグローバルを過不足なく宣言します。そのため DOM や Node の API を使うと、実行時のクラッシュではなく型エラーになります。

Tool

import { serve, tool } from "@subako-ai/function-sdk";
import { z } from "zod";

const lookup = tool({
  name: "lookup",
  description: "Look an order up by its number.",
  input: z.object({ order: z.number().int().describe("the order's number, such as 1042") }),
  output: z.object({ status: z.string(), total_cents: z.number() }),
  run: async ({ order }) => {
    const response = await fetch(`https://api.acme.example/orders/${order}`);
    if (!response.ok) throw new Error(`the orders API answered ${response.status}`);
    return await response.json();
  },
});

serve([lookup]);

input と output には、JSON Schema も出力できる Standard Schema (zod 4、valibot、arktype など) か、素の JSON Schema オブジェクトを渡せます。素の JSON Schema は入出力の形を伝えるだけで、検証は行いません。入力はオブジェクトでなければなりません。
入力は run の前に検証されます。出力も、output が検証を行えるものであれば、それに照らしてチェックされます。
エラーを throw すると呼び出しは失敗し、モデルはそのエラーを読みます。返したオブジェクトは JSON として、文字列はテキストとして送られます。
serve はエントリーポイントで一度だけ呼び、すべての Tool をまとめて渡します。

公式の MCP TypeScript SDK を使いたい場合は、代わりに @subako-ai/function-sdk/mcp の serveMcp で McpServer を提供できます。

ファイル

import { fs } from "@subako-ai/function-sdk";

const csv = fs.readText("/volume/tmp/export.csv");
fs.mkdir("/volume/data/reports");
fs.writeText("/volume/data/reports/q3.md", summary);

fs には readBytes、writeBytes、appendText、remove、stat、exists、list もあります。

HTTP

fetch は Subako を通り、Grant のネットワークと Credential の設定が適用されます。fetch で扱えるのはテキストの本文だけです。Volume のファイルを本文として送る場合や、レスポンスを Volume に保存する場合は http.request を使います。

import { http } from "@subako-ai/function-sdk";

const saved = await http.request({
  url: "https://api.acme.example/exports/q3",
  saveTo: "/volume/tmp/q3.csv",
});
// saved.file: { path: "/volume/tmp/q3.csv", bytes: 48211 }

失敗すると、kind と message を持つ HttpError で reject されます。

画像

import { answer } from "@subako-ai/function-sdk";

return answer({ path }).withImageFile(path);

ランタイムは Node でもブラウザーでもありません。言語そのもののほかに提供するのは、console (stderr に出力)、タイマー、TextEncoder と TextDecoder、crypto.getRandomValues と randomUUID、URL、Headers、Response、AbortController、fetch だけです。npm の package も、これらしか使わないものなら組み込んで実行できますが、Node の module を使うものは動きません。

ビルド

npx @subako-ai/function-sdk build   # dist/ に module.wasm、subako-package.json、assets/ を書き出します
npx @subako-ai/function-sdk pack    # dist/ を <name>.tar.gz にまとめます

build はカレントディレクトリに subako-package.json があることを前提とします。エントリーは、別のファイルを指定しない限り src/index.ts です。アップロードするには、.tar.gz をコンソールから送るか、subako function create dist で dist/ ディレクトリを送ります。