和 TypeScript / Node 交互
AgentScript 的重点是描述 agent workflow 和模型上下文，而不是替代 JavaScript /
TypeScript 生态。遇到普通编程任务时，可以通过 import tool 调用显式授权的
Node 内置模块，或宿主项目里已经安装的 npm 包。
这篇教程使用 Node 内置模块，因此在当前仓库里不需要额外安装依赖就能运行。
完整源码：../../../tutorials/typescript-interop.as
1. Capability Registry
node: 和 npm: import 默认拒绝。workspace 必须通过
agentscript.npm.json 显式授权：
{
"allow": {
"node": ["crypto"],
"npm": {}
}
}
这份文件应该保持小而可审计。它表示当前 workspace 允许 AgentScript 程序调用
Node 的 crypto 模块，但还没有授权任何 npm 包。
2. 程序
创建 typescript-interop.as，或者直接打开仓库里的
tutorials/typescript-interop.as：
import tool Crypto from "node:crypto"
main agent TypeScriptInterop {
role "Interop example"
description "Use a Node built-in module from AgentScript and return JSON-safe data."
main func(input {
label: string
payload: json
}) {
run_id = Crypto.randomUUID()
digest = Crypto.hash("sha256", input.label, "hex")
return {
label: input.label,
payload: input.payload,
run_id: run_id,
digest: digest
}
}
}
这里没有 generate。这是刻意的：交互能力在调用模型之前也有价值。你可以先
做数据标准化、生成 ID、读取文件，或者调用一个 JSON-friendly 的库，然后在后续
agent 中决定哪些结果要通过 use 进入模型上下文。
3. 运行
agentscript tutorials/typescript-interop.as --quiet --input '{"label":"release-notes","payload":{"version":"0.1.19","kind":"patch"}}'
输出会包含原始 JSON payload，以及 Node 生成的值：
{
"label": "release-notes",
"payload": {
"version": "0.1.19",
"kind": "patch"
},
"run_id": "generated-uuid",
"digest": "sha256-hex-digest"
}
4. 这对 TypeScript 意味着什么
AgentScript 不直接执行 TypeScript source file。它通过 Node module loader
调用 JavaScript 模块。实际使用时，可以这样理解：
-
node:crypto这类 Node 内置模块在授权后可以直接导入。 -
npm 包需要先由宿主项目安装，再写入
agentscript.npm.json。 -
TypeScript 写的库需要先编译或发布为 JavaScript，之后就能按 npm 包调用。
-
函数参数和返回值必须是 JSON-safe：string、number、boolean、
null、数组、
plain object。
如果某个包暴露的是 class、stream、buffer、callback 或 builder object，建议在
TypeScript 侧写一层很薄的 JSON-friendly wrapper，编译成 JavaScript 后再由
AgentScript 导入。
5. 调用 npm 包
对于已经安装的 npm 包，写法一样：
import tool Yaml from "npm:yaml"
main agent ParseYaml {
main func(input {
text: string
}) {
doc = Yaml.parse(input.text)
return {
document: doc
}
}
}
宿主项目需要安装 yaml 并授权：
{
"allow": {
"node": ["crypto"],
"npm": {
"yaml": { "version": "^2.0" }
}
}
}
下一步
完整边界和异常情况见：../npm-tools.md。然后继续阅读 ReAct
教程，看 tool result 如何进入模型上下文。
