# Vercel AI SDK Minimal Agent

这是文章配套的最小可运行 Agent 示例。它用 Hono 提供 HTTP 服务和一个简单 Web UI，用 Vercel AI SDK 的 `generateText`、`tool`、`isStepCount` 实现工具调用循环。模型入口默认连接本机 OpenAI-compatible 服务，例如 LM Studio 或 Ollama 的 OpenAI-compatible endpoint。

## 运行前提

- Node.js 22+
- pnpm
- 一个本地 OpenAI-compatible 模型服务
- 一个支持 tool calling 的本地模型

最省事的本地路线是先启动 LM Studio 的 Local Server。它默认提供 `http://localhost:1234/v1` 这种 OpenAI-compatible 接口；模型 ID 以 LM Studio 里实际加载的模型名称为准。也可以用 Ollama 的 OpenAI-compatible endpoint，常见地址是 `http://localhost:11434/v1`。

这个 demo 只要求本地运行，不需要注册 Vercel，也不需要部署。浏览器访问 `localhost`，本地 Hono 服务读取 `.env`，再把模型请求发给本机模型服务。

需要注意的是，工具调用依赖模型能力。不是所有本地模型都能稳定生成 tool call；如果页面能打开但 Agent 没有调用工具，优先换一个明确支持工具调用的 instruct 模型，或者再把模型入口换成云厂商 / Vercel AI Gateway。

## 本地运行

```bash
pnpm install
cp .env.example .env
```

编辑 `.env`：

```env
LOCAL_LLM_BASE_URL=http://localhost:1234/v1
LOCAL_LLM_API_KEY=local
LOCAL_LLM_MODEL=你的本地模型 ID
PORT=3333
```

启动：

```bash
pnpm dev
```

`pnpm dev` 会先把 `src/` 里的 TypeScript 编译到 `dist/`，再用 Node.js 启动 HTTP 服务。改完源码后重新执行一次即可。

打开 http://localhost:3333 ，输入类似下面的问题：

```text
客户说 ORD-2026-0001 的耳机已经签收，想退款。请判断是否符合规则，并写一段给客户的回复。
```

页面会显示两部分内容：

- Agent 回复：模型生成的客服判断和回复草稿。
- 工具调用过程：模型调用了哪些工具，每个工具返回了什么。

## 这个 demo 展示了什么

- Web UI 通过 `fetch('/api/agent')` 调本地 HTTP 接口。
- Hono 接住请求，校验 `message`，再调用 `runSupportAgent`。
- `runSupportAgent` 使用 `generateText` 调模型。
- 三个本地函数被包装成 AI SDK tools：查订单、查退款规则、生成回复前检查清单。
- `stopWhen: isStepCount(5)` 允许模型在一次请求里调用工具，再根据工具结果生成最终回答。

## 生产化前还缺什么

这个项目只适合学习机制。真正上线前至少还要补：

- 用户登录和客服权限。
- 真实订单、售后、工单和日志系统。
- 工具调用审计。
- 成本预算和速率限制。
- 高风险动作的人工确认。
- 错误重试和长任务恢复。