快速上手

本页用四步带你从安装走到一个带权限闸门的多轮 agent。

1. 安装

需要 Node.js >=22（当前 provider 包要求）。

pnpm add @lite-agent/sdk @lite-agent/provider zod

@lite-agent/sdk —— 开箱即用的 agent（query / createLiteAgent / tool）；完整转出 @lite-agent/core。
@lite-agent/provider —— 模型接入（anthropic() / openai() / aiSdk()）；支持的协议 · 支持的厂商。
zod —— 工具入参 schema。

2. 第一个 `query()`

query() 运行一个一次性 agent，并流式产出类型化的 AgentEvent：

import { query } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";

for await (const ev of query({
  prompt: "Read README.md and summarize this project.",
  model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  modelName: "claude-sonnet-4-6",
  workdir: process.cwd(),
})) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

开箱即用，agent 已经拥有内置默认工具（bash、read_file、write_file、edit_file、delete_file）。生成器最终 resolve 为一个 LiteAgentResult（messages、text、usage、stopReason）。

3. 添加自定义工具

用 tool() 从 Zod schema 定义工具，通过 tools 传入，并用 allowedTools 收窄模型可见的工具集：

import { query, tool } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";
import { z } from "zod";

const weather = tool(
  "get_weather",
  "Get the weather for a city",
  z.object({ city: z.string() }),
  async ({ city }) => `It's sunny in ${city}.`,
);

for await (const ev of query({
  prompt: "What's the weather in Tokyo?",
  model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  modelName: "claude-sonnet-4-6",
  tools: [weather],
  allowedTools: ["get_weather", "read_file"],
})) {
  if (ev.type === "text_delta") process.stdout.write(ev.text);
}

allowedTools 是对内置工具加自定义工具的精确名称白名单——不在名单里的工具在模型看到之前就被移除。

4. 多轮会话 + 权限闸门

createLiteAgent(cfg) 返回一个有状态、持有当前会话的 LiteAgent——连续的 send() 调用共享同一段对话。加上 policy({ ask: [...] }) 权限闸门（工具名 glob 匹配，优先级 deny > ask > allow）和一个 onApproval 处理器，即可让人进入环路：

import { createLiteAgent, policy } from "@lite-agent/sdk";
import { anthropic } from "@lite-agent/provider";
import { createInterface } from "node:readline/promises";

const agent = createLiteAgent({
  model: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
  modelName: "claude-sonnet-4-6",
  workdir: process.cwd(),
  // Every bash / write_file / edit_file call pauses for approval.
  permission: policy({ ask: ["bash", "write_file", "edit_file", "delete_file"] }),
  onApproval: {
    async request(call) {
      const rl = createInterface({ input: process.stdin, output: process.stdout });
      const answer = await rl.question(`Allow ${call.name} ${JSON.stringify(call.input)}? [y/N] `);
      rl.close();
      return answer.trim().toLowerCase() === "y" ? "allow" : "deny";
    },
  },
});

const first = await agent.send("Create hello.txt with a short greeting.");
console.log(first.text);

const second = await agent.send("Now read it back to me."); // same session
console.log(second.text);

当模型调用 write_file 时，内核发出 approval_request 事件、挂起该工具调用，等待你的处理器返回 "allow" 或 "deny"。

Tip

LiteAgent 还提供会话管理：resume(id)、clear()、listSessions()、deleteSession(id)，通过 listCheckpoints(id) / restore(id, seq) 做时间回溯，以及手动 compact()。见会话与检查点。

另请参阅

代理循环 —— 内核轮次循环如何工作。
事件 —— 完整的 AgentEvent 参考。
权限 —— 内容级规则、审计与试运行。
模型 provider —— Anthropic、OpenAI 及 OpenAI 兼容本地端点。
核心策略 —— 用内核原语构建自己的 agent。

query() 与 createLiteAgent() 统一使用 workdir、system；旧的 cwd、systemPrompt 仍兼容，但冲突配置会报错。Shell 和文件修改默认需要审批；OS 隔离仍需配置沙箱，工作目录本身不能限制 Shell。普通接入先使用 createLiteAgent、send、subscribe、close，底层组装能力按需使用 @lite-agent/core。

需要统一修改默认 .lite-agent 目录名称或编码持久化数据，请参阅存储与命名空间。

#快速上手

#1. 安装

#2. 第一个 query()

#3. 添加自定义工具

#4. 多轮会话 + 权限闸门