---
title: TypeScript
description: TypeScript 用の SDK。
---

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

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

## Package を始める

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

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

```bash
npm install @subako-ai/function-sdk zod
```

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

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

## Tool

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

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

## ファイル

```ts
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` を使います。

```ts
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 されます。

## 画像

```ts
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 を使うものは動きません。

## ビルド

```bash
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/` ディレクトリを送ります。